Chunk data¶

Opto Engineering cameras can append additional information to image data, arranged in chunks. Examples of common chunk data sent with image data are exposure time, image width and height, gain, and many others. Each value refers to the specific image it is sent with.

Each chunk is represented by a GenICam feature. To use this functionality, users must first enable chunk mode on the device, then enable each specific interested chunk. Once an image is acquired, users can access the chunk values from it.

The following sections show how to enable and retrieve chunk data for each supported language.

C++

Each chunk stored with the image can be retrieved by calling the GetChunkNode() function of the Itala::IImage interface.

1. Enable Chunk Mode

First, enable the chunk data functionality via the device nodemap.

// Enable chunk data
GenApi::CBooleanPtr pChunkModeActive = pDevice->GetNodeMap().GetNode("ChunkModeActive");
pChunkModeActive->SetValue(true);

2. Enable a Specific Chunk

Use the ChunkSelector node to select the desired chunk and ChunkEnable to enable it. This example enables the exposure time chunk.

// Get the node for chunk data selection and select exposure time chunk
GenApi::CEnumerationPtr pChunkSelector = pDevice->GetNodeMap().GetNode("ChunkSelector");
pChunkSelector->FromString("ChunkExposureTime");

// Enable the exposure time chunk data
GenApi::CBooleanPtr pChunkEnable = pDevice->GetNodeMap().GetNode("ChunkEnable");
pChunkEnable->SetValue(true);

3. Access Chunk Data from an Image

When a new image is grabbed, the chunk data nodes can be accessed via its interface.

Itala::IImage* pImage = pDevice->GetNextImage(500);

if (pImage->HasChunkData())
{
  // Read the chunk value, automatically updated by ItalaApi after grab
  GenApi::CFloatPtr pChunkExposureTime = pImage->GetChunkNode("ChunkExposureTime");
  std::cout << "Current exposure time is " << pChunkExposureTime->GetValue() << std::endl;
}

pImage->Dispose();
pImage = nullptr;

Each chunk can be retrieved by calling the IMG_GetChunkNode() function with the H_IMAGE handle.

1. Enable Chunk Mode

First, enable the chunk data functionality via the device nodemap.

// Enable chunk data
H_NODE hNodeChunkModeActive = NULL;
error = NODEMAP_GetNode(hNodeMap, "ChunkModeActive", &hNodeChunkModeActive);
error = NODE_BooleanSetValue(hNodeChunkModeActive, true);

2. Enable a Specific Chunk

Use the ChunkSelector node to select the desired chunk and ChunkEnable to enable it. This example enables the exposure time chunk.

// Get the node for chunk data selection and select exposure time chunk
error = NODEMAP_GetNode(hNodeMap, "ChunkSelector", &hNodeChunkSelector);
error = NODE_FromString(hNodeChunkSelector, "ChunkExposureTime");

// Enable the exposure time chunk data
error = NODEMAP_GetNode(hNodeMap, "ChunkEnable", &hNodeChunkEnable);
error = NODE_BooleanSetValue(hNodeChunkEnable, true);

3. Access Chunk Data from an Image

When a new image is grabbed, the chunk data nodes can be accessed.

H_IMAGE hImage = NULL;
error = DEV_GetNextImage(hDevice, 500, &hImage);

bool hasChunkData = false;
error = IMG_HasChunkData(hImage, &hasChunkData);

if (hasChunkData) {
  // Read the chunk value, automatically updated by ItalaApi after grab
  H_NODE hNodeExposureTime = NULL;
  error = IMG_GetChunkNode(hImage, "ChunkExposureTime", &hNodeExposureTime);

  float exposureTime = 0;
  error = NODE_FloatGetValue(hNodeExposureTime, &exposureTime);
  printf("Current exposure time is %f\n", exposureTime);
}

error = IMG_Dispose(hImage);
hImage = NULL;

.NET

Each chunk can be retrieved by calling the IImage.GetChunkNode function.

1. Enable Chunk Mode

First, enable the chunk data functionality via the device nodemap.

// Enable chunk data
GenApi.IBoolean chunkModeActive = device.GetNodeMap().GetNode<IBoolean>("ChunkModeActive");
chunkModeActive.Value = true;

2. Enable a Specific Chunk

Use the ChunkSelector node to select the desired chunk and ChunkEnable to enable it. This example enables the exposure time chunk.

// Get the node for chunk data selection and select exposure time chunk
GenApi.IEnumeration chunkSelector = device.GetNodeMap().GetNode<IEnumeration>("ChunkSelector");
chunkSelector.FromString("ChunkExposureTime");

// Enable the exposure time chunk data
GenApi.IBoolean chunkEnable = device.GetNodeMap().GetNode<IBoolean>("ChunkEnable");
chunkEnable.Value = true;

3. Access Chunk Data from an Image

When a new image is grabbed, the chunk data nodes can be accessed via its interface.

using (Itala.IImage image = device.GetNextImage(500))
{
  if (image.HasChunkData)
  {
    // Read the chunk value, automatically updated by ItalaApiNET after grab
    GenApi.IFloat chunkExposureTime = image.GetChunkNode<GenApi.IFloat>("ChunkExposureTime");
    Console.WriteLine("Current exposure time is " + chunkExposureTime.Value);
  }
}

.NET Framework

Each chunk can be retrieved by calling the IImage.GetChunkNode function.

1. Enable Chunk Mode

First, enable the chunk data functionality via the device nodemap.

// Enable chunk data
GenApi.IBoolean chunkModeActive = device.GetNodeMap().GetNode<IBoolean>("ChunkModeActive");
chunkModeActive.Value = true;

2. Enable a Specific Chunk

Use the ChunkSelector node to select the desired chunk and ChunkEnable to enable it. This example enables the exposure time chunk.

// Get the node for chunk data selection and select exposure time chunk
GenApi.IEnumeration chunkSelector = device.GetNodeMap().GetNode<IEnumeration>("ChunkSelector");
chunkSelector.FromString("ChunkExposureTime");

// Enable the exposure time chunk data
GenApi.IBoolean chunkEnable = device.GetNodeMap().GetNode<IBoolean>("ChunkEnable");
chunkEnable.Value = true;

3. Access Chunk Data from an Image

When a new image is grabbed, the chunk data nodes can be accessed via its interface.

Itala.IImage image = device.GetNextImage(500);
if (image.HasChunkData)
{
  // Read the chunk value, automatically updated by ItalaApiNET after grab
  GenApi.IFloat chunkExposureTime = image.GetChunkNode<GenApi.IFloat>("ChunkExposureTime");
  Console.WriteLine("Current exposure time is " + chunkExposureTime.Value);
}
image.Dispose();

Python

Each chunk can be retrieved by calling the IImage.get_chunk_node() method.

1. Enable Chunk Mode

First, enable the chunk data functionality via the device nodemap.

# Enable chunk data
chunk_mode_active = device.node_map.ChunkModeActive
chunk_mode_active.value = True

2. Enable a Specific Chunk

Use the ChunkSelector node to select the desired chunk and ChunkEnable to enable it. This example enables the exposure time chunk.

# Get the node for chunk data selection and select exposure time chunk
chunk_selector = device.node_map.ChunkSelector
chunk_selector.from_string("ChunkExposureTime")

# Enable the exposure time chunk data
chunk_enable = device.node_map.ChunkEnable
chunk_enable.value = True

3. Access Chunk Data from an Image

When a new image is grabbed, the chunk data nodes can be accessed via its interface.

image = device.get_next_image(500)

if image.has_chunk_data:
  # Read the chunk value, automatically updated by ItalaApi after grab
  chunk_exposure_time = image.get_chunk_node("ChunkExposureTime")
  print(f"Current exposure time is {chunk_exposure_time.value}")

image.dispose()

Note

Chunk feature names and types are standardized by the SFNC (Standard Feature Naming Convention), which is part of the GenICam standard. Please refer to the official SFNC document to gather information about a particular chunk. For a more in-depth description of the standard, refer to the official GenICam documentation. All material is freely accessible from the GenICam Introduction page.