videoinput

Create video input object

Description

A videoinput object represents a connection between MATLAB^® and an image acquisition device.

Creation

Syntax

vid = videoinput(adaptor)

vid = videoinput(adaptor,deviceID)

vid = videoinput(adaptor,deviceID,format)

vid = videoinput(___,Name,Value)

Description

vid = videoinput(adaptor) creates a video input object vid. adaptor is a character vector or string scalar that specifies the name of the adaptor used to communicate with the device. Use imaqhwinfo to determine the adaptors available on your system.

vid = videoinput(adaptor,deviceID) creates a video input object vid, where deviceID is a numeric scalar value that identifies a particular device available through the specified adaptor, adaptor. Use imaqhwinfo(adaptor) to determine the devices available through the specified adaptor. If deviceID is not specified, the first available device ID is used. You can also use a device's name in place of deviceID. If multiple devices have the same name, the first available device is used.

vid = videoinput(adaptor,deviceID,format) creates a video input object vid, where format is a character vector or string scalar that specifies a particular video format supported by the device or the full path of a device configuration file (also known as a camera file). To get a list of the formats supported by a particular device, view the DeviceInfo structure for the device that is returned by imaqhwinfo. Each DeviceInfo structure contains a SupportedFormats field. If format is not specified, the device's default format is used. When the video input object is created, its VideoFormat property contains the format name or device configuration file that you specify.

vid = videoinput(___,Name,Value) creates a video input object and sets additional properties using one or more name-value arguments in addition to the input arguments in previous syntaxes. If an invalid property name or property value is specified, the object is not created. Use tab-completion to see a full list of properties that you can set for your adaptor using name-value arguments.

To view a complete list of video input object functions and properties, use imaqhelp.

Note

The toolbox chooses the first available video source object as the selected source and specifies this video source object's name in the object's SelectedSourceName property. Use getselectedsource(obj) to access the video source object that is used for acquisition.

Properties

General Properties

BayerSensorAlignment — Sensor alignment for Bayer demosaicing

"grbg" (default) | "gbrg" | "rggb" | "bggr"

Sensor alignment for Bayer demosaicing, specified as "grbg", "gbrg", "rggb", or "bggr". If the ReturnedColorSpace property is set to "bayer", then the Image Acquisition Toolbox™ will demosaic Bayer patterns returned by the hardware. This color space setting interpolates Bayer pattern encoded images into standard RGB images. If your camera uses Bayer filtering, the toolbox supports the Bayer pattern and can return color if desired.

In order to perform the demosaicing, the toolbox needs to know the pixel alignment of the sensor. This is the order of the red, green, and blue sensors and is normally specified by describing the four pixels in the upper-left corner of the sensor. It is the band sensitivity alignment of the pixels as interpreted by the camera's internal hardware. You must get this information from the camera's documentation and then specify the value for the alignment, as described in the following table.

There are four possible sensor alignments.

Value	Description
"gbrg"	The 2-by-2 sensor alignment is green blue red green
"grbg"	The 2-by-2 sensor alignment is green red blue green
"bggr"	The 2-by-2 sensor alignment is blue green green red
"rggb"	The 2-by-2 sensor alignment is red green green blue

The value of this property is only used if the ReturnedColorSpace property is set to "bayer".

For examples showing how to convert Bayer images, see Converting Bayer Images.

Data Types: char | string

DeviceID — Image acquisition device ID

1 (default) | nonnegative integer

This property is read-only.

Image acquisition device ID for the specified adaptor, specified as a nonnegative integer. This property identifies the device represented by the video input object.

A device ID is a number, assigned by an adaptor, that uniquely identifies an image acquisition device. The adaptor assigns the first device it detects the identifier 1, the second device it detects the identifier 2, and so on.

You can specify the device ID as an input for the videoinput function when you create a video input object. The object stores the value in the DeviceID property and also uses the value when constructing the default value of the Name property.

To get a list of the IDs of the devices connected to your system, use the imaqhwinfo function, specifying the name of a particular adaptor as an argument.

Data Types: double

FrameGrabInterval — How often to acquire frame from video stream

1 (default) | positive integer.

