Accessing Device Properties
This section describes how to query, read and change properties of a component, usually the video capture device.
Property Map
Properties are accessed through a PropertyMap. For example, to get the property map for the device properties of the video capture device opened by a grabber, use Grabber.DevicePropertyMap. Propery map objects are also available for driver settings (Grabber.DriverPropertyMap), interfaces (Interface.PropertyMap) and codec settings (VideoWriter.PropertyMap).
Property Identifiers
Each property is identified by a string identifier, for example ExposureTime or Gain.
Many property identifiers are defined by the GenICam Standard Feature Naming Convention (SFNC),
but devices can also have additional device-specific properties.
Common property identifiers are defined in the PropId class.
Property Objects
Each property has a display name, a description, a type, and visibility and accessibility information. The display name can be used in user interfaces to show a friendly name for the property, while the description can contain additional information about the property's meaning and/or usage.
There are multiple functions to directly interact with properties, such as PropertyMap.SetValue and its overloads that can be used to quickly configure the value of a property with a known type and value.
Detailed property information and configuration is achieved through an object-oriented interface. To get a Property object instance, call PropertyMap::Find or its sibling functions, passing the property's known identifier.
Untyped find functions that take a string to identify the property, return references to the Property base class,
while the typed find functions (that use a PropId to identify the property) return references to the derived property class,
e.g. PropInteger or PropEnumeration. The Property base class
can be casted to its actual type.
A property object can be interogated for generic property attributes, for example
- its type (Property.Type)
- its display name (Property.DisplayName)
- its description (Property.Description)
Specialized Property Types
Each property type has different methods of interaction and can provide additional type-dependent information.
Integer Properties
These are used to configure settings that are represented by whole numbers, such as the Width or Height of the ROI that is being read out from the image sensor.
An integer property defines a minimum and maximum value as well as a stepping for valid values.
It can define additional attributes such as a unit or display hints.
Integer properties are represented by instances of the PropInteger class.
Float Properties
These are used to configure settings that are represented by floating-point numbers, such as ExposureTime or AcquisitionFrameRate.
A float property defines a minimum and maximum value as well as an optional stepping for valid values.
It can define additional attributes such as a unit or display hints.
Float properties are represented by instances of the PropFloat class.
Command Properties
A command property represents an action that a device can execute, for example TriggerSoftware.
The command can be executed and queried for completion.
Command properties are represented by instances of the PropCommand class.
Boolean Properties
A boolean property is a simple on/off switch.
Boolean properties are represented by instances of the PropBoolean class.
Enumeration Properties
Enumeration properties let the user choose from a set of valid values identified by strings.
They are used to configure camera settings such as the PixelFormat.
The enumeration entries also have an integer value associated with them. However, that numeric value does not necessarily have a well-defined meaning, and it should be used with care.
Enumeration properties are represented by instances of the PropEnumeration class.
String Properties
String properties are mostly used to provide device information in text form.
String properties are represented by instances of the PropString class.
Register Properties
Register properties represent fixed-length arrays of raw byte data.
Register properties are represented by instances of the PropRegister class.
Category Properties
Category properties are special properties that contain links to other properties.
That way, they span a tree of properties starting from the Root category. This tree can be used to structure user interfaces.
Category properties are represented by instances of the PropCategory class.
