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.device_property_map. Propery map objects are also available for driver settings (Grabber.driver_property_map), interfaces (Interface.property_map) and codec settings (VideoWriter.property_map).
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 enumeration.
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 functions to directly interact with properties, such as PropertyMap.set_value() 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.
A property object can be interogated for generic property attributes, for example
its type (Property.type)
its display name (Property.display_name)
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 PropId.WIDTH or PropId.HEIGHT of the ROI that is being read out from the image sensor.
An integer property defines a PropInteger.minimum and PropInteger.maximum value as well as an PropInteger.increment for valid values.
It can define additional attributes such as a PropInteger.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 PropId.EXPOSURE_TIME or PropId.ACQUISITION_FRAME_RATE.
A float property defines a PropFloat.minimum and PropFloat.maximum value as well as an optional PropFloat.increment for valid values.
It can define additional attributes such as a PropFloat.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 PropId.TRIGGER_SOFTWARE.
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 PropBooolean 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.