How often the video input object acquires a frame from the video stream, specified as a positive integer. By default, objects acquire every frame in the video stream, but you can use this property to specify other acquisition intervals.

Note

Do not confuse the frame grab interval with the frame rate. The frame rate describes the rate at which an image acquisition device provides frames, typically measured in seconds, such as 30 frames per second. The frame grab interval is measured in frames, not seconds. If a particular device's frame rate is configurable, the video source object might include the frame rate as a device-specific property.

For example, when you specify a FrameGrabInterval value of 3, the object acquires every third frame from the video stream, as illustrated in this figure. The object acquires the first frame in the video stream before applying the FrameGrabInterval.

You specify the source of the video stream in the SelectedSourceName property.

Data Types: double

FramesAcquired — Total number of frames acquired

0 (default) | nonnegative integer

This property is read-only.

Total number of frames that the object has acquired, regardless of how many frames have been extracted from the memory buffer, specified as a nonnegative integer. The video input object continuously updates the value of the FramesAcquired property as it acquires frames.

Note

When you issue a start command, the video input object resets the value of the FramesAcquired property to 0 (zero) and flushes the buffer.

To find out how many frames are available in the memory buffer, use the FramesAvailable property.

Data Types: double

FramesAvailable — Number of frames available in memory buffer

0 (default) | nonnegative integer

This property is read-only.

Total number of frames that are available in the memory buffer, specified as a nonnegative integer. When you extract data, the object reduces the value of the FramesAvailable property by the appropriate number of frames. You use the getdata function to extract data and move it into the MATLAB workspace.

Note

When you issue a start command, the video input object resets the value of the FramesAvailable property to 0 (zero) and flushes the buffer.

To view the total number of frames that have been acquired since the last start command, use the FramesAcquired property.

Data Types: double

Name — Name of image acquisition object

character vector | string scalar

Name of the image acquisition object, specified as a character vector or string scalar.

The toolbox creates the default name by combining the values of the VideoFormat and DeviceID properties with the adaptor name in this format: VideoFormat + '-' + adaptor name + '-' + DeviceID

Data Types: char | string

NumberOfBands — Number of color bands in data to be acquired

positive integer

This property is read-only.

Number of color bands in the data to be acquired, specified as a positive integer. The toolbox defines band as the third dimension in a 3-D array, as shown in this figure.

The value of the NumberOfBands property indicates the number of color bands in the data returned by getsnapshot, getdata, and peekdata.

Data Types: double

PreviewFullBitDepth — Whether preview data is displayed in full bit depth

"off" (default) | "on"

Whether the image data in the Preview window is being displayed in full bit depth, specified as "off" or "on".

Note

The Image Acquisition Toolbox Preview window supports the display of up to 16-bit image data. The Preview window was designed to only show 8-bit data, but many cameras return 10-, 12-, 14-, or 16-bit data. The Preview window display supports these higher bit-depth cameras. However, larger bit data is scaled to 8-bit for the purpose of displaying previewed data. To capture the image data in the Preview window in its full bit depth for grayscale images, set the PreviewFullBitDepth property to 'on'.

If you set this property to "off", image data in the preview window is scaled down from its bit depth to 8-bit. If you set this property to "on", the image data in the preview window is being captured in its full bit depth.

This property can be set to "on" only when the value of the ReturnedColorspace property is set to "grayscale" and for video formats higher than 8-bit depth.

Data Types: char | string

Previewing — Whether object is currently previewing data in separate window

"off" (default) | "on"

This property is read-only.

Whether the object is currently previewing data in a separate window, specified as "off" or "on".

The object sets the Previewing property to "on" when you call the preview function.

The object sets the Previewing property to "off" when you close the preview window using the closepreview function or by clicking the Close button in the preview window title bar.

Data Types: char

ReturnedColorSpace — Color space used in MATLAB

"grayscale" | "rgb" | "YCbCr" | "bayer"

Color space you want the toolbox to use when it returns image data to the MATLAB workspace, specified as "grayscale", "rgb", "YCbCr", or "bayer". This is only relevant when you are accessing acquired image data with the getsnapshot, getdata, and peekdata functions.

