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 videoinput function. 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 videoinput function specifying the adaptor name, device ID, and video format. You retrieved this information using the imaqhwinfo function (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 device. The imaqhwinfo function includes the default videoinput syntax in the VideoInputConstructor field of the device information structure.

vid = videoinput('matrox');

This syntax uses the default video format listed in the DefaultFormat field of the data returned by imaqhwinfo. You can optionally specify the video format. See Specifying the Video Format for more information.

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

vid

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 videoinput function. 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 videoinput function 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 imaqhwinfo function to determine the list of supported formats. The imaqhwinfo function returns this information in the SupportedFormats field of the device information structure. See Determining Supported Video Formats for more information.

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 DefaultFormat field of the device information structure returned by the imaqhwinfo function.)

Note

For Matrox devices, the M_NTSC_RGB format represents a component video format.

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.

Note

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 DeviceFileSupported field of the device information structure returned by imaqhwinfo. See Getting More Information About a Particular Device for more information.

When you use a device configuration file, the value of the VideoFormat property of the video input object is the name of the file, not a video format character vector.

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.

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 SelectedSourceName property.

This example changes the currently selected video source object from CH0 to CH1 by setting the value of the SelectedSourceName property.

vid.SelectedSourceName = 'CH1';

Note

The 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 SelectedSourceName property, 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 imaqhwinfo function. When called with a video input object as an argument, imaqhwinfo returns 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'