Learn more about Image Acquisition Toolbox

Configuring Image Acquisition Object Properties

On this page…
About Image Acquisition Object Properties Viewing the Values of Object Properties Viewing the Value of a Particular Property Getting Information About Object Properties Setting the Value of an Object Property

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.

Back to Top

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

Back to Top

Viewing the Value of a Particular Property

To view the value of a particular property of an image acquisition object, use the get function, specifying the name of the property as an argument. You can also access the value of the property as you would a field in a MATLAB structure.

This example uses the get function to retrieve the value of the Previewing property.

get(vid,'Previewing')

ans =

off

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

vid.Previewing

ans =

off

Back to Top

Getting Information About Object Properties

To get information about a particular property, you can view the reference page for the property in Property Reference and Properties — Alphabetical List. 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: 'string'
         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')

Back to Top

Setting the Value of an Object Property

To set the value of a particular property of an image acquisition object, use the set function, specifying the name of the property as an argument. You can also assign the value to the property as you would a field in a MATLAB structure.

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

This example uses the set function to set the value of the LoggingMode property.

set(vid,'LoggingMode','disk&memory')

To verify the new value of the property, use the get function.

get(vid,'LoggingMode')

ans =

disk&memory

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';
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.

Back to Top

Creating Image Acquisition Objects

Starting and Stopping a Video Input Object

© 1984-2009- The MathWorks, Inc.    -   Site Help   -   Patents   -   Trademarks   -   Privacy Policy   -   Preventing Piracy   -   RSS