Operator CoefficientBuffer

Operator Library: Memory

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 a 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 43, 'Individual Latencies of the Operators in Library Memory'.

[Note] CoefficientBuffer Is Not Available for imaFlex CXP-12 Quad and imaFlex CXP-12 Penta Platforms

CoefficientBuffer is not supported on imaFlex CXP-12 Quad and imaFlex CXP-12 Penta platforms. The example 'Functional Example for Loading Test Images Using ImageInjector ' shows how you can substitute the functionality of the CoefficientBuffer operator as test image source on imaFlex CXP-12 Quad or imaFlex CXP-12 Penta using the ImageInjector operator. Note that for the ImageInjector operator you need either an Expert license, a Debugging Module license, or the VisualApplets 4 license.

The example '2D Shading Correction / Flat Field Correction Using Operator RamLUT' shows how you can a RamLUT instead of the CoefficientBuffer for 2D shading correction.

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.

The output ports of the operator work synchronously. The transfer of the first image pixel starts exactly at the same moment on all output ports. If all images have been transferred to the receiving operator, CoefficientBuffer starts to synchronously output the images again.

[Note] Behavior during simulation

The images on the operator's links are output simultaneously. In one simulation step, the operator outputs maximally one image on each link. If during a simulation step all of the stored images (one per link) have been forwarded to the receiving operator, i.e., if there occurred no blocking, the same output (one image per link) will be forwarded in the following simulation step.

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., coefficient image 0 will be provided on 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 stored in CoefficientBuffer in pixels.

BufferHeight specifies the height of all coefficient images managed by CoefficientBuffer in pixels. 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.

Parameter LoadCoefficients 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.

Parameter UpdateROI is used to update the current RoI dynamically while the image acquisition is running or when no images are grabbed. The new RoI 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.

Parameter 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.

Parameter 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.

Parameter YOffset 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.

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

Parameter CoefficientFile N specifies the file name of the coefficient image for 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 exceeds 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

Internally, the CoefficientBuffer operator generates one cumulative pixel from all coefficient image pixels. This is the so-called super-pixel.

  • If the RAM data width is less than the super-pixel bit width, the super-pixel is distributed over multiple RAM cells.
  • If the super pixel is less than the RAM data width, only one super-pixel is stored in each RAM cell, even if multiple super-pixels would fit into a RAM cell.

Therefore, a RAM cell will only be occupied by one super-pixel or is part of a super-pixel.

The operator internally stores a pixel of the output bit width in a RAM-data-width wide block, e.g., if the output bit width is set to 8bit on a marathon VCL platform (RAM data width is 256bit), only 8 bit of each RAM cell are used. The rest is wasted.

Increasing the bandwidth by simply increasing the parallelism will NOT help in this case.

You can look up the RAM data width of the frame grabber you are using in the Platform Resources section of this documentation:

Appendix. Device Resources

Find below some ideas to increase the bandwidth/ RAM-efficiency:

Tip 1:

To increase the bandwidth, you may define the bitwidth of a pixel to be bigger, and later on use a CastParallel operator to correct this.

Example: You need an image in Gray 8bit but with the bandwidth of parallelism 8. For that you can define the output bit width to be 64 (parallelism 1) and later on use operator CastParallel to shift the link back to 8 bit and parallelism 8.

This way, your image will also consume less RAM as more than 1 pixel are stored in 1 RAM cell. If used directly - without operator CastParallel - the memory needed to store the image will be 8 times bigger.

Tip 2:

If the bit width of the combined link would exceed 64 bit, you can split your image to multiple images and use more than one link of operator CoefficientBuffer. Later on you can combine all links since all outputs are O-synchronous.

Example: You want to send an RGB24 image in parallelism 4. The accumulated pixel would be 4*24 = 96Bit - which is too big. So the idea to solve this would be to split the image into 4 sub images, each having ¼ of the pixel.

Internally, the operator will accumulate the pixel of each input to one super-pixel of 96bit.

This way, the efficiency of the ram is also increased. If we take a 1024x1024 image on an Ironman mE5VQ8-CXPD platform (128 Bit wide RAM data interface), the image stored in simple 1 link CoefficientBuffer is

1024 * 1024 * 128 / 8 Byte = 16MB.

If the 4-link setup is applied, the size is

1024 * 1024 * (128 / 4) / 8 = 4MB

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 any2
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

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

RamDataWidth
Type static write parameter
Default 0
Range Integer number

This parameter provides the number of data bits that can be used at the RAM interface.

RamAddressWidth
Type static write parameter
Default 0
Range Integer number

This parameter provides the number of RAM address bits available.

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.

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:

  Prev     Level Up     Next  
Content Top Home