VisualApplets
Operator Reference

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 43, '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.

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

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.

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

Supported Link Format

Link Parameter	Input Link I	Output Link O
Bit Width	[1, 64]	as I
Arithmetic	{unsigned, signed}	as I
Parallelism	any	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

	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].
	The product of the bit width and the parallelism must not exceed the native ram data width (RamDataWidth). Check Appendix. Device Resources for more information.
	Maximum image dimensions for I: I.Img.Protocol = VALT_IMAGE2D: 2^RamAddressWidth >= (I.Max.Img.Width * I.Max.Img.Height) / I.Parallelism I.Img.Protocol = VALT_LINE1D: 2^RamAddressWidth >= I.Max.Img.Width / I.Parallelism