This property can have any of the following values:

Value	Description
"grayscale"	MATLAB grayscale color space.
"rgb"	MATLAB RGB color space.
"YCbCr"	MATLAB YCbCr color space. Note that YCbCr is often imprecisely referred to as YUV. (YUV is similar, but not identical. They differ by the scaling factor applied to the result. YUV refers to a particular scaling factor used in composite NTSC and PAL formats. In most cases, you can specify the YCbCr color space for devices that support YUV.)
"bayer"	Convert grayscale Bayer color patterns to RGB images. The bayer color space option is only available if your camera's default returned color space is grayscale. To use the BayerSensorAlignment property, you must set the ReturnedColorSpace property to bayer.

Note

For some adaptors, such as GigE and GenTL, if you use a format that starts with Bayer (e.g. BayerGB8_640x480), the raw Bayer pattern is automatically converted to color – the ReturnedColorSpace is RGB. If you set the ReturnedColorSpace to "grayscale", you'll get the raw pattern.

For an example showing how to determine the default color space and change the color space setting, see Specifying the Color Space.

Data Types: char | string

ROIPosition — Region-of-interest (ROI) window

[ 0 0 width height ] (default) | 1-by-4 element vector

Region-of-interest acquisition window, specified as a 1-by-4 element vector. The ROI defines the actual size of the frame logged by the toolbox, measured with respect to the top left corner of an image frame.

ROIPosition is specified as a 1-by-4 element vector [XOffset YOffset Width Height].

XOffset	Position of the upper left corner of the ROI, measured in pixels.
YOffset	Position of the upper left corner of the ROI, measured in pixels.
Width	Width of the ROI, measured in pixels. The sum of XOffset and Width cannot exceed the width specified in VideoResolution.
Height	Height of the ROI, measured in pixels. The sum of YOffset and Height cannot exceed the height specified in VideoResolution.

Note

The Width does not include both end points as well as the width between the pixels. It includes one end point, plus the width between pixels. For example, if you want to capture an ROI of pixels 20 through 30, including both end pixels 20 and 30, set an XOffset of 19 and a Width of 11. The same rule applies to height.

In the figure shown above, the width of the captured ROI contains pixels 51 through 170, including both end points, because the XOffset is set to 50 and the Width is set to 120.

Data Types: double

Running — Whether video input object is ready to acquire data

"off" (default) | "on"

This property is read-only.

Whether the video input object is ready to acquire data, specified as "off" or "on".

Along with the Logging property, Running reflects the state of a video input object. The Running property indicates that the object is ready to acquire data, while the Logging property indicates that the object is acquiring data.

The object sets the Running property to "on" when you issue the start command. When Running is "on", you can acquire data from a video source.

The object sets the Running property to "off" when any of the following conditions is met:

• The specified number of frames has been acquired.

• A run-time error occurs.

• You issue the stop command.

When Running is "off", you cannot acquire image data. However, you can acquire one image frame with the getsnapshot function.

Data Types: char

Timeout — Amount of time to wait for image data

10 (default) | positive integer

Amount of time in seconds that the getdata and getsnapshot functions wait for data to be returned, specified as a positive integer. The Timeout property is only associated with these blocking functions. If the specified time period expires, the functions return control to the MATLAB command line.

A timeout is one of the conditions for stopping an acquisition. When a timeout occurs, and the object is running, the MATLAB file function specified by ErrorFcn is called.

Note

The Timeout property is not associated with hardware timeout conditions.

Data Types: double

UserData — Stored data to associate with image acquisition object

any type

Stored data that you want to associate with an image acquisition object, specified as any MATLAB data type.

Note

The object does not use the data in UserData directly. However, you can access the data by referencing the property as you would a field in a MATLAB structure using dot notation.

VideoFormat — Video format or name of device configuration file

character vector

This property is read-only.

Video format used by the image acquisition device or the name of a device configuration file, depending on which you specified when you created the object, specified as a character vector.

Image acquisition devices typically support multiple video formats. When you create a video input object, you can specify the video format that you want the device to use. If you do not specify the video format as an argument, the videoinput function uses the default format. Use the imaqhwinfo function to determine which video formats a particular device supports and find out which format is the default.

