Operator ImageBufferSpatial

Operator Library: Memory

Availability for Hardware Platforms
Please note that this operator is only available for target platforms of the microEnable 4 series (including PixelPlant).

This operator computes a spatial correction of its color components. Moreover, a region-of-interest (ROI) feature is included. The total number of bits (bit width x parallelism) must not exceed the memory limitations of the respective frame grabber.

This operator buffers the image stream in the Frame Grabber RAM (DRAM). One VisualApplets resource of type RAM is required (see 'Allocation of Device Resources').

For information on the latency of the operator, see Table 42, 'Individual Latencies of the Operators in Library Memory'.

The operator's key feature is the correction of the spatial shift of tri-linear line scan color cameras. For each color component red, green, and blue a relative shift can be defined using the parameters DeltaRed, DeltaGreen, and DeltaBlue. A shift means the delay in lines between the input and the resulting output image. A shift of 0 leaves the input image untouched. If for example DeltaRed = 0, DeltaGreen = 1, and DeltaBlue = 2, the first line of the output image consists in the following components: Red component read from the first input image line, green component is read from the second input image line, and blue component read from the third input image line. In order to switch the readout direction from forward to backward, just change the parameters: DeltaRed = 2, DeltaGreen = 1, and DeltaBlue = 0. Delta shifts can be negative, 0 or positive.

The buffer transforms delta values to relative deltas internally. The transformation implements this formula:

where delta is DeltaRed, DeltaGreen or DeltaBlue. This transformation is performed internally. The delta parameters of the operator stay unchanged and show the specified values. The transformation to relative deltas causes one delta offset to become 0 and the other two to become either 0 or negative, e.g. the configuration [DeltaRed = 1, DeltaGreen = 2, DeltaBlue = 1] is equivalent to [DeltaRed = -1, DeltaGreen = 0, DeltaBlue = -1]. The configuration [DeltaRed = -3, DeltaGreen = -3, DeltaBlue = -3] and [DeltaRed = 1, DeltaGreen = 1, DeltaBlue = 1] are both equivalent to [DeltaRed = 0, DeltaGreen = 0, DeltaBlue = 0]. A configuration like [DeltaRed = 1, DeltaGreen = 1, DeltaBlue = 1] indicates to perform a spatial correction with the configuration [DeltaRed = 0, DeltaGreen = 0, DeltaBlue = 0] and cut off the first line. Since the operator supports only relative delta shifts, the cut off of the first line will not be performed by the operator. However it is relatively easy to achieve the cutting outside the operator by using VA operators like CoordinateY and RemoveLine.

For each read out line the operator provides a line ID marker that is synchronous to the output link O. The line ID is a global marker and can be used to detect when lines are lost due to an overflow in the buffer. When an overflow occurs the buffer will discard input lines until the overflow condition is lifted, i.e., the RAM has enough storage room for at least 1 RoI line. The difference between 2 consecutive lines minus 1 is the amount of lines lost due to an overflow in the buffer.

The operator will continuously correct spatial shifts - a typical requirement for many line scan applications. However when the acquisition starts the buffer needs at least a certain amount of lines to output a corrected line. When this threshold is not reached no lines are output. The buffer outputs only lines that were corrected. The start-up lines required for the 1st image line to be corrected are not output. The threshold value depends on the specified delta shifts, e.g. DeltaRed = 0, DeltaGreen = 1, DeltaBlue = -3 require 5 lines to perform a correction. Thus the threshold is 5. After the 5th line, the buffer starts to output lines. In other words, the buffer starts to output lines as soon as it can correct them.

In frame correction applications (VALT_IMAGE2D input) the spatial correction will be performed on each frame individually, i.e. for every frame the spatial correction begins anew.

The first line output by the buffer owns always the line ID 0. In 2D application mode the line ID of the 1st frame line will show a gap to the last line of the previous frame. The gap size equals the amount of lines required to perform correction for this 1st output line. Not correctable lines are suppressed by the buffer.

