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 H_DEVICE
handle. Note that H_NODEMAP
refers to the GenApi
namespace since it’s provided by the GenApi library, developed by the GenICam group.
// Gets the nodemap of the device with handle hDevice
H_NODEMAP hNodeMap = NULL;
error = DEV_GetNodeMap(hDevice, &hNodeMap);
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. GenApi offers different pointers to work with different feature types.
// "ReverseX" is a boolean feature
H_NODE hReverseX = NULL;
error = NODEMAP_GetNode(hNodeMap, &hReverseX);
// "Width" is a integer feature
H_NODE hWidth = NULL;
error = NODEMAP_GetNode(hNodeMap, &hWidth));
// "ExposureTime" is a float feature.
H_NODE hExposureTime = NULL;
error = NODEMAP_GetNode(hNodeMap, &hExposureTime);
// "DeviceUserID" is a string feature.
H_NODE hDeviceUserID = NULL;
error = NODEMAP_GetNode(hNodeMap, &hDeviceUserID);
// "AcquisitionMode" is a enum feature.
H_NODE hAcquisitionMode = NULL;
error = NODEMAP_GetNode(hNodeMap, &hAcquisitionMode);
// "DeviceReset" is a command feature
H_NODE hDeviceReset = NULL;
error = NODEMAP_GetNode(hNodeMap, &hDeviceReset);
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)
bool oldReverseX = false;
error = NODE_BooleanGetValue(hReverseX, &oldReverseX);
error = NODE_BooleanGetValue(hReverseX, 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
int64_t oldWidth = 0;
error = NODE_IntegerGetValue(hWidth, &oldWidth);
error = NODE_IntegerSetValue(hWidth, 520);
// Microseconds
float oldExpTime = 0;
error = NODE_FloatGetValue(hExposureTime, &oldExpTime);
error = NODE_FloatSetValue(hExposureTime, 257000);
// A user-defined ID is assigned to the camera
char oldUserId[255];
size_t sizeMessage = 255;
error = NODE_StringGetValue(hDeviceUserID, oldUserId, &sizeMessage);
error = NODE_StringSetValue(hDeviceUserID, "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.
int64_t maxWidth = 0;
error = NODE_IntegerGetMax(hWidth, &maxWidth);
int64_t minWidth = 0;
error = NODE_IntegerGetMin(hWidth, &minWidth);
int64_t incWidth = 0;
error = NODE_IntegerGetInc(hWidth, &incWidth);
int64_t newWidth = minWidth + 5 * incWidth;
if(newWidth <= maxWidth){
error = NODE_IntegerGetValue(hWidth, 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
int64_t oldAcquisitionModeInt = 0;
error = NODE_EnumerationGetIntValue(hAcquisitionMode, &oldAcquisitionModeInt);
H_NODE hEntry = NULL;
error = NODE_EnumerationGetEntryByIntValue(hAcquisitionMode, oldAcquisitionModeInt, &hEntry);
// Get the value as string
size_t sizeAcqOld = 255;
char acquisitionModeString[255];
error = NODE_EnumEntryGetSymbolic(hEntry, acquisitionModeString, &sizeAcqOld);
// Set the value as integer."3" equals "Continuous" acquisition mode (see SFNC)
int64_t newAcquisitionMode = 3;
error = NODE_EnumerationSetIntValue(hAcquisitionMode, newAcquisitionMode);
// Set the value from string
error = NODE_FromString(hAcquisitionMode, "Continuous");
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
error = NODE_CommandExecute(hDeviceReset);
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.
bool isReadable = false;
error = IsNodeReadable(hWidth, &isReadable);
if(isReadable){
int64_t widthValue=0;
error = NODE_IntegerGetValue(hWidth, &widthValue):
}
bool isWritable = false;
error = IsNodeWritable(hWidth, &isWritable);
if(isWritable){
error = NODE_IntegerSetValue(hWidth, 520):
}
If a feature is not included in a camera XML or it’s retrieved and assigned to the wrong type, its pointer is invalid.
H_NODE hWidthWrong = NULL;
error = NODEMAP_GetNode(hNodeMap, "Wwwwwwwwidth", &hWidthWrong);
if(hWidthWrong){
// "Wwwwidth" isn't a valid SFNC name.
// If the camera XML doesn't include a custom feature called
// "Wwwwidth", the condition is false.
}