As an alternative, you can specify the name of a device configuration file, also known as a camera file or digitizer configuration format (DCF) file. Some image acquisition devices use these files to store device configuration information. The videoinput function can use this file to determine the video format and other configuration information.

Use the imaqhwinfo function to determine if your device supports device configuration files.

Data Types: char

VideoResolution — Width and height of incoming video stream

[width height]

This property is read-only.

Width and height in pixels of the frames in the incoming video stream, specified as a two-element vector [width height].

Note

You specify the video resolution when you create the video input object, by passing in the video format argument to the videoinput function. If you do not specify a video format, the videoinput function uses the default video format. Use the imaqhwinfo function to determine which video formats a particular device supports and find out which format is the default.

Data Types: double

Data Logging Properties

Logging — Whether object is currently logging data

"off" (default) | "on"

This property is read-only.

Whether video input object is currently logging data, specified as "off" or "on".

When a trigger occurs, the object sets the Logging property to "on" and logs data to memory, a disk file, or both, depending on the value of the LoggingMode property.

The object sets the Logging property to "off" when it acquires the requested number of frames, an error occurs, or you issue a stop command.

To acquire data when the object is running but not logging, use the peekdata function. The peekdata function does not guarantee that all the requested image data is returned. To acquire all the data without gaps, you must have the object log the data to memory or to a disk file.

Data Types: char

LoggingMode — Destination for acquired data

"memory" (default) | "disk" | "disk&memory"

Destination for acquired data, specified as "memory", "disk", or "disk&memory". This property specifies where you want the video input object to store the acquired data. You can specify any of the following values:

Value	Description
"disk"	Log acquired data to a disk file.
"disk&memory"	Log acquired data to both a disk file and to a memory buffer.
"memory"	Log acquired data to a memory buffer.

If you select "disk" or "disk&memory", you must specify the AVI file object used to access the disk file as the value of the DiskLogger property.

Note

When logging data to memory, you must extract the acquired data in a timely manner with the getdata function to avoid using up all the memory that is available on your system.

Note

The peekdata function does not return any data while running if in disk logging mode.

Data Types: char | string

DiskLogger — MATLAB VideoWriter file used to log data

[] (default) | VideoWriter object

MATLAB VideoWriter file used to log data, specified as a VideoWriter object. This property specifies the VideoWriter file object used to log data when the LoggingMode property is set to "disk" or "disk&memory".

For the best performance, logging to disk requires a MATLAB VideoWriter object, which is a MATLAB object, not an Image Acquisition Toolbox object. After you create and configure a VideoWriter object, you can specify it with the DiskLogger property.

A MATLAB VideoWriter object specifies the file name and other characteristics. For example, you can use VideoWriter properties to specify the profile used for data compression and the desired quality of the output. For complete information about the VideoWriter object and its properties, see the VideoWriter.

Note

Do not use the variable returned by the VideoWriter function to perform any operation on a VideoWriter file while it is being used by a video input object for data logging. For example, do not change any of the VideoWriter file properties, add frames, or close the object. Your changes could conflict with the video input object.

After Logging and Running are off, it is possible that the DiskLogger might still be writing data to disk. When the DiskLogger finishes writing data to disk, the value of the DiskLoggerFrameCount property should equal the value of the FramesAcquired property. Do not close or modify the DiskLogger until this condition is met.

For more information about logging image data using a VideoWriter file, see Logging Image Data to Disk.

Note

The peekdata function does not return any data while running if in disk logging mode.

DiskLoggerFrameCount — Number of frames written to disk

nonnegative integer

This property is read-only.

Number of frames written to disk, specified as any nonnegative integer. This property indicates the current number of frames written to disk by the DiskLogger. This value is only updated when the LoggingMode property is set to "disk" or "disk&memory".

After Logging and Running are off, it is possible that the DiskLogger might still be writing data to disk. When the DiskLogger finishes writing data to disk, the value of the DiskLoggerFrameCount property should equal the value of the FramesAcquired property. Do not close or modify the DiskLogger until this condition is met.

