Using External Data Value References with Vision

The IMAQ ImageToArray VI provides access to the pixels of a Vision image by copying the image pixels from the Vision image into a 2-D LabVIEW array. This data copy consumes CPU cycles and memory bandwidth, and it also increases the amount of memory that the application requires. For large image sizes, the impact to application performance and memory usage can be significant.

Instead of using the IMAQ ImageToArray VI, consider using the IMAQ ImageToEDVR VI to create an external data value reference to the pixels in the Vision image. Using an external data value reference avoids the data copy and reduces CPU overhead. Additionally, the IMAQ ImageToEDVR VI also gives you more flexibility in representing the pixel data. There are options for viewing pixel data as 1-D, 2-D, or 3-D arrays, and as different data types than the original Vision image data type.

What to Use

Use the following block diagram objects to directly manipulate Vision image pixels using an external data value reference.

IMAQ ImageToEDVR
Case Structure
In Place Element Structure
Delete Data Value Reference
Merge Errors

What to Do

The following block diagram is an example of how to use external data value references with the Vision Development Module. The block diagram uses the IMAQ ImageToEDVR VI to create an external data value reference to the desired pixels in a Vision image. The external data value reference then passes through an In Place Element structure which gives access to the referenced data in array form. The subVI in the In Place Element structure executes application-specific code. After the subVI executes, the Delete Data Value Reference function releases the reference to the pixel data in the Vision image. Further processing or display of the image is possible.

Customize the gray sections of the following block diagram to meet your application goals.

The following list describes important details about the previous diagram:

1. Configure the IMAQ ImageToEDVR VI. For more information, refer to the Configuring the IMAQ ImageToEDVR VI section.
2. Wire the external data value reference to an In Place Element structure configured with Data Value Read/Write nodes.
3. Include code customized to meet your application goals.
4. Delete the external data value reference. The Vision image tracks how many external data value references have been made to it. The underlying image memory cannot be fully disposed until all of the references have been released.
5. Ensure that the VI handles errors in the correct order by using a Merge Errors function. You must handle incoming errors from the IMAQ ImageToEDVR VI before errors from the In Place Element structure.
6. Synchronize additional image display or processing operations with the external data value reference. One convenient way to do this is by using the error cluster to control the flow of the application. For more information, refer to the Synchronizing with External Data Value References section.

Configuring the IMAQ ImageToEDVR VI

There are numerous ways to configure the IMAQ ImageToEDVR VI to get data in a format that is useful for your application. The dimensionality of the array, the data type of the array, the rectangular region of the image to reference, the X and Y step sizes for the source image, and whether to include border pixels around the desired region are configurable. However, not all combinations of settings are allowed. Refer to the IMAQ ImageToEDVR VI documentation for a general description of the controls and indicators.

The following rules describe the conditions that must be satisfied for a valid settings combination.

