Use Advanced Property Support in the GigE Vision and GenICam GenTL Interfaces

Advanced Property Support

The Image Acquisition Toolbox™ has added GenICam™ property enhancements for the GigE Vision^® (gige) and GenICam GenTL (gentl) adaptors used with the videoinput object in R2016a. These features were already included in the gigecam object.

Ability to change properties while the acquisition is running
Dynamic accessibility and readability
Dynamic constraints
Grouped selector properties

Change Properties While the Acquisition Is Running

This ability is useful for properties that you want to change dynamically, such as exposure time. For example, you can now do this:

% Create the videoinput object using the GigE adaptor
vid = videoinput('gige')

% Get the video source
src = getselectedsource(vid);

% Set the frames per trigger on the source
vid.FramesPerTrigger = Inf;

% Start acquiring frames
start(vid)

% Change the exposure time during the acquisition
src.ExposureTime = 4;

Previously, changing the exposure time after starting the acquisition resulted in an error.

Note

This workflow is not supported in the Image Acquisition Explorer. While the acquisition is running, you can not change a property on the Device Properties tab.

Dynamic Accessibility and Readability

Device-specific properties, or camera GenICam properties, are now dynamically accessible. In previous releases, camera GenICam properties that were not accessible were hidden. If you display the device-specific properties using the disp, get or propinfo functions, properties that previously did not show up now show up with labels.

The propinfo function includes a new field called Accessible, which is a read-only boolean property. A disp on a property that has Accessible set to 0 results in “Currently not accessible.” To enable accessibility, set Accessible to 1. For example, if you have the ReverseY property set to Accessible, the following:

 propinfo(src,'ReverseY')

would result in a disp showing:

 Accessible: 1

The same is true for the ReadOnly property. Readability is now dynamic and the propinfo function shows a ReadOnly property as either 'notCurrently', if it is writable, or 'currently', if it is read-only. The example in the Dynamic Constraints section demonstrates the dynamic use of this property.

You can view the source properties to see if any properties are currently not accessible. In this example, for the part of the disp shown below, AcquisitionFrameCount and BalanceRatioRaw are currently not accessible.

>> src = vid.Source

src = 

   Display Summary for Video Source Object:

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

      Device Specific Properties:
        AcquisitionFrameCount = (Currently not accessible)
        AcquisitionFrameRate = 4.5
        AcquisitionFrameRateAuto = Off
        AcquisitionFrameRateEnabled = True
        BalanceRatioRaw = (Currently not accessible)
        BinningHorizontal = 1
        BinningVertical = 1
        BlackLevel = 1.001
        ...

Dynamic Constraints

If you change a property that results in a change of possible values, or constraint change, for another property, the other property’s constraint values are updated dynamically. Consider a camera that has an automatic sharpness setting that you can set to Continuous to automatically adjust the sharpness or set to Off. The automatic sharpness property then affects the related Sharpness property. In this example, when SharpnessAuto is set to Continuous, a disp of the Sharpness property shows the constrained values and that it is not able to be set.

>> propinfo(src, 'SharpnessAuto')

ans = 

               Type: 'character vector'
         Constraint: 'enum'
    ConstraintValue: {'Continuous'  'Off'}
       DefaultValue: 'Continuous'
           ReadOnly: 'notCurrently'
     DeviceSpecific: 1
         Accessible: 1

>> propinfo(src, 'Sharpness')

ans = 

               Type: 'integer'
         Constraint: 'bounded'
    ConstraintValue: [1532 1532]
       DefaultValue: 1532
           ReadOnly: 'currently'
     DeviceSpecific: 1
         Accessible: 1

If you then set the SharpnessAuto property to Off, a second disp of the Sharpness property shows that the constrained values have dynamically updated, and that it is now able to be set (no longer read-only).

>> src.SharpnessAuto = 'Off'
>> propinfo(src, 'Sharpness')

ans = 

               Type: 'integer'
         Constraint: 'bounded'
    ConstraintValue: [0 4095]
       DefaultValue: 1532
           ReadOnly: 'notCurrently'
     DeviceSpecific: 1
         Accessible: 1

Grouped Selector Properties

In both the Image Acquisition Explorer and the command line, selector properties are now grouped. In the tool, you can see the groupings in the Device Properties tab. In the property display on the command line, the related properties are grouped – the selector property is listed, with its possible values appearing below it.

For example, in previous versions of the toolbox, for a GainSelector with possible values of Red, Blue, and Green and a Gain property, the gain properties displayed as follows:

>> vid = videoinput('gige')
>> src = getselectedsource(vid)
...
...
RedGain = 0.4
BlueGain = 0.2
GreenGain = 0.1
...

They now display as separate values on one selector property instead:

>> vid = videoinput('gige')
>> src = getselectedsource(vid)
...
...
GainSelector = 'Red'
Gain = 0.2
...

Compatibility Considerations

The grouping of selector properties results in a compatibility consideration starting in R2016a because of the change in how selector properties are displayed, read, or written. There are now fewer properties since some are shown as a single selector property with separate values, whereas they used to be separate properties.

If you have any MATLAB^® code written prior to R2016a which references the previous, separate properties, you need to change the code to reflect them as values on the selector property. Setting and getting properties that belong to a selector using the previous composite-name style is no longer supported. For example, RedGain no longer works. Instead use GainSelector set to Red, as shown in the example.

To set a property value, first set the selector value, then set the property value:

src.GainSelector = 'Green';
src.Gain = 0.1;