Operator CoefficientBuffer

The operator allows the upload of image files from the host PC to the frame grabber which will be continuously output and used as image source. An image file is used here as an universal data container. Therefore, uploaded images can contain any data such as coefficients. All coefficient images must have the same pixel width and height but can be in completely different formats. For example link 0 coefficient image can be in GRAY 8 bit format. Link 1 could provide an image in RGB16 format. And link 2 could be a binary image. All coefficient images are stored in the Frame Grabber RAM (DRAM). One VisualApplets resource of type RAM is required. Check 'Allocation of Device Resources' for more information. For information on the latency of the operator, see Table 28, 'Individual Latencies of the Operators in Library Memory'.

The number of links corresponds to the number of coefficient images stored in CoefficientBuffer. The coefficient images can only be uploaded into the FPGA buffer via software while no image acquisition is running. This is done by writing to parameter LoadCoefficients.

CoefficientBuffer also supports a region of interests (RoI) management. The RoI is defined by the 4 parameters XOffset, XLength, YOffset and YLength. XOffset and YOffset define the upper left corner of the RoI, i.e. the start coordinate in pixels. The dimensions of the RoI must not exceed the dimensions of the stored coefficient images defined by the parameters BufferWidth and BufferHeight. The RoI can be updated dynamically during acquisition or when no acquisition is running by setting all 4 RoI coordinate parameters to new values and writing to the parameter UpdateROI. Note that XLength must also fulfill the granularity of the link parallelism, i.e. XLength modulo LinkParallelism = 0.

For each output link a coefficient image file is stored in the buffer, i.e. the coefficient image 0 will be provided on the link 0. The coefficient images must be loaded into CoefficientBuffer before the acquisition starts. The coefficient images must be stored in the files specified by the parameters CoefficientFile N, N stands for the link number respectively for the coefficient image number. The coefficient files must be encoded in TIF format.

BufferWidth specifies the width of all coefficient images in pixels stored in CoefficientBuffer.

BufferHeight specifies the height of all coefficient images in pixels managed by CoefficientBuffer. BufferWidth and BufferHeight determine the output maximal image dimensions of all output links.

For grayscale links, grayscale image files have to be used. For color links, RGB image files have to be used.

If the bit width of a link is higher than the bit width of the image file, the operator will use multiple image file pixel to generate the output pixels. For example a link of 22 bit will require 3 pixel in an 8 bit image file. Thus, the image width of the image file has to be 3 times higher than parameter BufferWidth.

If the bit width of a link is less than the bit width of the image file, the operator will use the lower bits of the input image file only. For example, an 8 bit image file and a 3 bit link will use bits 0, 1 and 2 of the file.

16 bit TIF files should only be used with care.

LoadCoefficients parameter is used to start loading of coefficient images into the buffer before the image acquisition starts. The loading is triggered by a write cycle or value 1 to this parameter. Writing value 0 has no effect.

UpdateROI parameter is used to update the current RoI dynamically when image acquisition is running or when no images are grabbed. The new RoI to be updated must be specified by the 4 RoI coordinate parameters before writing to this parameter. The written value does not affect the updating process, only the write cycle triggers it, i.e. the written value can be either 0 or 1.

XOffset specifies the offset in horizontal direction from the left image border to the 1st column of the RoI. The specified value is measured in pixels and must not exceed BufferWidth-1 value.

XLength specifies the length of the RoI in horizontal direction in pixels. The specified value must not exceed BufferWidth and must be divisible by the output link parallelism. Also the following constraint must be met: XOffset + XLength <= BufferWidth.

YOffset parameter specifies the offset in vertical direction from the top image border to the 1st line of the RoI. YOffset must be specified in pixels and must not exceed BufferHeight-1.

YLength parameter specifies the length of the RoI in vertical direction in pixels. The length must not exceed BufferHeight. Also the following constraint must be met: YOffset + YLength <= BufferHeight.

CoefficientFile N parameter specifies the file name of the coefficient image for the link N stored in TIF format.

[Note] Note
  1. The parallelism of link 0 determines the parallelism of all other links.

  2. Setting of the parallelism for the link 0 corrects XLength value to be divisible by the new parallelism. This might be handled differently in future VA versions. This means that when using the up/down buttons in the spinbox of the parallelism attribute of the link XLength might be modified. Therefore a check on XLength setting is recommended after all links are connected and specified.

  3. Setting the parameter BufferWidth and BufferHeight corrects the RoI coordinates in case any of them exceed the new image dimensions. The coordinates will be corrected to the closest possible valid values.

  4. CoefficientBuffer supports 2D, 1D and 0D images. In case of 1D and 0D images the operator will provide the coefficient images - that are stored as 2D images - continuously without generating end of frame respectively end of line markers.

  5. The operator is using 1 DDRRAM bank. Thus, the storage space for coefficient images is limited to the capacity of one RAM bank (e.g., 128MByte on mE4 boards, 256MByte on mE5 boards) per 1 operator. Furthermore, due to the internal formatting of the DDRRAM, the actual storage space might be a bit less than the physical storage space. The used storage space is related to the link formats respectively to the pixel width of each link. In an optimal case the sum of all link pixel widths is divisible by the capacity of one RAM bank (i.e., by 128 on me4, or by 256 on mE5). In this case all coefficient images can be stored together in one memory bank. In any other case the storage will be used sub-optimally. Check Appendix. Device Resources for more information on hardware platforms.

