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 ic4::PropertyMap. For example, to get the property map for the device properties of the video capture device opened by a grabber, call ic4::Grabber::devicePropertyMap(). Propery map objects are also available for driver settings (ic4::Grabber::driverPropertyMap), interfaces (ic4::Interface::interfacePropertyMap) and codec settings (ic4::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 ic4::PropId namespace.

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 ic4::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 create a property object (ic4::Property), call ic4::PropertyMap::find() or its sibling functions, passing the property's known identifier.

A property object can be interrogated for generic property attributes, for example

• Its type (ic4::Property::type())
• Its display name (ic4::Property::displayName())
• Its description (ic4::Property::description())

Specialized Property Types

Each 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.
They can define additional additional attributes such as a, a unit or display hints.
To interact with integer properties, call one of the ic4::PropInteger member functions.

Float properties

These are used to configure settings that are represented by floating-point numbers, such as the ExposureTime or AcquisitionFrameRate.
A float property defines a minimum and maximum value as well as a stepping for valid values.
They can define additional additional attributes such as a unit or display hints.
To interact with float properties, call one of the ic4::PropFloat member functions.

Command properties

A command property represents an action that a device can execute.
To interact with command properties, call one of the ic4::PropCommand member functions.

Boolean properties

A boolean property is a simple on/off switch. To interact with boolean properties, call one of the ic4::PropBoolean member functions.

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.
To interact with enumeration properties, call one of the ic4::PropEnumeration functions.

String properties

String properties are mostly used to provide device information in text form. To interact with string properties, call one of the ic4::PropString member functions.

Register properties

Register properties represent fixed-length arrays of raw byte data. To interact with register properties, call one of the ic4::PropRegister member functions.

Category properties

Category properties are a special properties without a value, but they 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. To interact with category properties, call one of the ic4::PropCategory member functions.

To convert a ic4::Property object into its derived form, call one of the conversion member functions such as ic4::Property::asCommand() or ic4::Property::asString().