Using parameters XOffset and XLength the ROI size can be defined. If the XLength is not divisible by the link parallelism the operator will insert dummy pixels to fill up the last parallel word, e.g. the link parallelism is 2, XOffset is 0 and XLength is 7, the operator will output 4 parallel words each consisting of 2 pixels. The last word will contain a dummy pixel. The value of that dummy pixel is undefined. In VA simulation dummy pixels will be set to zero for better visibility. The sum of XOffset and XLength parameters must not exceed the maximal link image width. If the input image width is less than the sum of the x-offset and the x-length, the operator will still read the parameterized x-length. In this case, the operator will output undefined memory contend to the exceeding pixel.

To measure the fill level of the buffer the operator provides 2 parameters: FillLevel and Overflow. FillLevel shows the percentaged fill level of the RAM in 25% steps. The Overflow parameter is set to 1 when FillLevel is close to or is 100% and the next image to be stored in the buffer will exceed the RAM capacity. In case of an overflow, input data is discarded and the input image height is reduced. Thus, incomplete images are stored in memory. Users have to poll for the overflow parameter. As the duration of the overflow state can be very short it is possible that it is in between of a polling cycle of the operator.

Parameter InfiniteSource is used to specify if the operator is directly connected to a camera or is sequenced with other memory operators. Check 'Infinite Sources / Connecting Cameras' for more information.

Operator Restrictions

  • Empty frames are not supported.

    Images with varying line lengths are not supported.

Bandwidth Optimization

The theoretical bandwidth [bits/second] going through an operator that uses the Frame Grabber RAM (DRAM) is calculated in accord with the following formula:

However, the actual bandwidth is always less than the theoretical bandwidth due to the DRAM efficiency.

The maximum bandwidth going through the operator is reached if the product of Bit Width and Parallelism is equal to the internal RAM Port Width.

[Note] Platform-specific values

RAM Port Width and System Clock are platform-specific. See Appendix. Device Resources for detailed information on your individual platform.

I/O Properties

Property Value
Operator Type M
Input Link I, image data input
Output Links O, data input
LinkID, data input

Supported Link Format

Link Parameter Input Link I Output Link O Output Link LinkID
Bit Width [3, 63] unsigned, [6, 63] signed1 as I auto
Arithmetic {unsigned, signed} as I unsigned
Parallelism any2 as I as I
Kernel Columns 1 as I as I
Kernel Rows 1 as I as I
Img Protocol {VALT_IMAGE2D, VALT_LINE1D} as I as I
Color Format VAF_COLOR as I VAF_GRAY
Color Flavor FL_RGB as I FL_NONE
Max. Img Width any as I as I
Max. Img Height any as I as I

1 2

The product of the bit width and the parallelism must not exceed the native ram data width. Check Appendix. Device Resources for more information.


Type dynamic/static read/write parameter
Default 0
Range [0, Max.Img Width - XLength]

This parameter defines the x-coordinate of the upper left corner of the ROI.

Type dynamic/static read/write parameter
Default 1024
Range [1, Max.Img Width - XOffset]

This parameter defines the width of the ROI.

Type dynamic/static read/write parameter
Default 0
Range any

This parameter defines the shift of the red component. The delta can be a positive or negative integer value.

Type dynamic/static read/write parameter
Default 0
Range any

This parameter defines the shift of the green component. The delta can be a positive or negative integer value.

Type dynamic/static read/write parameter
Default 0
Range any

This parameter defines the shift of the blue component. The delta can be a positive or negative integer value.

Type dynamic read parameter
Default 0
Range [0%, 100%]

This parameter provides the fill level of DRAM in 25% steps.

Type dynamic read parameter
Default 0
Range [0, 1]

This parameter indicates a buffer overflow.

Type static parameter

This parameter activates support for infinite source operators like Camera operators. See 'Infinite Sources / Connecting Cameras' for more information.