videoinput

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.

green blue
red   green

green red
blue  green

blue  green
green red

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

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

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.

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

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.

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

Data Types: double

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.

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

Data Types: double

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

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

Whether the image data in the Preview window is being displayed in full bit depth, specified as "off" or "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

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

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:

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

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].

Data Types: double

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:

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

Data Types: char

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.

Data Types: double

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

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

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].

Data Types: double

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

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:

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.

Data Types: char | string

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.

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.

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

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.

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

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.

Data Types: char | string | cell | function_handle

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

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

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

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

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.

Data Types: char | string | cell | function_handle

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.

Data Types: double

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

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.

Data Types: char

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.

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

Data Types: char

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.

Data Types: char

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.

Data Types: double

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

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

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.

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

Data Types: double

This property is read-only.

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

Data Types: double

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.

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

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

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

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:

Data Types: char

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

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.

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.

Data Types: char | string

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.

Data Types: double