Creating Image Acquisition Objects
Types of Objects
After you get information about your image acquisition hardware, described in Getting Hardware Information, you can establish a connection to the device by creating an image acquisition object. The toolbox uses two types of image acquisition objects:
Video input object
Video source object
Video Input Objects
A video input object represents the connection between MATLAB® and a video acquisition device
at a high level. You must create the video input object using the
See Creating a Video Input Object for more information.
Video Source Objects
When you create a video input object, the toolbox automatically creates one or more video source objects associated with the video input object. Each video source object represents a collection of one or more physical data sources that are treated as a single entity. The number of video source objects the toolbox creates depends on the device and the video format you specify.
At any one time, only one of the video source objects, called the selected source, can be active. This is the source used for acquisition. The toolbox selects one of the video source objects by default, but you can change this selection. See Specifying the Selected Video Source Object for more information.
The following figure illustrates how a video input object acts as a container for one or more video source objects.
Relationship of Video Input Objects and Video Source Objects
For example, a Matrox® frame grabber device can support eight physical connections, which Matrox calls channels. These channels can be configured in various ways, depending upon the video format. If you specify a monochrome video format, such as RS170, the toolbox creates eight video source objects, one object for each of the eight channels on the device. If you specify a color video format, such as NTSC RGB, the Matrox device uses three physical channels to represent one RGB connection, where each physical connection provides the red data, green data, and blue data separately. With this format, the toolbox only creates two video source objects for the same device.
Creating a Video Input Object
To create a video input object, call the
specifying the adaptor name, device ID, and video format. You retrieved
this information using the
(described in Getting Hardware Information). The only required argument
is the adaptor name. The toolbox can use default values for the device
ID and video format.
This example creates a video input object to represent the connection
to a Matrox image acquisition
imaqhwinfo function includes the default
VideoInputConstructor field of the device
vid = videoinput('matrox');
This syntax uses the default video format listed in the
of the data returned by
imaqhwinfo. You can optionally
specify the video format. See Specifying the Video Format for more
Viewing a Summary of a Video Input Object
To view a summary of the characteristics of the video input
object you created, enter the variable name you assigned to the object
at the command prompt. For example, this is the summary for the object
The items in this list correspond to the numbered elements in the object summary:
The title of the summary includes the name of the image acquisition device this object represents. In the example, this is a Matrox Orion frame grabber.
The Acquisition Source section lists the name of all the video source objects associated with this video input object. For many objects, this list might only contain one video source object. In the example, the Matrox device supports eight physical input channels and, with the default video format, the toolbox creates a video source object for each connection. For an example showing the video source objects created with another video format, see Specifying the Video Format.
The Acquisition Parameters section lists the values of key video input object properties. These properties control various aspects of the acquisition, such as the number of frames to acquire and the location where acquired frames are stored. For information about these properties, see Acquiring Image Data.
The Trigger Parameters section lists the trigger type configured for the object and the number of times the trigger is to be executed. Trigger execution initiates data logging, and the toolbox supports several types of triggers. The example object is configured by default with an immediate trigger. For more information about configuring triggers, see Specifying the Trigger Type.
The Status section lists the current state of the object. A video input object can be in one of several states:
Running or not running (stopped)
Logging or not logging
Previewing or not previewing
In the example, the object describes its state as
Waiting for START. This indicates it is not running. For more information about the running state, see Starting and Stopping a Video Input Object. This section also reports how many frames of data have been acquired and how many frames are available in the buffer where the toolbox stores acquired frames. For more information about these parameters, see Controlling Logging Parameters.
Specifying the Video Format
You can optionally specify the format of the video stream when
you create a video input object as a third argument to the
This argument can take two forms:
A character vector specifying a video format
A name of a device configuration file, also known as a camera file
The following sections describe these options. If you do not
specify a video format, the
uses one of the video formats supported by the device. For Matrox and Data Translation® devices,
it chooses the RS170 video format. For Windows® devices,
it uses the first RGB format in the list of supported formats or,
if no RGB formats are supported, the device's default format.
Using a Video Format Character Vector
To specify a video format as a character vector, use the
to determine the list of supported formats. The
returns this information in the
of the device information structure. See Determining Supported Video Formats for
In this example, each of the character vectors is a video format supported by a Matrox device.
info = imaqhwinfo('matrox'); info.DeviceInfo.SupportedFormats ans = Columns 1 through 4 'M_RS170' 'M_RS170_VIA_RGB' 'M_CCIR' 'M_CCIR_VIA_RGB' Columns 5 through 8 'M_NTSC' 'M_NTSC_RGB' 'M_NTSC_YC' 'M_PAL' Columns 9 through 10 'M_PAL_RGB' 'M_PAL_YC'
For Matrox devices,
the toolbox uses the RS170 format as the default. (To find out which
is the default video format, look in the
of the device information structure returned by the
For Matrox devices,
M_NTSC_RGB format represents a component video
This example creates a video input object, specifying a color video format.
vid2 = videoinput('matrox', 1,'M_NTSC_RGB');
Using Device Configuration Files (Camera Files)
For some devices, you can use a device configuration file, also known as a camera file, to specify the video format as well as other configuration settings. Image acquisition device vendors supply these device configuration files.
The toolbox ignores hardware trigger configurations included
in a device configuration file. To configure a hardware trigger, you
must use the toolbox
triggerconfig function. See Using a Hardware Trigger for more information.
For example, with Matrox frame grabbers, you can download digitizer configuration format (DCF) files, in their terminology. These files configure their devices to support particular cameras.
Some image acquisition device vendors provide utility programs you can use to create a device configuration file or edit an existing one. See your hardware vendor's documentation for more information.
To determine if your image acquisition device supports device
configuration files, check the value of the
of the device information structure returned by
See Getting More Information About a Particular Device for more
When you use a device configuration file, the value of the
of the video input object is the name of the file, not a video format
This example creates a video input object specifying a Matrox device configuration file as an argument.
Specifying the Selected Video Source Object
When you create a video input object, the toolbox creates one
or more video source objects associated with the video input object.
The number of video source objects created depends on the device and
the video format. The
Source property of the video
input object lists these video source objects.
To illustrate, this example lists the video source objects associated
with the video input object
vid.Source Display Summary for Video Source Object Array: Index: SourceName: Selected: 1 'CH0' 'on' 2 'CH1' 'off' 3 'CH2' 'off' 4 'CH3' 'off' 5 'CH4' 'off' 6 'CH5' 'off' 7 'CH6' 'off' 8 'CH7' 'off'
By default, the video input object makes the first video source
object in the array the selected source. To use another video source,
change the value of the
This example changes the currently selected video source object
CH1 by setting the
value of the
vid.SelectedSourceName = 'CH1';
getselectedsource function returns the
video source object that is currently selected at the time the function
is called. If you change the value of the
you must call the
getselectedsource function again
to retrieve the new selected video source object.
Getting Information About a Video Input Object
After creating a video input object, you can get information
about the device it represents using the
When called with a video input object as an argument,
a structure containing information about the object such as the name
of the adaptor, name of the device, video resolution, and details
of the vendor's device driver and version.
out = imaqhwinfo(vid) out = AdaptorName: 'winvideo' DeviceName: 'IBM PC Camera' MaxHeight: 96 MaxWidth: 128 NativeDataType: 'uint8' TotalSources: 1 VendorDriverDescription: 'Windows WDM Compatible Driver' VendorDriverVersion: 'DirectX 9.0'