• The width specified by the Optional Rectangle input (the Right value minus the Left value) must be greater than 0. A reference to a zero-sized region is not useful and is explicitly not allowed.
• If the desired EDVR array is 1-D, the width of the Optional Rectangle input must be equal to the X Resolution of the source image. A 1-D array only has a single stride value, which specifies the stride from element to element in the array. A 2-D image can be represented as a 1-D array by concatenating the desired rows from the image in order from top to bottom. Because there is only a single stride value, it is not possible to skip over part of an image row. The entire image row must be used including the left border pixels, the image data, the right border pixels, and the line-alignment padding pixels.
• The height specified by the Optional Rectangle input (the Bottom value minus the Top value) must be greater than 0. A reference to a zero-sized region is not useful and is explicitly not allowed.
• The X Step Size must be greater than 0. A value of 0 would result in a column stride of 0 in the EDVR array, which is an invalid value.
• The width specified by the Optional Rectangle input must be a multiple of the X Step Size. A line of image data can be segmented into four parts: left border, image data, right border, and line-alignment padding. It is guaranteed that the first byte of a segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size of each line segment in the source image is a multiple of the X Step Size.
• If the Include Border Pixels input is enabled, the source image border size must be a multiple of the X Step Size. A given line of image data can be segmented into four parts: left border, image data, right border, and line-alignment padding. It is guaranteed that the first byte of a segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size of each line segment in the source image is a multiple of the X Step Size.
• If the desired EDVR array is 1-D, the source image border size must be a multiple of the X Step Size and the source image line padding size must be a multiple of the X Step Size. A line of image data can be segmented into four parts: left border, image data, right border, and line-alignment padding. It is guaranteed that the first byte of a given segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size of each line segment in the source image is a multiple of the X Step Size.
• The Y Step Size must be greater than 0. A value of 0 would result in a row stride of 0 in the EDVR array, which is an invalid value.
• The height specified by the Optional Rectangle input must be a multiple of the Y Step Size. A column of image data can be segmented into three parts: top border, image data, and bottom border. It is guaranteed that the first byte of a segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size of each column segment in the source image is a multiple of the Y Step Size.
• If the Include Border Pixels input is enabled, the source image border size must be a multiple of the Y Step Size. A column of image data can be segmented into three parts: top border, image data, and bottom border. It is guaranteed that the first byte of a segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size of each column segment in the source image is a multiple of the Y Step Size.
• If the desired EDVR array is 1-D, the Y Step Size must be equal to 1. A 1-D array only has a single stride value, which is used to specify the stride from element to element in the array. A 2-D image can be represented as a 1-D array by concatenating the desired rows from the image in order from top to bottom. Because there is only a single stride value, it is not possible to skip over an image row. All of the image rows in the region must be used.
• The width specified by the Optional Rectangle input multiplied by the source image pixel size in bytes must be a multiple of the EDVR data type size in bytes. A line of image data can be segmented into four parts: left border, image data, right border, and line-alignment padding. It is guaranteed that the first byte of a segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size in bytes of each line segment in the source image is a multiple of the EDVR data type size in bytes.
• If the Include Border Pixels input is enabled, the source image border size multiplied by the source image pixel size in bytes must be a multiple of the EDVR data type size in bytes. A line of image data can be segmented into four parts: left border, image data, right border, and line-alignment padding. It is guaranteed that the first byte of a segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size in bytes of each line segment in the source image is a multiple of the EDVR data type size in bytes.
• If the desired EDVR array is 1-D, the source image border size multiplied by the source image pixel size in bytes must be a multiple of the EDVR data type size in bytes and the source image line padding size multiplied by the source image pixel size in bytes must be a multiple of the EDVR data type size in bytes. A line of image data can be segmented into four parts: left border, image data, right border, and line-alignment padding. It is guaranteed that the first byte of a given segment from the source image is included in the first element of the corresponding segment in the EDVR array. To accomplish this, it is required that the size in bytes of each line segment in the source image is a multiple of the EDVR data type size in bytes.
• If the desired EDVR array is 3-D, the source image pixel size in bytes must be a multiple greater than one of the EDVR data type size in bytes. The 3rd dimension of the array is intended to allow you to access the components of aggregate image data types. For example, an RGB32 image consists of 4 U8 components: blue, green, red, and alpha. A 3-D array with a data type that is the same size as the image data type does not provide any additional usefulness over the 2-D array variant. Therefore, this is explicitly not allowed.
• If the EDVR array is 1-D or 2-D and the X Step Size input is greater than one, the source image pixel size in bytes must be equal to the EDVR data type size in bytes. A 1-D or 2-D array does not have enough stride value settings to be able to properly represent this configuration.

Synchronizing with External Data Value References

Image access synchronization is handled automatically when using VIs from the Vision Development Module library. For instance, the internal image locking will prevent two functions from writing to the same image at the same time. It will also prevent a function from reading an image while another function is in the process of writing to the image. This synchronization ensures that the image data is always coherent.

When a call to the IMAQ ImageToEDVR VI is executed, it is synchronized with other Vision Development Module calls so that it is guaranteed that the image content will not change while the external data value reference is being created. Once the call to the IMAQ ImageToEDVR VI executes, make sure that image data corruption does not occur with the resulting external data value reference. Because the external data value reference can be used outside of the context of the Vision Development Module library, it cannot be synchronized with the Vision image using internal Vision Development Module synchronization techniques. The image pixel data can be accessed and modified without the protection provided by the Vision Development Module library, which makes it possible to accidentally corrupt the image data.

To avoid corrupting the image, do not simultaneously access the Vision image and the external data value reference associated with the Vision image. Do not pass the source Vision image to Vision Development Module VIs or to the image display control while the external data value reference is being operated on inside of the In Place Element structure. One common method to control the order of operations and to ensure that Vision Development Module VIs are not executing while the In Place Element structure is executing, is by using the error cluster wire. The error cluster wire follows traditional data-flow semantics. By having a single error cluster wire you can control the order of execution. Refer to the previous block diagram for a simple example. Another method is to use the Flat Sequence or Stacked Sequence structure. Each frame is fully executed in order, and by placing operations in different frames, you can guarantee that the frames will not occur simultaneously.