Data Types: double

Event and Callback Properties

EventLog — Information about events

array of structures

This property is read-only.

Information about events, specified as an array of structures. Each structure in the array represents one event. Events are recorded in the order in which they occur. The first EventLog structure reflects the first event recorded, the second EventLog structure reflects the second event recorded, and so on.

Each event log structure contains two fields: Type and Data.

The Type field stores a character array that identifies the event type. The Image Acquisition Toolbox defines many different event types, listed in this table. Note that not all event types are logged.

Event Type	Description	Included in Log
Error	Run-time error occurred. Run-time errors include timeouts and hardware errors.	Yes
Frames Acquired	The number of frames specified in the FramesAcquiredFcnCount property has been acquired.	No
Start	Object was started by calling the start function.	Yes
Stop	Object stopped executing.	Yes
Timer	Timer expired.	No
Trigger	Trigger executed.	Yes

The Data field stores information associated with the specific event. For example, all events return the absolute time the event occurred in the AbsTime field. Other event-specific fields are included in Data. For more information, see Retrieving Event Information.

EventLog can store a maximum of 1000 events. If this value is exceeded, then the most recent 1000 events are stored.

Data Types: struct

ErrorFcn — Callback function to execute when run-time error occurs

imaqcallback (default) | character vector | function handle | cell array

Callback function to execute when an error event occurs, specified as a character vector, function handle, or cell array. A run-time error event is generated immediately after a run-time error occurs.

Run-time errors include hardware errors and timeouts. Run-time errors do not include configuration errors such as setting an invalid property value.

Run-time error event information is stored in the EventLog property. You can retrieve any error message with the Data.Message field of EventLog.

Note

Callbacks, including ErrorFcn, are executed only when the video object is in a running state. If you need to use the ErrorFcn callback for error handling during previewing, you must start the video object before previewing. To do that without logging data, use a manual trigger.

Data Types: char | string | cell | function_handle

FramesAcquiredFcn — Callback function to execute when specified number of frames have been acquired

[] (default) | character vector | function handle | cell array

Callback function to execute every time a predefined number of frames have been acquired, specified as a character vector, function handle, or cell array.

A frames acquired event is generated immediately after the number of frames specified by the FramesAcquiredFcnCount property is acquired from the selected video source. This event executes the MATLAB file specified for FramesAcquiredFcn.

Use the FramesAcquiredFcn callback if you must access each frame that is acquired. If you do not have this requirement, you might want to use the TimerFcn property.

Frames acquired event information is not stored in the EventLog property.

Data Types: char | string | cell | function_handle

FramesAcquiredFcnCount — Number of frames that must be acquired before frames acquired event is generated

0 (default) | positive integer

Number of frames to acquire from the selected video source before a frames acquired event is generated, specified as a positive integer.

The object generates a frames acquired event immediately after the number of frames specified by FramesAcquiredFcnCount is acquired from the selected video source.

Data Types: double

StartFcn — Callback function to execute when start event occurs

[] (default) | character vector | function handle | cell array

Callback function to execute when a start event occurs, specified as a character vector, function handle, or cell array. A start event occurs immediately after you issue the start command.

The StartFcn callback executes synchronously. The toolbox does not set the object's Running property to "on" until the callback function finishes executing. If the callback function encounters an error, the object never starts running.

Start event information is stored in the EventLog property.

Data Types: char | string | cell | function_handle

StopFcn — Callback function to execute when stop event occurs

[] (default) | character vector | function handle | cell array

Callback function to execute when a stop event occurs, specified as a character vector, function handle, or cell array. A stop event occurs immediately after you issue the stop command.

The StopFcn callback executes synchronously. Under most circumstances, the image acquisition object will be stopped and the Running property will be set to "off" by the time the MATLAB file completes execution.

Stop event information is stored in the EventLog property.

Data Types: char | string | cell | function_handle

TimerFcn — Callback function to execute when timer event occurs

[] (default) | character vector | function handle | cell array

Callback function to execute when a timer event occurs, specified as a character vector, function handle, or cell array. A timer event occurs when the time period specified by the TimerPeriod property expires.