Recommended Setting Order for using this Operator

  1. Connect all links of CoefficientBuffer.

  2. Specify the link formats for all links.

  3. Set BufferWidth and BufferHeight parameters.

  4. Set RoI coordinates.

  5. Set the coefficient file names.

Using the Operator with Maximum Performance

The CoefficientBuffer operator generates internally one cumulative pixel from all coefficient image pixels. This is the so calles super-pixel. If the RAM data width is less than the super-pixel bit width the super-pixel is distributed over multiple RAM cells. In constrast, if the super pixel is less than the RAM data width, only one super-pixel is stored in each RAM cell. If more than one super-pixel would fit into a RAM cell, only one super-pixel is stored in a RAM cell. Therefore, a RAM cell will only be occupied with one super-pixel or is part of a super-pixel.

Example for microEnable IV frame grabbers with a RAM cell width of 64 bit.

Suppose that the Coefficientbuffer is used with a single coeffcient image file only, the pixel bit width is 8 bit per pixel and the parallelism is 1. In this case, the buffer will dramatically loose performance. That's because only 1/8th of the bandwidth is used. Moreover, the buffer reads its its values with doubled design clock frequency, i.e. only 1/16th of the full bandwidth is used.

To use the buffer with maximum performance, the pixel data has to be reinterpreted. In out example, the buffer output link has to be parameterized to 64 bit per pixel and parallelism two has to be used. This will cause the buffer to read 128 bit per design clock. Use a CastParallel operator to reinterpret the 64 bit data values to a bit width of eight and a parallelism of 16. Moreover, the parameter BufferWidth has to be set to 1/8th of the image width of the coefficient image.

In conclusion, the maximum bandwidth can only be obtained if the output bit width is high, e.g. 64 bit. Using a high output parallelism will not increase the bandwidth.

Using the Operator as Simulation Source

The operator can be used as a simulation source. In this case, the operator will try to load and use the image files specified by the Coefficient File N parameters. Note that this will only work properly if the image files exactly match with the link format. If you have a link format of e.g. 64 Bit, the image width of your image file has to be 8 times the maximum image width of the link as the image will have 8 bit per pixel. The height has to exactly match with the maximum image height specified at the link, too.

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 x 2 (true for read-only parameters).

[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
Output Link O[n], data output

Supported Link Format

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

1

The range of the output 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

BufferWidth
Type static parameter
Default 1024
Range [1, 65535]

This parameter defines coefficient images width in pixels. Moreover, this parameter defines the maximum image width of all output links. The range of this parameter depends on the used frame grabber and its RAM.

BufferHeight
Type static parameter
Default 1024
Range [1, 65535]

This parameter defines the coefficient images height in pixels. Moreover, this parameter defines the maximum image height of all output links. The range of this parameter depends on the used frame grabber and its RAM.

LoadCoefficients
Type dynamic write parameter
Default 0
Range {0, 1}

This parameter is used to start loading of coefficient images into the buffer before the image acquisition starts. The loading is triggered by a write cycle of value one to this parameter. Writing value 0 does not cause the loading of the coefficient files.

UpdateROI
Type dynamic write parameter
Default 1
Range {1}

The parameter is used to update the ROI settings in hardware. The values defined by the 4 ROI coordinate parameters are used. An update can be done at any time, even during a running acquisition.

XOffset
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. Changing the value does not directly change the ROI settings. You have to write to parameter UpdateROI to apply new settings.

The step size is the parallelism.

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

This parameter defines the width of the ROI. Changing the value does not directly change the ROI settings. You have to write to parameter UpdateROI to apply new settings.

The step size is the parallelism.

YOffset
Type dynamic/static read/write parameter
Default 0
Range [0, BufferHeight - YLength]

This parameter defines the y-coordinate of the upper left corner of the ROI. Changing the value does not directly change the ROI settings. You have to write to parameter UpdateROI to apply new settings.

YLength
Type dynamic/static read/write parameter
Default 1024
Range [1, BufferHeight - YOffset]

This parameter defines the height of the ROI. Changing the value does not directly change the ROI settings. You have to write to parameter UpdateROI to apply new settings.

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

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

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.

Coefficient File N
Type dynamic read/write parameter
Default coefficients_N.tif
Range any filename of a tif file with optional path

This parameter defines the file name of the coefficient image for the link N.

Examples of Use

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