Data Chunks#

The Data Chunks camera feature allows you to generate supplementary image data and append that data to every image that you acquire.

Using the Feature#

How It Works#

Data chunks allow you to add supplementary information to individual image acquisitions. The desired supplementary information is generated and appended as data chunks to the image data.

Image data is also considered a "chunk". This "image data chunk" can't be disabled and is always the first chunk transmitted by the camera. If one or more data chunks are enabled, these chunks are transmitted as chunk 2, 3, and so on.

The figure below shows a set of chunks with the leading image data chunk and appended data chunks. The example assumes that the CRC checksum chunk feature is enabled.

After data chunks have been transmitted to the computer, they must be retrieved to obtain their information. The exact procedure depends on your camera model and the programming language used for your application. For more information about retrieving data chunks, see the pylon API Documentation.

Additional Metadata#

Besides the data chunks, the camera adds additional metadata to individual images, e.g., the image height, image width, the image ROI offset, and the pixel format used. This information can be retrieved by accessing the grab result data via the pylon API.

Enabling and Retrieving Data Chunks#

1. Set the ChunkModeActive parameter to true.
2. Set the ChunkSelector parameter to the kind of chunk that you want to enable (if available):
   • AutoBrightnessStatus
   • CounterValue
   • ExposureTime
   • FocusIndicator
   • Framecounter
   • FrameID
   • Gain
   • LineStatusAll
   • PayloadCRC16
   • SequenceSetIndex or SequencerSetActive
   • Timestamp
   • Triggerinputcounter
3. Enable the selected chunk by setting the ChunkEnable parameter to true.
4. Repeat steps 2 and 3 for every desired chunk.
5. Implement chunk retrieval in your application.
   For information about implementing chunk retrieval, see the pylon API Documentation.

Available Data Chunks#

Auto Brightness Status Chunk#

If this chunk is available and enabled, the camera appends the status of the target brightness adjustments to every image.

Target brightness adjustments are performed whenever the Exposure Auto or the Gain Auto auto function or both are enabled.

• On ace 2, boost, and dart M/R cameras, the BslChunkAutoBrightnessStatus parameter is available. It indicates the auto brightness status using the following enumeration:

  • Disabled: Target brightness adjustments are disabled, i.e., Gain Auto and Exposure Auto are set to Off.
  • TargetNotReached: Target brightness adjustments are enabled, but the target brightness value has not been reached.
  • TargetReached: Target brightness adjustments are enabled, and the target brightness value has been reached.

• On other cameras, the status is indicated using the following values:

  • 0: Equals the Disabled status, see above.
  • 1: Equals the TargetNotReached status, see above.
  • 2: Equals the TargetReached status, see above.

Counter Value Chunk#

If this chunk is available and enabled, the camera appends the current value of the camera's counter to every image.

• On ace 2, boost, and dart M/R cameras, the ChunkCounterSelector parameter is available. It allows you to choose which counter to retrieve data from. To do so, set the parameter to Counter1 or Counter2.
• On other cameras, the camera always retrieves the current value of Counter 1, which counts the number of acquired images.

Exposure Time Chunk#

If this chunk is enabled, the camera appends the exposure time used for image acquisition to every image.

The data chunk includes the ExposureTime and the ChunkExposureTimeSelector parameter values.

The ChunkExposureTimeSelector parameter selects the exposure time to be included in the exposure time chunk.

Focus Indicator Chunk#

If this chunk is available and enabled, the camera appends a value indicating the level of focus in every acquired image.

The value can range from 0.0 to 4095.0. A higher value indicates a higher level of focus. Calculations are based on a 5x5 sharpness detection algorithm.

A typical use case of the focus indicator chunk would be to monitor changes in the chunk value while the lens is being focused. For example, if the value after continuously increasing starts to decrease, this may indicate that a good level of focus has been reached.

Changes in the scene, e.g., increased brightness, will affect the chunk value. Therefore, while monitoring the chunk value, make sure that the target scene doesn't change.

Focus Indicator ROIs#

By default, the camera uses almost the full image ROI to calculate the level of focus.

You can change this and specify up to two parts of the sensor array that should be used to calculate the level of focus. Doing so is similar to setting up an auto function ROI. Two focus indicator ROIs are available.

To configure the focus indicator ROIs:

1. Set the BslFocusIndicatorROISelector parameter to the desired focus indicator ROI, e.g., ROI1.
2. Set the BslFocusIndicatorROIEnable parameter to true to enable the focus indicator ROI selected.
   By default, ROI 1 is enabled and ROI 2 is disabled.
3. Enter values for the following parameters to specify the position of the focus indicator ROI selected:
   • AutoFunctionROIOffsetX (see note below)
   • AutoFunctionROIOffsetY
4. Enter values for the following parameters to specify the size of the focus indicator ROI selected:
   • AutoFunctionROIWidth
   • AutoFunctionROIHeight

Frame Counter Chunk#

If this chunk is available and enabled, the camera appends the number of acquired images to every image.

To do so, the camera retrieves the current value of the Counter 2 counter. On cameras with the Frame Counter chunk, Counter 2 counts the number of acquired images.

To manually reset the counter, reset Counter 2.

Frame ID Chunk#

If this chunk is available and enabled, the camera appends the frame ID indicating the number of the image that has been exposed.

The frame ID starts at 0 and keeps incrementing by 1 for each exposed image until the camera is powered off. The maximum value is 2^48.

Gain Chunk (= GainAll Chunk)#

If this chunk is available and enabled, the camera appends the gain used for image acquisition to every image.

The data chunk includes the Gain parameter value.

Line Status All Chunk#

If this chunk is enabled, the camera appends the status of all I/O lines at the moment when image acquisition was triggered to every image.

The data chunk includes the LineStatusAll parameter value.

Payload CRC 16 Chunk#

If this chunk is enabled, the camera appends a CRC (Cyclic Redundancy Check) checksum to every image.

The checksum is calculated using the X-modem method and includes the image data and all appended chunks, if any, except the CRC chunk itself.

The CRC checksum chunk is always the last chunk appended to image data.

Sequencer Set Active Chunk (= Sequence Set Index Chunk)#

If this chunk is available and enabled, the camera appends the sequencer set used for image acquisition to every image.

The data chunk includes the SequencerSetActive or SequenceSetIndex parameter value (depending on your camera model).

Timestamp Chunk#

If this chunk is enabled, the camera appends an internal timestamp (in ticks) of a certain event to every image.

• On ace 2, boost, and dart M/R cameras, the parameter including the timestamp is named BslChunkTimestampValue.
  Also, the BslChunkTimestampSelector parameter is available, which allows you to choose the type of event that the timestamp should refer to:

  • FrameStart: The BslChunkTimestampValue parameter indicates when acquisition of the current image started.
  • ExposureStart: The BslChunkTimestampValue parameter indicates when exposure of the current image started. On rolling shutter cameras, the parameter indicates when exposure of the first row started.
  • ExposureEnd: The BslChunkTimestampValue parameter indicates when exposure of the current image ended. On rolling shutter cameras, this parameter serves no function and is preset to 0.

• On other cameras, the parameter including the timestamp is named ChunkTimestamp. It always indicates when acquisition of the current image started.

Trigger Input Counter Chunk#

If this chunk is available and enabled, the camera appends the number of hardware frame start trigger signals received to every image.

To do so, the camera retrieves the current value of the Counter 1 counter. On cameras with the Trigger Input Counter chunk, Counter 1 counts the number of hardware trigger signals received.

Specifics#

Show all camera models

Sample Code#

// Enable data chunks
camera.ChunkModeActive.SetValue(true);
// Select a chunk, e.g., the Exposure Time chunk
camera.ChunkSelector.SetValue(ChunkSelector_ExposureTime);
// Enable the selected chunk
camera.ChunkEnable.SetValue(true);
// Now, you must implement chunk retrieval in your application.
// For C++, C, and .NET sample implementations, see the "Grab_ChunkImage" and
// "Chunks" code samples in the pylon API Documentation

INodeMap& nodemap = camera.GetNodeMap();
// Enable data chunks
CBooleanParameter(nodemap, "ChunkModeActive").SetValue(true);
// Select a chunk, e.g., the Exposure Time chunk
CEnumParameter(nodemap, "ChunkSelector").SetValue("ExposureTime");
// Enable the selected chunk
CBooleanParameter(nodemap, "ChunkEnable").SetValue(true);
// Now, you must implement chunk retrieval in your application.
// For C++, C, and .NET sample implementations, see the "Grab_ChunkImage" and
// "Chunks" code samples in the pylon API Documentation

// Enable data chunks
camera.Parameters[PLCamera.ChunkModeActive].SetValue(true);
// Select a chunk, e.g., the Exposure Time chunk
camera.Parameters[PLCamera.ChunkSelector].SetValue(PLCamera.ChunkSelector.ExposureTime);
// Enable the selected chunk
camera.Parameters[PLCamera.ChunkEnable].SetValue(true);
// Now, you must implement chunk retrieval in your application.
// For C++, C, and .NET sample implementations, see the "Grab_ChunkImage" and
// "Chunks" code samples in the pylon API Documentation

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
/* Enable data chunks */
errRes = PylonDeviceSetBooleanFeature(hdev, "ChunkModeActive", 1);
CHECK(errRes);
/* Select a chunk, e.g., the Exposure Time chunk */
errRes = PylonDeviceFeatureFromString(hdev, "ChunkSelector", "ExposureTime");
CHECK(errRes);
/* Enable the selected chunk */
errRes = PylonDeviceSetBooleanFeature(hdev, "ChunkEnable", 1);
CHECK(errRes);
/* Now, you must implement chunk retrieval in your application. */
/* For C++, C, and .NET sample implementations, see the "Grab_ChunkImage" and */
/* "Chunks" code samples in the pylon API Documentation */

# Enable data chunks
camera.ChunkModeActive.Value = True
# Select a chunk, e.g., the Exposure Time chunk
camera.ChunkSelector.Value = "ExposureTime"
# Enable the selected chunk
camera.ChunkEnable.Value = True
# Now, you must implement chunk retrieval in your application.
# For C++, C, and .NET sample implementations, see the "Grab_ChunkImage" and
# "Chunks" code samples in the pylon API Documentation

You can also use the pylon Viewer to easily set the parameters.