The toolbox measures time relative to when the object is started with the start function. Timer events stop being generated when the image acquisition object stops running.

Note

Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value you specify is too small.

Data Types: char | string | cell | function_handle

TimerPeriod — Number of seconds between timer events

1 (default) | positive value greater than 0.01

Amount of time, in seconds, that must pass before a timer event is triggered, specified as a positive value greater than 0.01.

The toolbox measures time relative to when the object is started with the start function. Timer events stop being generated when the image acquisition object stops running.

Note

Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value you specify is too small.

Data Types: double

TriggerFcn — Callback function to execute when trigger event occurs

[] (default) | character vector | function handle | cell array

Callback function to execute when a trigger event occurs, specified as a character vector, function handle, or cell array. The toolbox generates a trigger event when a trigger is executed based on the configured TriggerType, and data logging is initiated.

Under most circumstances, the MATLAB file callback function is not guaranteed to complete execution until sometime after the toolbox sets the Logging property to "on".

Trigger event information is stored in the EventLog property.

Data Types: char | string | cell | function_handle

Trigger Properties

TriggerType — Type of trigger used by video input object

"immediate" (default) | "hardware" | "manual"

This property is read-only.

Type of trigger used by the video input object, specified as "immediate", "hardware", or "manual". Triggers initiate data acquisition.

You use the triggerconfig function to specify one of the following values for this property.

TriggerType Value	Description
"hardware" (if available for your device)	Trigger executes when a specified condition is met. You specify the condition using the TriggerCondition property and you specify the hardware source to monitor for the condition in the TriggerSource property. You use the triggerconfig function to set the values of these properties.
"immediate"	Trigger executes immediately after you call the start function.
"manual"	Trigger executes immediately after you call the trigger function.

Data Types: char

TriggerCondition — Required condition before trigger event occurs

character vector

This property is read-only.

Condition that must be met, via the TriggerSource, before a trigger event occurs, specified as a character vector. The trigger conditions that you can specify depend on the value of the TriggerType property.

TriggerType Value	Conditions Available
"hardware" (if available for your device)	Device-specific. For example, some Matrox® hardware supports conditions such as "risingEdge" and "fallingEdge". Use the triggerinfo function to view a list of valid values to use with your image acquisition hardware.
"immediate"	"none"
"manual"	"none"

You must use the triggerconfig function to set the value of this property.

Data Types: char

TriggerSource — Hardware source to monitor for trigger conditions

character vector

This property is read-only.

Hardware source the image acquisition object monitors for trigger conditions, specified as a character vector. When the condition specified in the TriggerCondition property is met, the object executes the trigger and starts acquiring data.

You use the triggerconfig function to specify this value. The value of the TriggerSource property is device specific. You specify whatever mechanism a particular device uses to generate triggers.

For example, for Matrox hardware, the TriggerSource property could have values such as "Port0" or "Port1". Use the triggerinfo function to view a list of values that are valid for your image acquisition device.

You must use the triggerconfig function to set the value of this property.

Note

The TriggerSource property is only used when the TriggerType property is set to "hardware".

Data Types: char

FramesPerTrigger — Number of frames to acquire per trigger using selected video source

10 (default) | positive integer

Number of frames the video input object acquires each time it executes a trigger using the selected video source, specified as a positive integer.

When the value of the FramesPerTrigger property is set to Inf, the object keeps acquiring frames until an error occurs or you issue a stop command.

Note

When the FramesPerTrigger property is set to Inf, the object ignores the value of the TriggerRepeat property.

Data Types: double

InitialTriggerTime — Absolute time of first trigger

[] (default) | MATLAB clock vector

This property is read-only.

Absolute time of the first trigger, returned as a MATLAB clock vector.

For all trigger types, InitialTriggerTime records the time when the Logging property is set to "on".

To find the time when a subsequent trigger executed, view the Data.AbsTime field of the EventLog property for the particular trigger.

Data Types: double

TriggerFrameDelay — Number of frames to skip before acquiring frames after trigger occurs

0 (default) | integer

Number of frames to skip before acquiring frames after a trigger occurs, specified as an integer. The object waits the specified number of frames after the trigger before starting to log frames.

