Operator ImageBufferMultiRoI

Operator Library: Memory

This operator provides support for multiple regions of interest (ROI) for each buffered image. All ROIs are read out sequentially. Each ROI is a new and independent output image: ROI 0, ROI 1, ROI 2 and so on until ROI N-1. N is the number of ROIs specified by the parameter NumRoI. Supported are all possible rectangular regions as long as the frame dimensions are not exceeded, i.e., a single pixel, a single line, a single column, a rectangular region, or the complete frame can be defined as a ROI. Different ROIs can be of different size. Each ROI can be defined individually. ROIs can overlap each other. However, all ROIs must meet the restriction of the maximal image size defined by the input and output links, i.e. ROI widths must not exceed the maximal image width and ROI heights must not exceed the maximal image height.

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

The operator buffers the image stream in the frame grabber on board RAM. One VisualApplets resource of type RAM is required (see 'Allocation of Device Resources').

ImageBufferMultiRoI operates on images of fixed size defined by the input link maximal image width and height parameters. This implies input frame dimension control performed by the operator.

Images that are smaller than the maximal image dimension will be buffered without modifications. However the reading of ROIs could cause the read of undefined pixel values i.e. pixel values outside of the input image dimension. The missing frame pixels contain random data and should be treated in further processing as undefined.

In case of an overflow, i.e. the buffer cannot store any more images due to being full, all incoming images will be dropped until there is enough free space in the buffer to store at least one frame. An overflow can occur because the reading of the ROIs is to slow in comparison to the writing. This can either be because to many ROIs are defined or because successive operators block the output. In normal situations of balanced designs an overflow will never occur.

The operator provides ROI images on its output as soon as the correspondent frame is completely buffered. The type of reading out is defined by the parameter Mode.

The parameter MaxNumRoI specifies the maximal number of ROIs. The actual number of ROIs used can be less and is defined using parameter NumRoI.

The parameter NumRoI specifies the number of ROIs the operator will provide at the output for each buffered image. This number mus not exceed MaxNumRoI when set to the dynamic type.

The parameter Mode specifies the operator behavior for processing images. FreeRun defines the buffer to provide ROIs at its output as soon as possible, i.e. as soon as the correspondent frame is completely buffered. This mode is also called free running mode. The operator is controlled only by the pipeline flow control mechanisms. WaitAfterImage mode forces the operator to hold on after all ROIs of a frame were provided on its output. To restart reading of the ROIs of the next frame, the parameter Unlock has to be written. WaitAfterRoI is similar to WaitAfterImage except that the operator stops after each ROI of each frame. To restart further processing a write cycle to the parameter Unlock is required.

The parameter Unlock is used for the modes WaitAfterImage and WaitAfterRoI to unlock the operator and to start further read out operations. In mode FreeRun this parameter has no effect.

XOffset, XLength, YOffset and YLength specify a set of ROIs. These parameters are field parameters. The parameter type of these parameters can be set to dynamic or static, this means adjustable or not adjustable during runtime. The parameter type of all ROI parameters is automatically adapted accordingly, when the parameter type of one ROI parameter is set. The size of the field is defined by parameter MaxNumRoI. The operator will read NumRoI ROIs in sequential order. Learn on how to configure field parameters in 'Parameter Editing'.

All ROIs can be updated dynamically. However, the updating can be performed for the modes FreeRun, WaitAfterImage and WaitAfterRoI only if no image acquisition is started. Additionally in the modes WaitAfterImage and WaitAfterRoI, ROIs can be updated if the corresponded frame / all ROIs of the frame were transmitted and the operator is waiting for a write cycle to the Unlock parameter.

Updating ROIs during image acquisition can lead to temporarily non-rectangular ROIs and should be avoided.

If the operator is used with image protocol VALT_LINE1D, the Y coordinate parameters are disabled. In 1D operation, the operator will read one ROI as one line. The output of the operator will then be an infinite 1D image stream, where each line is represented by one ROI e.g. line 0 = ROI 0, line 1 = ROI 1, line N = ROI N, line N+1 = ROI 0, ...

To measure the fill level of the buffer the operator provides 2 registers: FillLevel and Overflow. FillLevel shows the percental fill level of the RAM. The Overflow parameter is set to 1 when FillLevel is close or is 100% and the next image to be stored in the buffer will exceed the RAM capacity.

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.

