Main Content

Configuring Image Acquisition Object Properties

About Image Acquisition Object Properties

The video input object and the video source object both support properties that enable you to control characteristics of the video image and how it is acquired.

The video input object properties control aspects of an acquisition that are common to all image acquisition devices. For example, you can use the FramesPerTrigger property to specify the amount of data you want to acquire.

The video source object properties control aspects of the acquisition associated with a particular source. The set of properties supported by a video source object varies with each device. For example, some image acquisition devices support properties that enable you to control the quality of the image being produced, such as Brightness, Hue, and Saturation.

With either type of object, you can use the same toolbox functions to

  • View a list of all the properties supported by the object, with their current values

  • View the value of a particular property

  • Get information about a property

  • Set the value of a property

Note

Three video input object trigger properties require the use of a special configuration function. For more information, see Setting Trigger Properties.

Viewing the Values of Object Properties

To view all the properties of an image acquisition object, with their current values, use the get function. You can also use the inspect function to view a list of object properties in the Property Inspector window, where you can also edit their values.

This example uses the get function to display a list of all the properties of the video input object vid. Viewing the Properties of a Video Source Object describes how to do this for video source objects.

If you do not specify a return value, the get function displays the object properties in four categories: General Settings, Callback Function Settings, Trigger Settings, and Acquisition Sources.

get(vid)
  General Settings:
    DeviceID = 1
    DiskLogger = []
    DiskLoggerFrameCount = 0
    EventLog = [1x0 struct]
    FrameGrabInterval = 1
    FramesAcquired = 0
    FramesAvailable = 0
    FramesPerTrigger = 10
    Logging = off
    LoggingMode = memory
    Name = M_RS170-matrox-1
    NumberOfBands = 1
    Previewing = off
    ReturnedColorSpace = grayscale
    ROIPosition = [0 0 640 480]
    Running = off
    Tag = 
    Timeout = 10
    Type = videoinput
    UserData = []
    VideoFormat = M_RS170
    VideoResolution = [640 480]

  Callback Function Settings:
    ErrorFcn = @imaqcallback
    FramesAcquiredFcn = []
    FramesAcquiredFcnCount = 0
    StartFcn = []
    StopFcn = []
    TimerFcn = []
    TimerPeriod = 1
    TriggerFcn = []

  Trigger Settings:
    InitialTriggerTime = [0 0 0 0 0 0]
    TriggerCondition = none
    TriggerFrameDelay = 0
    TriggerRepeat = 0
    TriggersExecuted = 0
    TriggerSource = none
    TriggerType = immediate

  Acquisition Sources:
    SelectedSourceName = CH0
    Source = [1x8 videosource]

Viewing the Properties of a Video Source Object

To view the properties supported by the video source object (or objects) associated with a video input object, use the getselectedsource function to retrieve the currently selected video source object. This example lists the properties supported by the video source object associated with the video input object vid. Note the device-specific properties that are included.

Note

The video source object for your device might not include device-specific properties. For example, devices accessed with the 'winvideo' adaptor, such as webcams, that use a Video for Windows® (VFW) driver, may not provide a way for the toolbox to programmatically query for device properties. Use the configuration tools provided by the manufacturer to configure these devices.

get(getselectedsource(vid))
  General Settings:
    Parent = [1x1 videoinput]
    Selected = on
    SourceName = CH0
    Tag = 
    Type = videosource

  Device Specific Properties:
    InputFilter = lowpass
    UserOutputBit3 = off
    UserOutputBit4 = off
    XScaleFactor = 1
    YScaleFactor = 1

Viewing the Value of a Particular Property

To view the value of a particular property of an image acquisition object, access the value of the property as you would a field in a MATLAB® structure.

This example illustrates how to access a property by referencing the object as if it were a MATLAB structure using dot notation.

vid.Previewing

ans =

off

Getting Information About Object Properties

To get information about a particular property, see videoinput Properties. You can also get information about a particular property at the command line by using the propinfo or imaqhelp functions.

The propinfo function returns a structure that contains information about the property such as its data type, default value, and a list of all possible values, if the property supports such a list. This example uses propinfo to get information about the LoggingMode property.

propinfo(vid,'LoggingMode')

ans = 

               Type: 'character vector'
         Constraint: 'enum'
    ConstraintValue: {'memory'  'disk'  'disk&memory'}
       DefaultValue: 'memory'
           ReadOnly: 'whileRunning'
     DeviceSpecific: 0

The imaqhelp function returns reference information about the property with a complete description. This example uses imaqhelp to get information about the LoggingMode property.

imaqhelp(vid,'LoggingMode')

Setting the Value of an Object Property

To set the value of a particular property of an image acquisition object, you assign the value to the property as you would a field in a MATLAB structure, using dot notation.

Note

Because some properties are read-only, only a subset of all video input and video source properties can be set.

This example sets the value of a property by assigning the value to the object as if it were a MATLAB structure.

vid.LoggingMode = 'disk';

% Verify the property setting. 
vid.LoggingMode

ans =

disk

Viewing a List of All Settable Object Properties

To view a list of all the properties of a video input object or video source object that can be set, use the set function.

set(vid)

Setting Trigger Properties

The values of certain trigger properties, TriggerType, TriggerCondition, and TriggerSource, are interrelated. For example, some TriggerCondition values are only valid with specific values of the TriggerType property.

To ensure that you specify only valid combinations for the values of these properties, you must use two functions:

  • The triggerinfo function returns all the valid combinations of values for the specified video input object.

  • The triggerconfig function sets the values of these properties.

For more information, see Specifying Trigger Type, Source, and Condition.

Note

To get a list of options you can use on a function, press the Tab key after entering a function on the MATLAB command line. The list expands, and you can scroll to choose a property or value. For information about using this advanced tab completion feature, see Using Tab Completion for Functions.