In this figure, the TriggerFrameDelay is set to 5, so the object lets five frames pass before starting to acquire frames. The number of frames captured is defined by the FramesPerTrigger property.

Data Types: double

TriggerRepeat — Number of additional times to execute trigger

0 (default) | nonnegative integer

Number of additional times you want the object to execute a trigger, specified as a nonnegative integer. This table describes the behavior for several typical TriggerRepeat values.

Value	Behavior
0 (default)	Execute the trigger once when the trigger condition is met.
Any positive integer	Execute the trigger the specified number of additional times when the trigger condition is met.
Inf	Keep executing the trigger every time the trigger condition is met until the stop function is called or an error occurs.

To determine how many triggers have executed, check the value of the TriggersExecuted property.

Note

If the FramesPerTrigger property is set to Inf, the object ignores the value of the TriggerRepeat property.

Data Types: double

TriggersExecuted — Total number of executed triggers

0 (default) | nonnegative integer

This property is read-only.

Total number of triggers that the video input object has executed, specified as a nonnegative integer.

Data Types: double

Video Source Object Properties

Parent — Video input object that is parent of video source object

videoinput object

This property is read-only.

Video input object that is the parent of a video source object, specified as a videoinput object.

The parent of a video source object is defined as the video input object owning the video source object.

Selected — Whether video source object will be used for acquisition

"off" (default) | "on"

This property is read-only.

Whether the video source object will be used for acquisition, specified as "off" or "on". You select a video source object by specifying its name as the value of the video input object's SelectedSourceName property. The video input object Source property is an array of all the video source objects associated with the video input object.

If Selected is "on", the video source object is selected. If the value is "off", the video source object is not selected.

A video source is defined to be a collection of one or more physical data sources that are treated as a single entity. For example, hardware supporting multiple RGB sources, each of which is made up of three physical connections (red, green, and blue), is treated as a single video source object.

Data Types: char

SourceName — Name of video source object

character vector

This property is read-only.

Name of a video source object, specified as a character vector.

SourceName is one of the values in the video input object's SelectedSourceName property.

Data Types: char

Tag — Descriptive text to associate with image acquisition object

character vector | string scalar

Descriptive text that you want to associate with an image acquisition object, specified as a character vector or string scalar.

The Tag property can be useful when you are constructing programs that would otherwise need to define the image acquisition object as a global variable, or pass the object as an argument between callback routines.

You can use the value of the Tag property to search for particular image acquisition objects when using the imaqfind function.

Data Types: char | string

Type — Type of image acquisition object

"videoinput" | "videosource"

This property is read-only.

Type of image acquisition object, specified as "videoinput" or "videosource". An image acquisition object can be either one of two types:

• Video input object

• Video source object

Data Types: char

Acquisition Source Properties

SelectedSourceName — Name of currently selected video source

character vector | string scalar

Name of the video source object from which the video input object acquires data, specified as a character vector or string scalar. By default, the video input object selects the first available video source object stored in the Source property.

The toolbox defines a video source as one or more hardware inputs that are treated as a single entity. For example, hardware supporting multiple RGB sources, each of which is made up of three physical connections (red-green-blue), is treated as a single video source object.

Data Types: char | string

Source — Video source objects associated with video input object

video source object

This property is read-only.

Vector of video source objects that represent the physical data sources connected to a device. When a video input object is created, the toolbox creates a vector of video source objects associated with the video input object.

Each video source object created is provided a unique source name. You can use the source name to select the desired acquisition source by configuring the SelectedSourceName property of the video input object.

A video source object's name is stored in its SourceName property. If a video source object's SourceName is equivalent to the video input object's SelectedSourceName, the video source object's Selected property has a value of "on".

The video source object supports a set of common properties, such as SourceName. Each video source object can also support device-specific properties that control characteristics of the physical device such as brightness, hue, and saturation. Different image acquisition devices expose different sets of properties.

A video source is defined to be a collection of one or more physical data sources that are treated as a single entity. For example, hardware supporting multiple RGB sources, each of which is made up of three physical connections (red-green-blue), is treated as a single video source object.

