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 IDevice interface. Note that INodeMap belongs to the GenApi namespace since it’s provided by the GenApi library, developed by the GenICam group.

//Gets the GenICam nodemap of the device pointed by pDevice
GenApi::INodeMap& deviceNodemap = pDevice->GetNodeMap();

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
GenApi::CBooleanPtr pReverseX = deviceNodemap.GetNode("ReverseX");

// "Width" is a integer feature
GenApi::CIntegerPtr pWidth = deviceNodemap.GetNode("Width");

// "ExposureTime" is a float feature.
GenApi::CFloatPtr pExposureTime = deviceNodemap.GetNode("ExposureTime");

// "DeviceUserID" is a string feature.
GenApi::CStringPtr pDeviceUserID = deviceNodemap.GetNode("DeviceUserID");

// "AcquisitionMode" is a enum feature.
GenApi::CEnumerationPtr pAcquisitionMode = deviceNodemap.GetNode("AcquisitionMode");

// "DeviceReset" is a command feature
GenApi::CCommandPtr pDeviceReset = deviceNodemap.GetNode("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)
bool oldReverseX = pReverseX->GetValue();
pReverseX->SetValue(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 = pWidth->GetValue();
pWidth->SetValue(520);

// Microseconds
float oldExpTime = pExposureTime->GetValue();
pExposureTime->SetValue(257000);

// A user-defined ID is assigned to the camera
GenICam::gcstring oldUserID = pDeviceUserID->GetValue();
pDeviceUserID->FromString("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 = pWidth->GetMax();
int64_t minWidth = pWidth->GetMin();
int64_t incWidth = pWidth->GetInc();

int64_t newWidth = minWidth + 5 * incWidth;

if (newWidth <= maxWidth)
        pWidth->SetValue(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 = pAcquisitionMode->GetIntValue();

// Get the value as string
GenApi::CEnumEntryPtr pEntry = pAcquisitionMode->GetEntry(oldAcquisitionModeInt);
GenICam::gcstring oldAcquisitionModeString = pEntry->GetSymbolic();

// Set the value as integer."3" equals "Continuous" acquisition mode (see SFNC)
int64_t newAcquisitionMode = 3;
pAcquisitionMode->SetIntValue(newAcquisitionMode);

// Set the value from string
GenICam::gcstring newAcquisitionModeString = "Continuous";
pAcquisitionMode->FromString(newAcquisitionModeString);

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
GenApi::CCommandPtr pDeviceReset = deviceNodemap.GetNode("DeviceReset");
pDeviceReset->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 (GenApi::IsReadable(pWidth))
        int64_t width = pWidth->GetValue();

if (GenApi::IsWritable(pWidth))
        pWidth->SetValue(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.

pWidthWrongName = deviceNodemap.GetNode("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.
}

GenApi::CFloatPtr pWidthWrongType = deviceNodemap.GetNode("Width");
if (pWidthWrongType)
{
    // If the camera implements the "Width" feature, it has to be an integer.
    // The condition is false.
}