Memory Management with IMAQ
You can manage memory effectively in IMAQ in the following ways:
- Use IMAQ Create to create a new image.
- Give every image you create a different image name.
- Check the image type you assign to an image because some VIs work only with certain image types.
- Avoid branching the wiring for an image to multiple IMAQ processing VIs. If multiple processing VIs change an image at the same time, they might overwrite each other's results. For example, if one VI processes while another VI is examines an image, such as a threshold and histogram, the threshold might execute first and the histogram will have pixel values of 0 and 1 only. Use the Image Destination if you don't want to modify the original image.
This document includes a general explanation of image memory allocation using IMAQ VIs.
Creates a memory location for the image. The memory location does not have a size yet, it is empty. Use this VI every time that you create an image. The VI returns the memory location through the New Image indicator. You can select the type of image you want, such as RGB, 8-bit, or 16-bit. Some VIs work only with certain image types, so always check that the image type you allocate works with the VIs you call. To check the image type, right-click the VI and select Help. The top of the VI description lists the image types that the VI supports. Whenever you create a new image, ensure that it has a unique name. Using the same name for multiple images can cause strange behavior because the images can get mixed up.
Allocates the memory for the image. Enter the image location into the Image control. The VI allocates memory at the image location and returns the result through Image Out. Use this VI to pre-allocate image size or to resize an image.
IMAQ Snap and Similar VIs
IMAQ Snap and similar IMAQ VIs acquire an image and fill it with data from a camera. If you do not allocate memory for the image, the VI allocates the memory automatically and fills that memory with data from the camera. You cannot create a constant for the image. Use IMAQ Create.
IMAQ ReadFile and Similar VIs
IMAQ ReadFile and other File VIs dynamically allocate the appropriate buffer size for the image you want to read. The image file can include a color image. However, if the image you create is 8-bit monochrome, IMAQ ReadFile returns an 8-bit monochrome version of the color image from the file because 8 bits per pixel is not enough for a color pixel. Select the RGB image type when you create an image to use with color files if you want the image to have color.
IMAQ Copy Image
Copies everything about the source image to the destination image. The source and destination images must be the same image type. The VI copies the border, calibration information, overlays, and image data to the destination image. The VI allows you to keep a copy of the original while processing the copy further. Providing a destination image for VIs that would change the original also preserves the original, but using IMAQ Copy Image is another way to accomplish this.
IMAQ Cast Image
Converts images of one type to another. This is useful if you have a 16-bit image and want to perform AutoBThreshold, which only accepts 8-bit images. When converting from RGB to 8 bit, the VI pulls out the intensity plane so the image looks like the grayscale version of the original color image. However, when converting from 16 bit to 8 bit, the VI takes the highest 8 bits, which can cause significant loss of image integrity. In that case, you might consider a more effective way of converting your image, as this exampledemonstrates.
IMAQ Rotate and Similar VIs
IMAQ Rotate and similar IMAQ VIs acquire an image that you specify in the Image Src control and use the Image Dst memory location to create the resulting transformed image. If you do not specify a memory location in Image Dst, the VI performs the transform on the original image location, changing the contents of the original image. Any VI that includes Image Scr and Image Dst parameters changes the original image. If you want to keep a copy of the original image before the VI changes it, wire a different image to the destination.
Retrieves the actual memory location of an image. The VI passes the memory location to C code through a Call Library Function or CIN that uses the pointer to access the image data. Passing a pointer value is faster and uses less memory than converting the image to a 2D array and passing the 2D array. If you pass the pointer value, it points to the upper left pixel and the data will be contiguous. If the image has a border, this will be part of the contiguous data, so you must skip over it or make sure the border is set to 0 when creating the image.
Deletes the memory location of an image. After using this VI, the image no longer exists. If you do not use IMAQ Dispose after you finish working with an image, you allocate more memory every time you run IMAQ Create and you will never delete the memory. This is sometimes called a memory leak.
In general, use IMAQ Create every time you create an image. After you create a memory location of an image, either allocate a specific amount of memory to the image using the IMAQ SetImageSize VI, or use IMAQ Snap or a similar VI that grabs an image from the camera. When you finish working with the image, use IMAQ Dispose to release the memory that the image used.
Always call IMAQ Create to get an image. You can allocate memory for the image in the following ways:
- IMAQ SetImageSize: Manually modifies the image to a size you specify, but the image will be blank.
- IMAQ Snap: Automatically allocates the appropriate size for the acquisition and returns the image taken from the camera.
- IMAQ ReadFile: Automatically allocates the appropriate size for the image.
- IMAQ Copy: Copies all the information from one image to another including image data, size, border, overlays, and calibration information.
- IMAQ Cast: Converts an image of one type to another. You still must call IMAQ Create for each of the different images.
- IMAQ Rotate: Any processing VI that changes the contents of the original has an image destination. By wiring an empty image into the destination, the empty image includes the result of the processing VI.
The location of the previous VIs can be found in these locations:
Function Palette/Image Acquisition/IMAQ Snap.vi
Function Palette/Vision Utilities/Image Management/IMAQ Create.vi
Function Palette/Vision Utilities/Image Management/IMAQ SetImageSize.vi
Function Palette/Vision Utilities/Files/IMAQ ReadFile.vi
Function Palette/Vision Utilities/Image Management/IMAQ Copy.vi
Function Palette/Vision Utilities/Image Management/IMAQ Cast Image.vi
Function Palette/Vision Utilities/Image Manipulation/IMAQ Rotate.vi
Function Palette/Vision Utilities/Image Management/External Library Support/IMAQ GetImagePixelPtr.vi
Function Palette/Vision Utilities/Image Management/IMAQ Dispose.vi