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_PROPERTY_MAP. For example, to get the property map for the device properties of the video capture device opened by a grabber, call ic4_grabber_device_get_property_map. Propery map objects are also available for driver settings (ic4_grabber_driver_get_property_map), interfaces (ic4_devitf_get_property_map) and codec settings (ic4_videowriter_get_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.

Many common property identifiers are predefined for ease of use (see Property Identifiers).

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_propmap_set_value_int64 or ic4_propmap_set_value_string 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_propmap_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_prop_get_type)
• Its display name (ic4_prop_get_display_name)
• Its description (ic4_prop_get_description)

Common property operations are described in detail in the Property Objects section.

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.
  Interaction with integer properties is described in detail in the Integer Properties section.
• 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.
  Interaction with float properties is described in detail in the Float Properties section.
• Command properties
  A command property represents an action that a device can execute.
  Interaction with command properties is described in detail in the Command Properties section.
• Boolean properties
  A boolean property is a simple on/off switch. Interaction with boolean properties is described in detail in the Boolean Properties section.
• 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.
  Interaction with enumeration properties is described in detail in the Enumeration Properties section.
• String properties
  String properties are mostly used to provide device information in text form. Interaction with string properties is described in detail in the String Properties section.
  • Register properties
    Register properties represent fixed-length arrays of raw byte data. Interaction with register properties is described in detail in the Register Properties section.
• 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. Interaction with category properties is described in detail in the Category Properties section.