[Note] ImageBufferMultiRoI Is Not Available for imaFlex CXP-12 Quad Platforms

ImageBufferMultiRoI is not supported on imaFlex CXP-12 platforms, but you can use an equivalent user library element for imaFlex CXP-12 Quad platforms instead. See 'Delivered User Libraries' for instructions how to work with user library elements.

[Tip] Example: Optimization of Memory Usage

A cumstomer feeds an image with the dimensions 10000 x 7096 pixels (link property on input port). The parallelism is set to 4. The pixel width is set to 8bpp.

The platform used in this example is mE4, i.e. the platform provides 128 Mbyte RAM banks. To use all 128 MB, the operator should be fed with 64 bit. But with parallelism 4, only 32 bits ( 4 x 8 bits) are fed, i.e., the user can only use 64 MB of the RAM. To save an image with the dimensions of 10000 x 7096 pixels, ca. 70.960.000 Bytes (ca. 70 MB) are required, which is more than the available 64 MB. This is detected by VisualApplets, and the link is highlighted in red.

Solution: Parup (to 8) in front of the operator ImageBufferMultiRoi.

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 Link O, data input

Supported Link Format

Link Parameter Input Link I Output Link O
Bit Width [1, 64]12 as I
Arithmetic {unsigned, signed} as I
Parallelism any3 as I
Kernel Columns 1 as I
Kernel Rows 1 as I
Img Protocol {VALT_IMAGE2D, VALT_LINE1D} as I
Color Format any as I
Color Flavor any as I
Max. Img Width any as I
Max. Img Height any as I

1

The range of the input bit width is [1, 64] for unsigned inputs. For signed inputs, the range is [2, 64]. For unsigned color inputs, the range is [3, 63] and for signed color, the range is [6, 63].

2 3

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

Parameters

MaxNumRoI
Type static parameter
Default 1
Range [1, 65535]

This parameter defines the maximum number of ROIs which the operator is capable to store.

NumRoI
Type dynamic/static read/write parameter
Default 1
Range [1, MaxNumRoI]

This parameter defines the number of ROIs actually used. The operator will read NumRoI ROIs from each input image and provide them on its output. If the parameter is set to static the range is [1, 65536] and MaxNumRoI is disabled.

Mode
Type static parameter
Default FreeRun
Range {FreeRun, WaitAfterImage, WaitAfterRoI}

This parameter defines the operation mode of the read out algorithm. In FreeRun mode the operator provides ROI images as soon as the correspondent frame is completely buffered. In WaitAfterImage mode the operator will provide all ROIs within a single frame, then stop and wait for a software access to write on Unlock parameter to enable reading out of the next frame ROIs. In WaitAfterRoI mode the operator will stop after each ROI of each frame. To restart the reading out operation, the software has to write to the Unlock parameter.

Unlock
Type dynamic write parameter
Default 1
Range {1}

This parameter implements the handshake for the mode WaitAfterImage and WaitAfterRoI. Writing to this parameter value 1 will cause the operator to continue reading out of the next ROI / all ROIs of the next Frame.

This parameter can only be used of parameter Mode is set to WaitAfterImage or WaitAfterRoI.

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

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

The step size is the parallelism.

Learn on how to configure field parameters in 'Parameter Editing'.

XLength
Type dynamic/static read/write parameter
Default 1024
Range [2*parallelism, Max.Img Width - XOffset]

This field parameter defines the width of the ROI.

The step size is the parallelism.

Learn on how to configure field parameters in 'Parameter Editing'.

YOffset
Type dynamic/static read/write parameter
Default 0
Range [0, Max.Img Height - YLength]

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

Learn on how to configure field parameters in 'Parameter Editing'.

YLength
Type dynamic/static read/write parameter
Default 1024
Range [1, Max.Img Height - YOffset]

This field parameter defines the height of the ROI.

Learn on how to configure field parameters in 'Parameter Editing'.

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

This parameter provides the fill level of DRAM.

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

This parameter indicates a buffer overflow.

InfiniteSource
Type static parameter
Default ENABLED
Range {ENABLED, DISABLED}

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

Examples of Use

The use of operator ImageBufferMultiRoI is shown in the following examples: