Metadata Insertion

Introduction

The Metadata Insertion feature allows line-scan applications to insert metadata into a buffer.

Two types of metadata can be inserted into a buffer:

●

Buffer metadata: 4x32-bit metadata are inserted into an internal header information of the buffer;

●

Line metadata: 4x32-bit metadata are inserted at the end of each image line within the buffer.

These two types of metadata can be inserted independently or simultaneously.

Requirements

Only available on grabber-controlled cycle-start camera control methods (RG and RC).

The metadata are sampled on the CycleStart events of the CIC:

●

Buffer metadata are sampled on the CycleStart event that initiates the first line of the buffer

●

Line metadata are sampled on each CycleStart event

Configuration

The MetadataInsertion category of the Data Stream module contains the features for configuring metadata insertion.

Each MetadataInsertion feature responsible for configuring metadata insertion must be set before starting an acquisition.

When an acquisition is started, the features are locked.

Activation of the metadata

●

BufferMetadataInsertionEnable: Boolean feature to enable/disable the insertion of 4x32-bit (16 bytes) metadata for the buffer

●

LineMetadataInsertionEnable: Boolean feature to enable/disable the insertion of 4x32-bit (16 bytes) metadata at the end of each image line

Enabling the insertion of buffer metadata does not affect the payload size of the buffer.

However, enabling the insertion of line metadata does affect the payload size of the buffer.

When LineMetadataInsertionEnable = True, the data stream feature LineWidth is automatically increased by 16 to count for the size of the line metadata, which in turn may increase the data stream PayloadSize (or consume some of the padding part of the buffer, if used).

NOTE:

the size of the padding on a line, is always the difference between LinePitch and LineWidth, if LinePitch > LineWidth. When padding is added together with line metadata insertion, the padding part is located after the line metadata (image line - line metadata - padding).

See also: Image Data Padding.

Contents of the metadata

The metadata can contain GPC values, QDC positions, and/or I/O line states.

The contents of the metadata are configured with the features MetadataContent<N>, where N represents the offset, from 0 to 3, of one 32-bit metadata within a chunk of 128-bit metadata.

These four features describe the contents to be reported in both the buffer and line metadata.

The features can report the following contents:

On CycleStart event, the selected contents are sampled. Their values will be inserted in the buffer and/or the line metadata.

General Purpose Counter (GPC)

Four 32-bit General Purpose Counters can be used in various ways, e.g., to count the number of occurrences of a particular event, to implement a differential counter between two event streams, or even to latch a counter on a particular event. The latch functionality can be useful for permanent period measurements.

The GPCs are selected through GeneralPurposeCounterSelector and enabled/disabled with GeneralPurposeCounterEnable.

Up to three event sources can be set to define the behavior of a GPC:

●

GeneralPurposeCounterIncrementSource: selects an event stream used as trigger to increment the selected GPC

●

GeneralPurposeCounterDecrementSource: selects an event stream used as trigger to decrement the selected GPC

●

GeneralPurposeCounterLatchAndResetSource: selects an event stream used as trigger to latch and reset the selected GPC

When GeneralPurposeCounterEnable=False, the selected counter is reset.

Example 1

To count the difference between CycleStart and StartOfLine with GPC1:

●

Set GeneralPurposeCounterSelector to GPC1.

●

Set GeneralPurposeCounterIncrementSource to CycleStart.

●

Set GeneralPurposeCounterDecrementSource to StartOfLine.

●

Set GeneralPurposeCounterLatchAndResetSource to NONE.

●

Set GeneralPurposeCounterEnable to True.

To report the value of GPC1 in the metadata:

●

Set MetadataContent0 to GPC1Value.

NOTE:

the value of this GPC in the metadata will always be greater than 0. That is because the GPC is sampled on CycleStart, while StartOfLine will always happen after CycleStart.

Example 2

To measure the cycle period with GPC2:

●

Set GeneralPurposeCounterSelector to GPC2.

●

Set GeneralPurposeCounterIncrementSource to TIME16NS.

●

Set GeneralPurposeCounterDecrementSource to NONE.

●

Set GeneralPurposeCounterLatchAndResetSource to CycleStart.

●

Set GeneralPurposeCounterEnable to True.

To report the latched value of GPC2 in the metadata:

●

Set MetadataContent1 to GPC2LatchedValue.

Getting metadata

●

To get the buffer metadata of a buffer, use the commands BUFFER_INFO_CUSTOM_BUFFER_METADATA_<N> from BUFFER_INFO_CUSTOM_CMD_LIST, where N is the offset from 0 to 3.

The commands return the 32-bit inserted buffer metadata at offset N.

If no buffer metadata was inserted in the buffer, BUFFER_INFO_CUSTOM_BUFFER_METADATA_<N> commands return GC_ERR_NOT_AVAILABLE.

●

To get the line metadata of a buffer, use the command BUFFER_INFO_CUSTOM_LINE_METADATA_BASE from BUFFER_INFO_CUSTOM_CMD_LIST.

The command returns a pointer to the base address of the inserted line metadata.

If no line metadata was inserted in the buffer, BUFFER_INFO_CUSTOM_LINE_METADATA_BASE command returns 0.

●

To get the type of content of an inserted metadata in a buffer, use the commands BUFFER_INFO_CUSTOM_METADATA_CONTENT_<N> from BUFFER_INFO_CUSTOM_CMD_LIST, where N is the offset from 0 to 3.

The commands return an integer that identify the type of content that the buffer and/or line metadata contain at offset N.

The values returned by the BUFFER_INFO_CUSTOM_METADATA_CONTENT_<N> commands are translated as follows:

Value	BUFFER_INFO_CUSTOM_METADATA_CONTENT_0	BUFFER_INFO_CUSTOM_METADATA_CONTENT_1	BUFFER_INFO_CUSTOM_METADATA_CONTENT_2	BUFFER_INFO_CUSTOM_METADATA_CONTENT_3
1	GPC1Value	GPC2Value	GPC3Value	GPC4Value
2	GPC1LatchedValue	GPC2LatchedValue	GPC3LatchedValue	GPC4LatchedValue
3	QDC1Position	QDC2Position	QDC3Position	QDC4Position
4			LineStatusAllHi	LineStatusAll

If neither buffer nor line metadata were inserted, BUFFER_INFO_CUSTOM_METADATA_CONTENT_<N> commands return GC_ERR_NOT_AVAILABLE.

See also: cpp/330-metadata-insertion sample program