Introduction

Common Vision Blox provides a flexible and structured approach to configuring the acquisition stack and connected devices. Configuration is managed through a hierarchical feature tree referred to as Node Map, and individual parameters referred to as nodes. Nodes can be queried and modified by the user.

Configuration in CVB

Device configuration is based on a collection of configurable features, each represented as a node within a node map. Device features are accessed using unique names, which may be defined in the Standard Feature Naming Convention (SFNC). This ensures consistent meaning and behavior across devices from different vendors. Writing to a node will automatically store the changes in the device independently from the transport technology (e.g. USB or ethernet) used.

C++

#include <cvb/driver/genicam_device.hpp>
#include <cvb/genapi/node_map.hpp>
 
auto nodeMap = device->NodeMap(Cvb::NodeMapID::Device);
auto exposureNode = nodeMap->Node<Cvb::FloatNode>("ExposureTime");
// Increase by 10%
exposureNode->SetValue(exposureNode->Value() * 1.1);

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
using Stemmer.Cvb.GenApi;
 
var nodes = device.NodeMaps[NodeMapNames.Device];
var exposureNode = nodes["ExposureTime"] as FloatNode;
// Increase by 10%
exposureNode.Value = exposureNode.Value * 1.1

Python

import cvb
 
node_map = device.node_maps[cvb.NodeMapID.Device]
exposure_node = node_map["ExposureTime"]
# Increase by 10%
exposure_node.value = exposure_node.value * 1.1

You can use the GenICam Browser to get an overview over all available nodes. Nodes often contain additional information about a feature like the minimum or maximum value, the unit or even a tool tip.

Quick Configuration

Quick configuration allows users to provide configuration parameters that are applied during device open. This approach ensures that the device and acquisition stack are configured in an aligned manner, reducing the need for manual adjustments after initialization. While this method is less transparent than direct node manipulation, it can be more convenient for common setups and rapid deployment.

C++

#include <cvb/device_factory.hpp>
#include <cvb/driver/genicam_device.hpp>
 
auto items = Cvb::DeviceFactory::Discover(Cvb::DiscoveryFlags::IgnoreVins);
auto& item = itemList.at(0);
// enable and attach chunk data when opening the device
item.SetParameter("AttachChunk", "1");
auto device = Cvb::DeviceFactory::Open<Cvb::GenICamDevice>(item.AccessToken(), Cvb::AcquisitionStack::GenTL);

C#

using Stemmer.Cvb;
using Stemmer.Cvb.Driver;
 
var items = DeviceFactory.Discover(DiscoverFlags.IgnoreVins);
var item = discoveredDevices[0];
// enable and attach chunk data when opening the device
item.SetParameter("AttachChunk", "1");
var device = (GenICamDevice)DeviceFactory.Open(item, AcquisitionStack.GenTL);

Python

import cvb
 
items = cvb.DeviceFactory.discover_from_root(cvb.DiscoverFlags.IgnoreVins)
item = items[0]
# enable and attach chunk data when opening the device
item.set_parameter("AttachChunk", "1")
device  = cvb.DeviceFactory.open(item.access_token, cvb.AcquisitionStack.GenTL) 

The following options are available independently from the underlying technology. See GigE Vision or USB 3 Vision for technology specific parameters.

Name	Description	Default
"AttachChunk"	Enables and attaches chunk data in the device ("0" or "1")	as device
"NumBuffer" (deprecated)	Number of buffers to allocate for acquisition. Use `Cvb::CompositeStreamBase::RegisterManagedFlowSetPool` instead.	"3"
"PixelFormat" (deprecated)	Automatically convert the pixel format (see CVB 14.0)	"5"
"RotateImage" (deprecated)	Rotate the memory view on the image buffer (see CVB 14.0)	"0"
"WidthOverride" (deprecated)	Override the image width reported by the device	not used
"HeightOverride" (deprecated)	Override the image height reported by the device. Useful for frame grabbers and line scan cameras.	not used

Scope of Configuration

Configurations can apply at different level respectively modules of the acquisition stack. Each node map is accessible through a string ID:

Device Level: Controls settings specific to the connected hardware.
Stream Level: Defines settings related to data transfer and buffering.
Interface Level: Covers configurations for network interface cards (NICs), USB host controllers, or frame grabbers.
System/Producer/TL Level: Manages settings related to the GenTL implementation itself.

Every module of the GenTL can provide a node map with potential features to configure. The above node maps can be explored in the GenICam Browser. In addition, Common Vision Blox introduces two specialized node maps:

VinDevice Node Map: Facilitates convenient and aligned configuration of both the device and acquisition stack.
VinBuffer Node Map: Provides access to metadata for each acquired payload.

Both node maps offer a node map interface but are not actual GenAPI XML node maps. The optimized access to vendor specific features, that are not covered by GenICam.

Vin related Node Maps

The VinDevice node map offers users to configure the driver-related device features. Specifically, the node map includes features that are related to TurboDrive feature, or the GenICam chunk data feature. The following list describes all available nodes that belong to the VinDevice node map:

AttachChunk: This node controls attaching chunk data to the buffers. If the device is capable of the feature, the feature can be enabled by setting true to the node .
TurboDriveEnabled: This node indicates the activation of the TurboDrive feature. If the device is capable of the feature, the feature can be enabled by setting true to the node .
TurboDriveAlgorithm: This node indicates the selection of the two options of TurboDrive versions. TurboDrive version 1 is always lossless, but does not guarantee the bandwidth. TurboDrive version 2 may be lossy, but guarantees the bandwidth.
Quality: This node indicates the level for even lines or the global quality level for mono images. The quality level sets the lowest bits per pixel to be discarded. The value is of type integer and valid values are between 0 and 6, with 0 indicating always lossless encoding and 6 the highest level compression. A high value is not necessarily lossy, but more likely to be lossy.
QualityOddLines: This node is for quality level for odd lines in bayer images. Its properties are same as the Quality node for even lines.

The VinBuffer node map provides means to gather information about a single buffer returned/delivered by the stream's Wait method call. The VinBuffer node maps the following feature nodes:

FrameID: The unique ID of the frame (or image) that is transported in the corresponding buffer if applicable.
GenDCComponentSelector: If the delivered payload is a GenDC container the node values below refer to the selected component.
IsIncomplete: If its value is true, it indicates that the buffer data is not logically complete. In case of incomplete transmission for some reasons such as missing packets, the number of bytes successfully written to the buffer are reported in the SizeFilled node.
SizeFilled: The total number of bytes written into the buffer. In case of incomplete transmission, this node reports the number of bytes successfully written to the buffer.
Timestamp: An unsigned 64-bit integer representation of a timestamp generated when the buffer filled up with the deliverable data. The unit depends on the reporter such as a device or a transport layer. In case the technology and/or the device does not support the feature, this node value is not available.

Node and Node Map Lifetime

The CVB acquisition stack manages the lifetime of all node maps and nodes automatically using a reference counting mechanism. In addition a node will keep the node map alive and the node map will keep its provider alive.

Warning: Keeping nodes or nod maps alive that refer to a flow set pool can cause the acquisition engine to run out of buffers. See acquisition and streaming for details.

Acquisition Statistics

The data stream node map provides both standard and vendor-specific nodes that offer insights into the acquisition engine. These statistics include buffer states, lost packets, and resend requests in the case of GigE Vision (GEV). Monitoring these values helps diagnose performance issues and optimize data flow within the acquisition pipeline.

Examples

Example	Description
Vin Node Maps	Accessing the Vin node maps.
Software Trigger	Configuring and sending a software trigger.

Table of Contents