Device configuration#
In the GenICam world, each device exposes its parameters in a tree structure called nodemap, where each node of the tree represents a parameter, called feature, of the camera. The GenApi library is provided with ItalaApi and it is specifically designed to manipulate these features. Thanks to GenApi, the client code can write and read values to and from the nodemaps exposed by Opto Engineering devices, in accordance with the GenICam standard.
Note
Feature names and types are standardized by SFNC (Standard Feature Naming Convention), which is part of the GenICam standard. Its goal is to improve compatibility between different devices and applications by defining a set of standard features that every camera manufacturer must and/or should implement. Opto Engineering features are compliant with SFNC and are listed in the user manual of every Opto Engineering device. Please refer to the official SFNC document to gather information about a particular feature. Refer to the official GenICam document to find a more in-depth description of the standard. All the material is freely accessible from the GenICam Introduction page.
To configure a device, the client code can easily get its nodemap thanks to the itala.itala.IDevice
interface. Note that itala.itala.INodeMap
belongs to GenApi since it’s provided by the GenApi library, developed by the GenICam group.
# Gets the GenICam nodemap of the device pointed by pDevice
device_node_map = device.node_map
The nodemap can be queried for specific features, by name. If a requested feature exists, its instance is returned. Features can be of different types: Width and Height of the image, for instance, are expressed in pixels so they’re integer values. The feature ExposureTime is expressed in microseconds and it’s a float value. In python the different types are treated in the same way.
# "ReverseX" is a boolean feature
reverse_x = device_node_map.ReverseX
# "Width" is a integer feature
width = device_node_map.Width
# "ExposureTime" is a float feature
exposure_time = device_node_map.ExposureTime
# "DeviceUserID" is a string feature
device_user_id = device_node_map.DeviceUserID
# "AcquisitionMode" is a enum feature
acquisition_mode = device_node_map.AcquisitionMode
# "DeviceReset" is a command feature
device_reset = device_node_map.DeviceReset
Features must be used in different ways depending on the type. Here is a quick primer.
Boolean features#
Boolean features are simple booleans. They can be set to true/false or alternatively to 0/1.
# Flips the image sent by the device on the X axis (horizontally)
old_reverse_x = reverse_x.value
reverse_x.value = true
Integer, Float and String features#
Integer, float and string features are used in a similar fashion. To write the feature, a value of the proper type must be set. To read the feature, a variable of the proper type must be used. For instance:
# Pixels
old_width = width.value
pWidth.value = 520
# Microseconds
old_exo_time = exposure_time.value
exposure_time.value = 257000
# A user-defined ID is assigned to the camera
old_user_is = device_user_id.value
device_user_id.from_string("HelloCamera")
Integer and float features can be queried to know the maximum and minimum value supported. It’s also possible to query the minimum increment allowed between to values.
max_width = width.max
min_width = width.min
inc_width = width.inc
newWidth = minWidth + 5 * incWidth
if (newWidth <= maxWidth):
pWidth.value = newWidth
Enumeration features#
Enumeration features are full-fledged enums. Every enum feature has a set of valid entries, each one associated with an integer and its string representation.
# Get the value as integer
old_acquisition_mode_int = acquisition_mode->GetIntValue()
# Get the value as string
entry = acquisition_mode.get_entry(old_acquisition_mode_int)
old_acquisition_mode_string = pEntry->GetSymbolic()
# Set the value as integer."3" equals "Continuous" acquisition mode (see SFNC)
new_acquisition_mode = 3
acquisition_mode.set_int_value(new_acquisition_mode)
# Set the value from string
new_acquisition_mode_string = "Continuous";
acquisition_mode.from_string(new_acquisition_mode_string);
It’s also possible to work directly with the entries to leverage more complex functionalities.
Command features#
Command features lets the user submit a command to the camera by calling the Execute method.
# "DeviceReset" is a command feature which resets the device
device_reset = device_node_map.DeviceReset
device_reset.execute()
Feature checks#
Some features are not meant to be writable, like DeviceTemperature (otherwise your camera would be an oven). Other features are not writable only when the camera is in a specific state. For instance, Width is writable only if the camera is not acquiring. If the acquisition is running, the feature becomes read only. Since more complex scenarios are possible, GenApi provides functions to check the accessibility of a feature.
if (itala.is_readable(width))
width_val = width.value
if (itala.is_writable(width))
width.value = 520
If a feature is not included in a camera XML is invalid.
width_wrong_name = device.node_map.GetNode("Wwwwidth")
# or
width_wrong_name = device.node_map.Wwwwidth
if (pWidthWrongName)
{
# "Wwwwidth" isn't a valid SFNC name.
# If the camera XML doesn't include a custom feature called
# "Wwwwidth", the condition is false.
}