Operator Library: Hardware Platform
This operator represents the image data interface between a CXP dual-tap camera and VisualApplets. You can use the operator for single channel, dual channel or quad channel CXP interfaces. You select the type of interface with the parameter ConnectionCount. The operator outputs raw image data for each tap port, no matter which format the camera delivers. You then need to convert this image data into the format sent by the camera. To convert the image data, use appropriate operators for aggregating and casting raw byte values to pixel values. Certain situations during operation may be communicated via the event system as described below. Additionally, the operator has various parameters signaling the status of the connection to the camera.
Available for Hardware Platforms |
---|
imaFlex CXP-12 Quad |
CXP Standard Multi-Tap Definition
Usually, the image pixels are scanned sequentially from the top left to the bottom right. However, with the steadily growing number of pixels on modern image sensors, this approach does not produce acceptable frame rates. To tackle this issue, sensor manufacturers help themselves by scanning multiple pixels at the same time. The CXP standard accommodates this technique by introducing the concept of taps. A tap can be seen as a scanning device, which reads the image pixels sequentially. The way an image is scanned is defined as the Tap Geometry, which the host reads from the device.
Taps Apply to Vertical Scanning Only | |
---|---|
Taps apply to vertical scanning only. Horizontal scanning is fixed from left to right. |
It is recommended in the CXP standard, that a frame grabber host supports the three tap formats 1X-1Y, 1X-1Y2, and 1X-2YE. The tap format 1X-1Y represents the default characteristic scanning the image pixel by pixel from top left to bottom right, while the other formats represent two tap geometries, that are depicted in the following figure:
Although data from each tap is formed into
separate streams, it is important to note that there is no fixed mapping between the
stream-ID and the tap. However, it is safe to assume, that this mapping remains constant
during acquisition. The TapG
code, and thus, the required information to
find this mapping, is provided in the CXP image header, which can be read on the
optional MetaDataTap0/1 ports.
Tap Format | TapG Code |
---|---|
1X-1Y | 0x0000 |
1X-1Y2, tap 1 | 0x0004 |
1X-1Y2, tap 2 | 0x1004 |
1X-2YE, tap 1 | 0x0041 |
1X-2YE, tap 2 | 0x1041 |
Flipping the Lower Half of the Image Is Not the Responsibility of this Operator | |
---|---|
Flipping the lower half of the image in the case of the 1X-2YE tap format is not the responsibility of this CxpCameraMultiTap operator. The user application needs to reformat the tap(1) by using additional VisualApplets operators. |
Instantiation in VisualApplets
The operator provides image data on its output tap. This output is always present. It is 1 for the single tap and needs to be set to 2 for the dual-tap cameras. In addition to this standard output ports, you can configure an optional MetaData output for the CXP header metadata for each tap output exclusively, i.e. for dual-tap application you can define up to 2 MetaDataTap ports. The following pop-up dialog appears during operator instantiation and can be configured to the following permutations:
Figure 441. This configuration is equivalent to a simpler CxpCamera operator with only O output and no meta data.
Figure 442. This configuration is equivalent to a simpler CxpCamera operator with port O and MetaDataO selected.
Figure 443. In this configuration only the tap 0 is output with its metadata. For the tap 1 only the metadata is output. This configuration can be useful for debugging a camera/frame grabber combination.
Figure 444. In this configuration the operator provides both camera taps as 2 separate data streams on its Tap0 and Tap1 ports. However, no metadata information is output.
Figure 445. In this configuration the operator provides both camera taps as 2 separate streams on its Tap0 and Tap1 ports. The operator provides also the meta information for the Tap0 port. This configuration might be meaningful for symmetrical camera tap configurations, where the CXP header is in most parts identical for both taps except for the TapG Code fields.
Figure 446. This is the maximal configuration of the operator, where for each tap an own output is presented together with its own metadata.
Optional MetaDataTap Port
The format for both metadata ports is identical. It is provided in VisualApplets as 32-bit output and is shown in the following picture:
Each CXP frame provides a corresponding error-free image header. For incorrect image headers, no image stream data is sourced into the VisualApplets pipeline. The compressed image header consist of 6 words. The last byte is used for additional information, which is for internal usage only. Particularly, the HeaderError bit informs whether the image header itself has an error or not.
Image Header | Description |
---|---|
StreamId | ID of the CXP stream |
Tag | 16-bit source image index. It is incremented for each transferred image, wraps around to 0 at 0xFFFF. The same number shall be used by each stream containing data relating to the same image (in case of multi-tap streams). |
XSize | 24-bit value representing the image width in pixels. |
XOff | 24-bit value representing the horizontal offset in pixels of the image with respect to the left hand pixel of the full device image. |
YSize | 24-bit value representing the image height in pixels. This value is set to 0 for line scan images. |
YOff | 24-bit value representing the vertical offset in pixels of the image with respect to the top line of the full device image. This value is set to 0 for line scan images. |
DSizeL | 24-bit value representing the number of data words per image line. |
PixelF | 16-bit value representing the pixel format. |
TapG | 16 bit value representing the tap geometry. |
Flags | Image flags. |
x-Mirror | (Not used yet). Describes whether the incoming image is x-mirrored or not. |
y-Mirror | (Not used yet). Describes whether the incoming image is y-mirrored or not. |
HeaderError |
1: Image header has an error and the frame is declared as lost. No corresponding image data exists in the operator output data stream. 0: Image header is correct and a corresponding image data exists in the operator output data stream. |
Modifying Image Width and Image Height | |
---|---|
Via the maximum image width and height properties of the output link you can adjust width and height to the camera-specific settings. However, the maximum image width on operator port O must be divisible by the parallelism of port O. Thus, make sure the maximum image width is divisible by the parallelism of port O! |
Device Resource Usage
The operator uses one or more resources of type CameraPort depending on the selection of the parameter ConnectionCount. For the event system a resource of the type EventPort is used. If ConnectionCount is set to X4 (quad channel), the following resource dialog opens up:
Error Handling and Event System
When the operator detects that the received reconstructed frame is larger or smaller than what was promoted by the camera in the CXP image header, a safety circuit gets activated. The operator then cuts off exceeding pixels and lines, so that the subsequent processing pipeline always sees the frame size which was defined in the image header. If the received frame is smaller in its dimensions than what was specified in the image header, the operator fills up the received frame with undefined data to achieve the specified frame dimensions which were defined in the image header. Filling up a smaller frame can cause the follow-up frames to get lost. The loss is then reported per event to the runtime software (Framegrabber SDK)(see the following paragraph). The size mismatch causes an event, too.
For a set of very critical errors, the operator will forward asynchronous events to the host runtime software (Framegrabber SDK). The event name in the Framegrabber API is <hierarchical operator name>\CxpStreamStatus, e.g. Device1\Process0\Camera\CxpStreamStatus. The event payload is provided as four 16-bit data words. The event format is defined as follows:
-
word [0]:
-
bits [0:15]: CXP image tag in which the event occurred.
-
-
word [1]:
-
bits [8:15]: stream-ID in which the event occurred.
-
bits [0:7]: reserved, treat as don't care.
-
-
word [2]:
-
bit [0]: CRC error occurred.
-
bit [1]: stream marker error detected in the image header.
-
bit [2]: An error in the image header was detected which could not be corrected.
-
bit [3]: A frame size error was detected, i.e. the image size defined in the CXP image header is not matching the reconstructed frame size from the transmitted packets. This happens when the camera puts one info into the image header but transmits different amount of data as promoted in the header.
-
bits [4:15]: reserved, treat as don't care.
-
-
word [3]:
-
bit [0]: Event type, 0 = Corrupted Entity, 1 = Lost Entity.
-
Corrupted Entity means that the error happens within a frame and that this frame is already sourced into the VisualApplets pipeline.
-
Lost Entity means that the error occurred before the frame was forwarded to the following operators and the frame was discarded by the camera operator.
-
When a corrupted entity is observed, the operator will fill up the frame according to the CXP image header definition so that the following operators will not cause undefined behavior. During this fill-up, a new frame may arrive and will then get lost. The lost entity event will also be raised when the camera sends data with a gap according to the frame tag.
-
-
bit [1]: An event loss for type Corrupted Entity occurred. This means that preceding events of type Corrupted Entity got lost. This happens when the runtime software is not reacting to events and the internal event queues ran full.
-
bit [2]: An event loss for type Lost Entity occurred. This means that preceding events of type Lost Entity got lost. This happens when the runtime software is not reacting to events and the internal event queues ran full.
-
bits [3:15]: amount of lost Lost Entity events.
-
There are two types of events: events for corrupted entities and events for lost entities. Bit 0 of word 3 describes which kind of event occurred. If the event buffers are full, it might happen that events get lost. When an event gets lost that marks a corrupted entity, bit 1 of word 3 will be set. When an event gets lost that marks a lost entity, bit 2 of word 3 will be set and bit 3 to 15 will provide the number of lost events indicating a lost frame. If bit 2 is set but the counter is 0, it means that a counter overflow happened.
Every event causes a software interrupt. To reduce the number of events, several events with the same frame tag might be merged together. In that case some error flags are combined. If an event was lost, the event before the lost event contains the information about the lost event and cannot be merged with further events with the same frame tag.
The events caused due to CRC errors report a frame tag, which may not be exactly related to the frame in which the CRC errors happen. The frame tag can be that of the preceding or following frame. This can only happen, when a camera sends a CXP packet, which contains a transition between 2 or more frames. The CRC computation is finished at the end of the packet, but the stream data is reconstructed on-the-fly. This means that a situation can happen, in which a CRC error is detected only after the preceding frame was already sent by the operator. In normal situations, in which the camera packets don't contain data both of the end of the ongoing frame and the beginning of the next frame, the frame tag during CRC error will always be correct. For all other cases as long as the complete frame stream data is less than the maximal packet size of 8k, there might be only 1 frame overlap within 1 packet. In that case, the software application should consider the preceding frame with the frame tag - 1 and the following frame with the frame tag + 1 as potentially corrupted as well.
Differentiating Error Events Between Taps | |
---|---|
The error handling and event system are common to both CXP tap streams. Use the stream-ID field to relate the received event to the appropriate tap. Normally, Tap 0 will get a lower stream-ID, typically 0. Tap 1 will get a stream-ID, which is larger than the one of Tap 0. |
Property | Value |
---|---|
Operator Type | M |
Output Links | Tap0/Tap1, image data output MetaDataTap0/MetaDataTap1, optional meta data output |
Link Parameter | Output Link Tap0/Tap1 | Output Link MetaDataTap0/MetaDataTap1 |
---|---|---|
Bit Width | 8 | 32 |
Arithmetic | unsigned | unsigned |
Parallelism | auto | 1 |
Kernel Columns | 1 | 1 |
Kernel Rows | 1 | 1 |
Img Protocol | {VALT_IMAGE2D, VALT_LINE1D} (default: VALT_IMAGE2D) | {VALT_IMAGE2D, VALT_LINE1D, VALT_PIXEL0D} (default: VALT_IMAGE2D) |
Color Format | VAF_GRAY | VAF_GRAY |
Color Flavor | FL_NONE | FL_NONE |
Max. Img Width | any (default: 1032) | 6 |
Max. Img Height | any (default: 1032) | 1 |
ConnectionCount | ||||
---|---|---|---|---|
Type | Static Write parameter | |||
Default | X1 | |||
Range | {X1, X2, X4} | |||
The parameter ConnectionCount defines the number of CXP lanes aggregated to the CXP link. The indices of the used connection ports are handled by resources of the type CameraPort. The number of port resources matches the connection count (e.g. X2: two CameraPort resource items). When you instantiate more than one CxpCamera operator (e.g. for dual-camera applet), resource conflicts may occur when multiple resources with the same index are used or when the number of consumed CameraPort resources exceeds the maximum of 4. In this case, the design rules check reports an error.
|
ResetStatus | ||||
---|---|---|---|---|
Type | Dynamic Write parameter | |||
Default | Off | |||
Range | {Off, On} | |||
The parameter ResetStatus resets the camera statistics, i.e. the error counters.
|
UsedConnections | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | {1,2,4} | |||
The parameter UsedConnections shows the amount of CXP lanes configured by the discovery software at runtime.
|
PacketTagErrorCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 8191] | |||
The parameter PacketTagErrorCount shows how many received packets have a tag that is non-compliant with the expected tag according to the CXP standard. In particular, this value is counting up when gaps are observed in following stream packet tag enumerations. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
ImageTagErrorCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 8191] | |||
The parameter counts how many mismatches occur between the image header tag, the expected tag according to the CXP standard and the received tag. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
StreamIdErrorCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 8191] | |||
The parameter counts how often the received stream-ID value in the stream packets mismatches the stream-ID value specified in the image header. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
CorrectedErrorCount | |
---|---|
Type | Dynamic Read parameter |
Default | |
Range | [0 : 8191] |
The parameter counts how many detected errors in the image header or the line markers have been corrected. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care. |
UncorrectedErrorCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 8191] | |||
The parameter counts how many detected errors in the image header or the line markers could not be corrected due to multiple bit errors in same byte. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
PacketBufferOverflowCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 8191] | |||
The parameter counts how often the packet buffer overflow occurs in the channel bonding in aggregated mode. This parameter is only relevant for ConnectionCount = X2 or X4. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
PacketBufferOverflowSource | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0x0 : 0xf] | |||
The parameter implements a bit mask to query in which of the potential 4 CXP channels the packet buffer overflow occurred. The parameter width depends on the parameter ConnectionCount. In X1 mode, the parameter width is 1 bit wide, in X2 mode, the parameter width is 2 bit wide and in X4 mode the parameter width is 4 bit wide. The order is: LSB = lowest CXP channel number, MSB = highest CXP channel number allocated by the operator.
|
CameraScanMode | |
---|---|
Type | Dynamic Read parameter |
Default | |
Range | {area,line} |
The received image header carries the information whether the stream is for the area scan or for the line scan applications. This parameter shows the last valid received stream image header information. This parameter is read out only for the Tap0 stream with the assumption, that Tap1 stream is exactly the same mode. This means this parameter applies either to area scan or to line scan for the complete camera and is thus identical for both taps and is not tap-specific. |
MarkerErrorCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 8191] | |||
The parameter counts how often the sequence of the CXP stream marker and the header or the line markers was incorrect. The parameter is 13 bit wide, where the bits [11:0] represent the actual counter value and the bit [12] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
UnexpectedStartupData | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | {false, true} | |||
The parameter detects the error situation in which the first data value after the operator reset was unexpected, i.e. no image header is received before. This situation can happen due to a buggy implementation of the camera, frame grabber firmware or wrong software control of the discovery procedure. Also, a hardware defect of the camera could theoretically cause such a situation.
|
FrameLostCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 33554431] | |||
The parameter counts the frames that were lost during acquisition and are not sent into the VisualApplets pipeline. Frames are lost when an error in the image header is detected or when a frame overlaps with another frame. The parameter is 25 bit wide where the bits [23:0] represent the actual counter value and the bit [24] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
FrameCorruptedCount | ||||
---|---|---|---|---|
Type | Dynamic Read parameter | |||
Default | ||||
Range | [0 : 33554431] | |||
The parameter counts the corrupted frames during acquisition. Corrupted frames are frames with error pixels which are sent to the VisualApplets pipeline. The parameter is 25 bit wide where the bits [23:0] represent the actual counter value and the bit [24] stands for the counter overflow. When the overflow bit is set, the counter value shall be treated as don't care.
|
The use of operator CxpCameraMultiTap is shown in the following examples:
-
'Functional Example for Multi Tap Camera Interface with Tap Geometry Sorting '
Examples - Demonstration of how to use the operator