The Source property encapsulates one or more video sources. To reference a video source, you use a numerical integer to index into the vector of video source objects.

GigE Properties

IgnoreDroppedFrames — Whether the acquisition continues when it encounters a dropped frame

"off" (default) | "on"

Whether the acquisition continues when it encounters a dropped frame, specified as "off" or "on".

If this property is set to "off", the acquisition stops when it encounters a dropped frame. If this property is set to "on", the acquisition continues by ignoring the dropped frames.

When this property is "on", keep track of the number of frames dropped while the acquisition is running with the NumDroppedFrames property.

Note

This property is only supported on videoinput objects using the gige adaptor and is not supported on gigecam objects.

Data Types: char | string

NumDroppedFrames — Number of frames dropped while acquisition is running

0 (default) | nonnegative integer

This property is read-only.

Number of frames dropped while the acquisition is running if the IgnoreDroppedFrames property is set to 'on', specified as a nonnegative integer.

This property does not keep track of the number of frames dropped while previewing.

Note

This property is only supported on videoinput objects using the gige adaptor and is not supported on gigecam objects.

Data Types: double

Object Functions

Configuration

get	Return image acquisition object properties
set	Configure or display image acquisition object properties

Execution

getselectedsource	Return currently selected video source object
start	Obtain exclusive use of image acquisition device
stop	Stop video input object
wait	Wait until image acquisition object stops running or logging

Trigger Functions

trigger	Initiate data logging
triggerconfig	Configure video input object trigger properties
triggerinfo	Provide information about available trigger configurations

Data Functions

flushdata	Remove data from memory buffer used to store acquired image frames
getdata	Acquired image frames to MATLAB workspace
getsnapshot	Immediately return single image frame
peekdata	Most recently acquired image data

Tools

closepreview	Close Video Preview window
imaqmontage	Sequence of image frames as montage
preview	Preview of live video data

General

delete	Remove image acquisition object from memory
imaqfind	Find image acquisition objects
imaqreset	Disconnect and delete all image acquisition objects
isvalid	Determine whether image acquisition object is associated with image acquisition device

Information and Help

imaqhelp	Help for image acquisition object functions and properties
imaqhwinfo	Information about available image acquisition hardware
propinfo	Property characteristics for image acquisition objects

Examples

Create Video Input Object

Construct a video input object.

obj = videoinput("matrox",1);

Select the source to use for acquisition.

obj.SelectedSourceName = "input1"

View the properties for the selected video source object.

src_obj = getselectedsource(obj);
get(src_obj)

Preview a stream of image frames.

preview(obj);

Acquire and display a single image frame.

frame = getsnapshot(obj);
image(frame);

Remove video input object from memory.

delete(obj);

Use VideoWriter

Create a video input object that accesses a GigE Vision^® image acquisition device and uses grayscale format at 10 bits per pixel.

vidobj = videoinput("gige",1,"Mono10");

You can log acquired data to memory, to disk, or both. By default, data is logged to memory. To change the logging mode to disk, configure the video input object's LoggingMode property.

vidobj.LoggingMode = "disk"

Create a VideoWriter object with the profile set to Motion JPEG 2000. Motion JPEG 2000 allows writing the full 10 bits per pixel data to the file.

vidobj.DiskLogger = VideoWriter("logfile.mj2","Motion JPEG 2000")

Now that the video input object is configured for logging data to a Motion JPEG 2000 file, initiate the acquisition.

start(vidobj)

Wait for the acquisition to finish.

wait(vidobj)

When logging large amounts of data to disk, disk writing occasionally lags behind the acquisition. To determine whether all frames are written to disk, you can optionally use the DiskLoggerFrameCount property.

while (vidobj.FramesAcquired ~= vidobj.DiskLoggerFrameCount) 
    pause(.1)
end

You can verify that the FramesAcquired and DiskLoggerFrameCount properties have identical values by using these commands and comparing the output.

vidobj.FramesAcquired
vidobj.DiskLoggerFrameCount

When the video input object is no longer needed, delete it and clear it from the workspace.

delete(vidobj)
clear vidobj

Version History

Introduced before R2006a