NI-IMAQ Images and IMAQ Vision Images in C

You can use either NI-IMAQ or Vision acquisition functions to acquire images when programming in C. NI-IMAQ functions represent an image as a "2D array", which is actually a 1D array of pixel values in which each row is appended to the previous row. Vision functions use an Image* , which is a pointer to an Image data structure that you can use with Vision processing functions.

One reason for the 2D array image type is that C users who have their own image processing algorithms can easily handle image data in a generic array format. If these C users had to work with the Image* format, they would need to call additional functions to get the address of the data or convert it to a 2D array. These steps waste time in unnecessary calls.

You can create a Image* with the function imaqCreateImage(), which requires the image type and border size. You can create a buffer array by calling the standard C function malloc or the NI-IMAQ function imgCreateBuffer(). Both an Image* and an image buffer can be created dynamically by the acquisition functions if they are set to NULL.

Note: You can distinguish NI-IMAQ function calls from IMAQ Vision function calls by their prefixes. NI-IMAQ functions start with img, and IMAQ Vision functions start with imaq.

If you have questions about functions or their parameters, you can use the function panels in CVI for help. You can access a function panel from any C file by pressing <Ctrl-Shift-P> and typing the first few letters of a function name. Right-click on the controls to get more information.

You can also access IMAQ Vision 6.0 for Measurement Studio documentation from Start>>Programs>>National Instruments>>Vision>>Documentation.

There are two methods for displaying images. The first method uses imgPlot() to display images at full frame rates inside a LabWindows/CVI child panel called a canvas. This method requires the parent window handle, an array of image data, and offset values for the image in the parent window. All the IMAQ examples use imgPlot() to overlay image data on a canvas. However, displaying on a canvas is not necessary.

The second method uses imaqDisplayImage() to display images at full frame rates inside an external image window. An image window is a separate window whose appearance you can configure. Properties you can set include whether the window has scroll bars, is resizable, or has a title bar. This method requires an Image*.

Where to find examples:
C:\Program Files\National Instruments\MeasurementStudio\CVI\samples\IMAQ\Display
C:\Program Files\National Instruments\MeasurementStudio\CVI\samples\Vision\1.GettingStarted

The imgSnap() function takes an array. The imaqSnap() function takes an Image*. You can perform most kinds of acquisition with Vision acquisition functions. However, for more advanced acquisition settings, like assigning each buffer in a ring to a different channel, use NI-IMAQ functions.

There is a way to use NI-IMAQ functions with Image* data types, so Vision users can acquire directly into an Image* for processing.

You can access examples of the different kinds of acquisition from the following locations:

• NI-IMAQ: CVI\samples\IMAQ
• Vision: CVI\sample\Vision\2. Functions\Acquisition

For each kind of acquisition, you need to call the following:

//Initialize interface and session
imgInterfaceOpen (“img0”, &iid); //Notice this is an NI-IMAQ function. The iid is the interface.
imgSessionOpen (iid, &sid); //Also uses IMAQ. The sid is the session, which will be used in all future calls.

Once you call these functions, you can set up and perform any kind of acquisition. Both NI-IMAQ and Vision acquisitons are shown, but only one is necessary.

Snap

main ()
{
//declare variables
INTERFACE_ID iid;
SESSION_ID sid;
Int8* ImaqBuffer=NULL; //NI-IMAQ image
Image* myImage = NULL; //IMAQ Vision image
//Initialize interface and session
imgInterfaceOpen (“img0", &iid);
imgSessionOpen (iid, &sid);
imgSnap (Sid, (void **)&ImaqBuffer); //NI-IMAQ function
myImage = imaqSnap (sid, myImage, IMAQ_NO_RECT); //IMAQ Vision function
}

There is a low-level version of all the NI-IMAQ examples that uses a buffer list and some buffer commands. Below are the important functions for the low-level NI-IMAQ snap example.

Main()
{
//declare variables
INTERFACE_ID iid;
SESSION_ID sid;
Int8* ImaqBuffer=NULL; //NI-IMAQ image
Image* myImage = NULL; //IMAQ Vision image
//Initialize interface and session
imgInterfaceOpen (“img0”, &iid);
imgSessionOpen (iid, &sid);

imgGetAttribute (Sid, IMG_ATTR_ROI_WIDTH, &acqWinWidth);
imgGetAttribute (Sid, IMG_ATTR_ROI_HEIGHT, &acqWinHeight);
imgGetAttribute (Sid, IMG_ATTR_BYTESPERPIXEL, &bytesPerPixel);

imgCreateBufList(1, &Bid); //Creates a buffer list with one buffer
bufSize = acqWinWidth * acqWinHeight * bytesPerPixel;
imgCreateBuffer(Sid, FALSE, bufSize, &ImaqBuffer);
imgSetBufferElement(Bid, 0, IMG_BUFF_ADDRESS, (uInt32)ImaqBuffer);
imgSetBufferElement(Bid, 0, IMG_BUFF_SIZE, bufSize);
imgSetBufferElement(Bid, 0, IMG_BUFF_COMMAND, IMG_CMD_STOP);
}

Other kinds of acquisition follow the same structure. Examples for each kind of acquisition ship with the software. Some functionality can be accomplished only through NI-IMAQ functions, such as assigning different buffers to different channels to achieve scanning of channels for the 1408/1409. You can use the technique in the above example to assign the pixel address to an IMAQ Vision buffer, if necessary.

NI-IMAQ provides C users an easy way to save images to disk. Pass the buffer address and the path to which you want to save to the imgSessionSaveBufferEx() function to save images to disk. You can save an image with imgSessionSaveBufferEx()as a BMP, TIFF, or PNG. The Vision functions for saving images is imaqWriteFile(). This function allows you to save an image as an AIPD, BMP, JPEG, TIFF, or PNG. Using the Vision functions, you can save overlay, pattern matching, calibration, and other useful information in PNG format.

See Also:
File IO - Reading and Writing Examples