Working with Properties

This example shows how to access and configure video acquisition properties.

Accessing Properties

To access a complete list of an object's properties and their current values, use the get function with the object.

% Create a video input object.
vidobj = videoinput('dcam', 1);

% List the video input object's properties and their current values.
get(vidobj)

  General Settings:
    DeviceID = 1
    DiskLogger = []
    DiskLoggerFrameCount = 0
    EventLog = [1x0 struct]
    FrameGrabInterval = 1
    FramesAcquired = 0
    FramesAvailable = 0
    FramesPerTrigger = 10
    Logging = off
    LoggingMode = memory
    Name = RGB24_640x480-dcam-1
    NumberOfBands = 3
    Previewing = off
    ReturnedColorSpace = rgb
    ROIPosition = [0 0 640 480]
    Running = off
    Tag = 
    Timeout = 10
    Type = videoinput
    UserData = []
    VideoFormat = RGB24_640x480
    VideoResolution = [640 480]

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

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

  Acquisition Sources:
    SelectedSourceName = input1
    Source = [1x1 videosource]

% Access the currently selected video source object
src = getselectedsource(vidobj);

% List the video source object's properties and their current values.
get(src)

  General Settings:
    Parent = [1x1 videoinput]
    Selected = on
    SourceName = input1
    Tag = 
    Type = videosource

  Device Specific Properties:
    AutoExposure = 511
    AutoExposureMode = auto
    Brightness = 304
    BrightnessMode = auto
    FrameRate = 15
    Gain = 87
    Gamma = 1
    Saturation = 90
    Sharpness = 80
    Shutter = 6
    WhiteBalance = [95 87]
    WhiteBalanceMode = auto

To access a specific property value, use dot notation with the object and property name.

framesPerTriggerValue = vidobj.FramesPerTrigger;

framesPerTriggerValue =

    10

brightnessValue = src.Brightness;

brightnessValue =

   304

Configuring Properties

Enumerated properties have a defined set of possible values. To list the enumerated values of a property, use the set function with the object and property name. The property's default value is listed in braces.

set(vidobj, 'LoggingMode')

[ {memory} | disk | disk&memory ]

To access a complete list of an object's configurable properties, use the set function with the object.

% List the video input object's configurable properties.
set(vidobj)

  General Settings:
    DiskLogger
    FrameGrabInterval
    FramesPerTrigger
    LoggingMode: [ {memory} | disk | disk&memory ]
    Name
    ReturnedColorSpace: [ {rgb} | grayscale | YCbCr ]
    ROIPosition
    Tag
    Timeout
    UserData

  Callback Function Settings:
    ErrorFcn: string -or- function handle -or- cell array
    FramesAcquiredFcn: string -or- function handle -or- cell array
    FramesAcquiredFcnCount
    StartFcn: string -or- function handle -or- cell array
    StopFcn: string -or- function handle -or- cell array
    TimerFcn: string -or- function handle -or- cell array
    TimerPeriod
    TriggerFcn: string -or- function handle -or- cell array

  Trigger Settings:
    TriggerFrameDelay
    TriggerRepeat

  Acquisition Sources:
    SelectedSourceName: [ {input1} ]

% List the video source object's configurable properties.
set(src)

  General Settings:
    Tag

  Device Specific Properties:
    AutoExposure
    AutoExposureMode: [ {auto} | manual ]
    Brightness
    BrightnessMode: [ {auto} | manual ]
    FrameRate: [ {15} | 7.5 | 3.75 ]
    Gain
    Gamma
    Saturation
    Sharpness
    Shutter
    WhiteBalance
    WhiteBalanceMode: [ {auto} | manual ]

To configure an object's property value, use dot notation with the object, property name, and property value.

vidobj.TriggerRepeat = 2;
src.Saturation = 100;

Getting Property Help and Information

To obtain a property's description, use the imaqhelp function with the object and property name. imaqhelp can also be used for function help.

imaqhelp(vidobj, 'LoggingMode')

    LOGGINGMODE  [ {memory} | disk | disk&memory ]  (Read-only: whileRunning)

    LoggingMode specifies the destination for acquired data.
    
    LoggingMode can be set to disk, memory,or disk&Memory. 
    
    If LoggingMode is set to disk, then acquired data is streamed to a disk file 
    as specified by the DiskLogger property. 
    
    If LoggingMode is set to memory, acquired data is stored in a memory buffer. 
    
    If LoggingMode is set to disk&Memory, then acquired data is stored in memory 
    and is streamed to a disk file as specified by the DiskLogger property.
    
    When logging to memory, you must extract the data in a timely manner with the 
    GETDATA function. If the data is not extracted in a timely manner, memory 
    resources may be used up.
    
    The value of LoggingMode cannot be modified while the object is running.
    
    See also DiskLogger, IMAQDEVICE/GETDATA.

To obtain information on a property's attributes, use the propinfo function with the object and property name.

propinfo(vidobj, 'LoggingMode')

ans = 

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

When an image acquisition object is no longer needed, remove it from memory and clear the MATLAB® workspace of the associated variable.

delete(vidobj);
clear vidobj