National Instruments Network Card Image Acquisition Software User Manual

IMAQ  
NI-IMAQ User Manual  
Image Acquisition Software  
NI-IMAQ User Manual  
June 1998 Edition  
Part Number 371443A-01  
 
 
Important Information  
Warranty  
The media on which you receive National Instruments software are warranted not to fail to execute programming  
instructions, due to defects in materials and workmanship, for a period of 90 days from date of shipment, as evidenced  
by receipts or other documentation. National Instruments will, at its option, repair or replace software media that do not  
execute programming instructions if National Instruments receives notice of such defects during the warranty period.  
National Instruments does not warrant that the operation of the software shall be uninterrupted or error free.  
A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside  
of the package before any equipment will be accepted for warranty work. National Instruments will pay the shipping costs  
of returning to the owner parts which are covered by warranty.  
National Instruments believes that the information in this manual is accurate. The document has been carefully reviewed  
for technical accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to  
make changes to subsequent editions of this document without prior notice to holders of this edition. The reader should  
consult National Instruments if errors are suspected. In no event shall National Instruments be liable for any damages  
arising out of or related to this document or the information contained in it.  
EXCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS  
ANY WARRANTY OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. CUSTOMERS RIGHT TO RECOVER DAMAGES CAUSED  
BY FAULT OR NEGLIGENCE ON THE PART OF NATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE  
CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR DAMAGES RESULTING FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS,  
OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSSIBILITY THEREOF. This limitation of the liability of  
National Instruments will apply regardless of the form of action, whether in contract or tort, including negligence.  
Any action against National Instruments must be brought within one year after the cause of action accrues. National  
Instruments shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty  
provided herein does not cover damages, defects, malfunctions, or service failures caused by owner’s failure to follow  
the National Instruments installation, operation, or maintenance instructions; owner’s modification of the product;  
owner’s abuse, misuse, or negligent acts; and power failure or surges, fire, flood, accident, actions of third parties,  
or other events outside reasonable control.  
Copyright  
Under the copyright laws, this publication may not be reproduced or transmitted in any form, electronic or mechanical,  
including photocopying, recording, storing in an information retrieval system, or translating, in whole or in part, without  
the prior written consent of National Instruments Corporation.  
Trademarks  
BridgeVIEW, ComponentWorks, CVI, IMAQ, LabVIEW, NI-IMAQ, RTSI, and StillColorare trademarks  
of National Instruments Corporation.  
Product and company names listed are trademarks or trade names of their respective companies.  
WARNING REGARDING MEDICAL AND CLINICAL USE OF NATIONAL INSTRUMENTS PRODUCTS  
National Instruments products are not designed with components and testing intended to ensure a level of reliability  
suitable for use in treatment and diagnosis of humans. Applications of National Instruments products involving medical  
or clinical treatment can create a potential for accidental injury caused by product failure, or by errors on the part of the  
user or application designer. Any use or application of National Instruments products for or involving medical or clinical  
treatment must be performed by properly trained and qualified medical personnel, and all traditional medical safeguards,  
equipment, and procedures that are appropriate in the particular situation to prevent serious injury or death should always  
continue to be used when National Instruments products are being used. National Instruments products are NOT intended  
to be a substitute for any form of established process, procedure, or equipment used to monitor or safeguard human health  
and safety in medical or clinical treatment.  
 
How to Use the NI-IMAQ Manual Set..........................................................................ix  
Conventions Used in This Manual.................................................................................x  
National Instruments Documentation ............................................................................xi  
Chapter 1  
About the NI-IMAQ Software.......................................................................................1-1  
Fundamentals of Building Applications with NI-IMAQ...............................................1-2  
The NI-IMAQ Libraries ..................................................................................1-2  
Chapter 2  
Low-Level Functions.....................................................................................................2-5  
Acquisition Functions......................................................................................2-5  
Attribute Functions..........................................................................................2-6  
Buffer Management Functions........................................................................2-6  
Interface Functions..........................................................................................2-7  
Utility Functions..............................................................................................2-7  
© National Instruments Corporation  
v
NI-IMAQ User Manual  
 
Contents  
Chapter 3  
Advanced Programming Examples............................................................................... 3-14  
Performing a Grab Using Low-Level Functions............................................. 3-15  
Performing a Sequence Acquisition Using Low-Level Functions.................. 3-15  
Performing a Ring Acquisition Using Low-Level Functions ......................... 3-16  
Appendix A  
StillColor  
Customer Communication  
Glossary  
Index  
NI-IMAQ User Manual  
vi  
© National Instruments Corporation  
 
Figures  
Figure 3-2.  
Figure 3-3.  
Figure 3-6.  
Figure 3-7.  
Snap Programming Flowchart...............................................................3-7  
Grab Programming Flowchart...............................................................3-9  
Signal I/O Function Programming Flowchart.......................................3-14  
Composite StillColor Snap Programming Flowchart............................3-17  
Figure A-1. Classical Decoding................................................................................A-4  
Figure A-3. White Light and the Visible Spectrum..................................................A-7  
Tables  
Table 1-1.  
Import Libraries.....................................................................................1-3  
Interface Naming Convention ...............................................................3-2  
Table 3-1.  
© National Instruments Corporation  
vii  
NI-IMAQ User Manual  
 
About This Manual  
NI-IMAQ software is a powerful application programming interface (API)  
between your image acquisition application and the National Instruments  
image acquisition (IMAQ) devices. This manual explains how to use your  
NI-IMAQ software.  
How to Use the NI-IMAQ Manual Set  
To install your software and documentation set, you should begin by  
reading the setup and test document included with your hardware and the  
NI-IMAQ release notes. These documents contain information about how  
to install your software and hardware. Then read Chapter 1, Introduction,  
of the your hardware user manual, which contains a flowchart that  
illustrates the sequence of steps you should take to learn about and get  
started with NI-IMAQ.  
When you are familiar with the material in this manual, you can use the  
descriptions of the NI-IMAQ functions.  
Organization of This Manual  
The NI-IMAQ User Manual is organized as follows:  
Chapter 1, Introduction to NI-IMAQ, describes the NI-IMAQ software  
and lists the application development environments compatible with  
NI-IMAQ, describes the fundamentals of creating NI-IMAQ  
applications for Windows 95 and Windows NT, describes the files used  
to build these applications, and tells you where to find sample  
programs.  
functions and briefly describes each function.  
Chapter 3, Programming with NI-IMAQ, contains an overview of the  
NI-IMAQ library, a description of the programming flow of NI-IMAQ,  
and programming examples.  
Appendix A, StillColor, describes the different methods you can use to  
acquire a color image using the IMAQ PCI/PXI-1408 and National  
Instruments StillColor technology, explains basic color theories, and  
describes the different output options supported by StillColor.  
© National Instruments Corporation  
ix  
NI-IMAQ User Manual  
 
     
About This Manual  
Appendix B, Customer Communication, contains forms you can use to  
request help from National Instruments or to comment on our products  
and manuals.  
The Glossary contains an alphabetical list and description of terms  
used in this manual, including abbreviations, acronyms, metric  
prefixes, mnemonics, and symbols.  
The Index contains an alphabetical list of key terms and topics in this  
manual, including the page where you can find each one.  
Conventions Used in This Manual  
The following conventions are used in this manual:  
This icon to the left of bold italicized text denotes a note, which alerts you  
to important information.  
bold  
Bold text denotes menus, menu items, or dialog box buttons or options.  
Bold italic text denotes a note, caution, or warning.  
bold italic  
italic  
Italic text denotes emphasis, a cross reference, or an introduction to a key  
concept.  
italic monospace  
monospace  
Italic text in this font denotes that you must supply the appropriate words  
or values in the place of these items.  
Lowercase text in this font denotes text or characters that are to be literally  
input from the keyboard, sections of code, programming examples, and  
syntax examples. This font is also used for the proper names of disk drives,  
paths, directories, programs, subprograms, subroutines, device names,  
functions, variables, filenames, and extensions, and for statements and  
comments taken from program code.  
NI-IMAQ User Manual  
x
© National Instruments Corporation  
 
 
About This Manual  
National Instruments Documentation  
The NI-IMAQ User Manual is one piece of the documentation set for your  
system. You could have any of several types of documents, depending on  
the hardware and software in your system. Use the documents you have as  
follows:  
Your IMAQ hardware documentation—These documents have  
detailed information about the IMAQ hardware that plugs into or is  
connected to your computer. Use these manuals for hardware  
installation and configuration instructions, hardware specification  
information, and application hints.  
Software documentation—Examples of software documentation you  
might have are the LabVIEW and LabWindows/CVI documentation,  
the ComponentWorks documentation, the IMAQ Vision  
documentation, and the NI-IMAQ documentation. After you have set  
up your hardware system, use either the application software  
(LabVIEW or LabWindows/CVI) or the NI-IMAQ documentation to  
help you write your application. If you have a large and complicated  
system, it is worthwhile to look through the software documentation  
before you configure your hardware.  
Accessory installation guide or manuals—If you are using accessory  
products, read the installation guides. They explain how to physically  
connect the relevant pieces of the system. Consult these guides when  
you are making your connections.  
Related Documentation  
The following document contains information you may find useful as you  
read this manual:  
Microsoft Visual C++ User Guide to Programming  
Customer Communication  
National Instruments wants to receive your comments on our products  
and manuals. We are interested in the applications you develop with our  
products, and we want to help if you have problems with them. To make it  
easy for you to contact us, this manual contains comment and configuration  
forms for you to complete. These forms are in Appendix B, Customer  
Communication, at the end of this manual.  
© National Instruments Corporation  
xi  
NI-IMAQ User Manual  
 
     
1
Introduction to NI-IMAQ  
This chapter describes the NI-IMAQ software and lists the application  
development environments compatible with NI-IMAQ, describes the  
fundamentals of creating NI-IMAQ applications for Windows 95 and  
Windows NT, describes the files used to build these applications, and tells  
you where to find sample programs.  
About the NI-IMAQ Software  
Thank you for buying a National Instruments image acquisition (IMAQ)  
device, which includes NI-IMAQ software. NI-IMAQ is a set of functions  
that controls the National Instruments plug-in IMAQ devices for image  
acquisition and Real-Time System Integration (RTSI) bus multiboard  
synchronization.  
NI-IMAQ has both high-level I/O functions for maximum ease of use and  
low-level I/O functions for maximum flexibility and performance.  
Examples of high-level functions are snap and grab image acquisition.  
Examples of low-level functions are buffer setup and video configuration.  
NI-IMAQ enhances the performance of National Instruments IMAQ  
devices because it lets multiple devices operate at their peak performance.  
NI-IMAQ includes a buffer and data manager that uses sophisticated  
techniques for handling and managing image acquisition buffers so that you  
can simultaneously acquire and process data. NI-IMAQ uses direct  
memory access (DMA) to transfer all data.  
NI-IMAQ is a library of routines that work with National Instruments  
IMAQ devices. NI-IMAQ contains methods for overcoming difficulties  
ranging from simple device initialization to advanced high-speed real-time  
image acquisition. The number of services you need for your applications  
depends on the types of IMAQ devices you have and the complexity of your  
applications.  
© National Instruments Corporation  
1-1  
NI-IMAQ User Manual  
 
         
Chapter 1  
Introduction to NI-IMAQ  
Application Development Environments  
This release of NI-IMAQ supports the following Application Development  
Environments (ADEs) for Windows 95 and Windows NT:  
LabVIEW version 4.x and higher  
LabWindows/CVI version 4.x and higher  
BridgeVIEW version 1.x and higher  
Borland C/C++ version 4.0 and higher  
Microsoft Visual C/C++ version 2.0 and higher  
Microsoft Visual Basic version 4.0 and higher  
Note  
Although NI-IMAQ has been tested and found to work with these ADEs, other  
ADEs or higher versions of the ADEs listed above may also work.  
If you are using Visual Basic, NI-IMAQ support is provided by the  
ComponentWorks IMAQ hardware interface control. Please consult the  
ComponentWorks IMAQ Vision documentation for more information.  
Files on the NI-IMAQ software media may be compressed. Always run the  
NI-IMAQ installation utility to extract the files you want. For a brief  
description of the directories produced by the install programs and the  
names and purposes of the uncompressed files, consult the readme.txt  
file on your installation CD or diskettes.  
Fundamentals of Building Applications with NI-IMAQ  
The NI-IMAQ Libraries  
The NI-IMAQ for Windows 95/NT function libraries are dynamic link  
libraries (DLLs), which means that NI-IMAQ routines are not linked into  
the executable files of applications. Only the information about the  
NI-IMAQ routines in the NI-IMAQ import libraries is stored in the  
executable files.  
Import libraries contain information about their DLL-exported functions.  
They indicate the presence and location of the DLL routines. Depending  
on the development tools you are using, you may give the DLL routines  
information through import libraries or through function declarations. Your  
NI-IMAQ software kit contains function prototypes for all routines.  
NI-IMAQ User Manual  
1-2  
© National Instruments Corporation  
 
     
Chapter 1  
Introduction to NI-IMAQ  
Creating an Application  
This section outlines the process for developing NI-IMAQ applications  
using C for Windows 95 and Windows NT. Detailed instructions on  
creating project and source files are not included. For information on  
creating and managing project files, consult the documentation included  
with your particular development environment.  
When programming, use the following guidelines:  
You must define the constant _NIWIN prior to including any  
NI-IMAQ header files. You can define this constant in your source files  
by using the #definedirective; that is, #define_NIWIN. Or, you  
can add the definition to your project file’s preprocessor definitions if  
your environment supports this feature.  
All C source files that use NI-IMAQ functions must include the  
NIIMAQ.Hheader file. Add this file to the top of your source files.  
You must add the IMAQ.LIBimport library to your project. Some  
environments allow you to add import libraries simply by inserting  
them into your list of project files. Other environments allow you to  
specify import libraries under the linker settings portion of the project  
file.  
When compiling, you will need to indicate where the compiler can find  
the NI-IMAQ header files and shared libraries. Most of the files you  
need for development are located under the NI-IMAQ target  
installation directory. If you choose the default directory during  
installation, the target installation directory is C:\Program Files\  
National Instruments\NI-IMAQ. The include files are located  
under the includesubdirectory. The import libraries are located  
under the lib\<environment>subdirectory for the following  
platforms:  
Table 1-1. Import Libraries  
Development Environment  
Microsoft Visual C++  
Borland C++  
Directory  
lib\msc  
lib\bc  
© National Instruments Corporation  
1-3  
NI-IMAQ User Manual  
 
   
Chapter 1  
Introduction to NI-IMAQ  
Sample Programs  
Please refer to the readme.txtfile located in your target installation  
directory for the latest details on NI-IMAQ sample programs. These  
programs are installed in the samplesubdirectory under the target  
installation folder if you elected to install the sample files.  
NI-IMAQ User Manual  
1-4  
© National Instruments Corporation  
 
 
2
Software Overview  
This chapter describes the classes of NI-IMAQ functions and briefly  
describes each function.  
Introduction  
NI-IMAQ functions are grouped according to the following classes:  
Generic functions  
High-level functions  
Snap functions  
Grab functions  
Ring and sequence functions  
Signal I/O functions  
Miscellaneous functions  
Low-level functions  
Acquisition functions  
Attribute functions  
Buffer management functions  
Interface functions  
Utility functions  
The generic and high-level functions appear within each function class in  
the logical order you might need to use them. The low-level functions  
appear within each function class in alphabetical order.  
© National Instruments Corporation  
2-1  
NI-IMAQ User Manual  
 
         
Chapter 2  
Software Overview  
Generic Functions  
Use generic functions in both high-level and low-level applications.  
imgInterfaceOpen  
Opens by name an interface as specified  
in the IMAQ Configuration Utility.  
imgSessionOpen  
imgClose  
Opens a session of an unknown type and  
returns a session ID.  
Closes a session or interface and unlocks  
and releases all buffers associated with  
the data type.  
High-Level Functions  
Use high-level functions to quickly and easily capture images. If you need  
more advanced functionality, you can mix high-level functions with  
low-level functions.  
Snap Functions  
Snap functions program the session to capture all or a portion of a single  
frame or field to the user buffer.  
imgSnap  
Performs a single frame and field  
acquisition.  
imgSnapArea  
Performs an area-specific frame or field  
acquisition.  
Grab Functions  
Grab functions start a continuous image acquisition to a user buffer. Any  
frame or field can be copied from the grab buffer to another user buffer.  
imgGrabSetup  
Configures and optionally starts a  
continuous acquisition.  
imgGrab  
Performs a transfer from a continuous  
acquisition session. Call this function  
only after calling imgGrabSetup.  
NI-IMAQ User Manual  
2-2  
© National Instruments Corporation  
 
       
Chapter 2  
Software Overview  
imgGrabArea  
Performs a transfer from a continuous  
acquisition. Call this function only after  
calling imgGrabSetup.  
Ring and Sequence Functions  
Ring and sequence functions start and stop a continuous acquisition of  
multiple fields or frames.  
imgRingSetup  
Prepares a session for acquiring  
continuously and looping into a buffer  
list.  
imgSequenceSetup  
Prepares a session for acquiring a full  
sequence into the buffer list.  
imgSessionStartAcquisition  
Starts a session acquisition identified by  
the session ID.  
imgSessionStopAcquisition  
Stops a session acquisition identified by  
the session ID.  
Signal I/O Functions  
Signal I/O functions control the trigger lines on IMAQ devices.  
imgSessionTriggerConfigure  
Configures an acquisition to start based  
on an external trigger.  
imgSessionLineTrigSourceConfigures triggering per line for  
acquisition from a line scan camera.  
imgSessionTriggerClear Disables all triggers on the session.  
imgSessionTriggerDrive Configures the specified trigger line to  
drive a signal out.  
imgSessionTriggerRead  
imgSessionWaitSignal  
Reads the current value of the specified  
trigger line.  
Waits for a signal to be asserted. This  
function will return when the specified  
signal is asserted.  
© National Instruments Corporation  
2-3  
NI-IMAQ User Manual  
 
   
Chapter 2  
Software Overview  
imgSessionWaitSignalAsync  
imgPulseCreate  
Monitors for a signal to be asserted and  
invokes a user-defined callback when the  
signal is asserted.  
Configures the attributes of a pulse. A  
single pulse consists of a delay phase  
(phase 1), followed by a pulse phase  
(phase 2), and then a return to the phase 1  
level.  
imgPulseDispose  
imgPulseRate  
Disposes of a pulse ID.  
Converts delay and width into delay,  
width, and timebase values needed by  
imgPulseCreate.  
imgPulseStart  
imgPulseStop  
Starts the generation of a pulse. You must  
call imgPulseCreatefirst to configure  
the pulse.  
Stops the generation of a pulse.  
Miscellaneous Functions  
Miscellaneous functions set and get the acquisition window’s region of  
interest and return information such as session status and buffer sizes.  
imgSessionStatus  
imgSessionSetROI  
imgSessionGetROI  
Gets the current session status.  
Sets acquisition origin and dimension.  
Gets acquisition origin and dimension.  
imgSessionGetBufferSize Gets the minimum buffer size needed for  
frame buffer allocation.  
NI-IMAQ User Manual  
2-4  
© National Instruments Corporation  
 
 
Chapter 2  
Software Overview  
Low-Level Functions  
Use low-level functions when you require more direct hardware control.  
Acquisition Functions  
Use acquisition functions to configure, start, and abort an image  
acquisition, or examine a buffer during an acquisition.  
imgMemLock  
Locks all session-associated image  
buffers in memory in preparation for an  
acquisition.  
imgMemUnlock  
Unlocks all session-associated buffers.  
imgSessionAbort  
Stops an asynchronous acquisition or  
synchronous continuous acquisition  
immediately.  
imgSessionAcquire  
Starts acquisition synchronously or  
asynchronously to the frame buffers in  
the associated session buffer list.  
imgSessionConfigure  
imgSessionCopyArea  
imgSessionCopyBuffer  
Specifies the buffer list to use with this  
session.  
Copies an area of a session’s buffer to a  
user-specified buffer.  
Copies a session’s image data to a user  
buffer format.  
imgSessionExamineBuffer Extracts a buffer from a live acquisition;  
lets you lock a buffer out of a continuous  
loop sequence for processing when you  
are performing a ring (continuous)  
acquisition.  
imgSessionReleaseBuffer Releases a buffer that was previously held  
with imgSessionExamineBuffer.  
© National Instruments Corporation  
2-5  
NI-IMAQ User Manual  
 
   
Chapter 2  
Software Overview  
Attribute Functions  
Use attribute functions to examine and change NI-IMAQ or camera  
attributes.  
imgGetAttribute  
Returns an attribute for an interface or  
session.  
imgGetCameraAttributeNumeric  
Gets the value of numeric camera  
attributes.  
imgGetCameraAttributeString  
Gets the value of camera attributes.  
imgSessionGetLostFramesList  
Gets information about frames that were  
overwritten during a continuous  
acquisition.  
imgSetAttribute  
Sets an attribute for an interface or  
session.  
imgSetCameraAttributeNumeric  
Sets the value of numeric camera  
attributes.  
imgSetCameraAttributeString  
Sets the value of camera attributes.  
Buffer Management Functions  
Use buffer management functions to set up objects such as buffer lists and  
buffers.  
imgCreateBuffer  
imgCreateBufList  
Creates a user frame buffer based on the  
geometric definitions of the associated  
session.  
Creates a buffer list that is passed to  
imgSessionConfigure.  
imgDisposeBuffer  
imgDisposeBufList  
Disposes of a user frame buffer.  
Purges all image buffers associated with  
this buffer list.  
NI-IMAQ User Manual  
2-6  
© National Instruments Corporation  
 
   
Chapter 2  
Software Overview  
imgGetBufferElement  
Gets an element of a specific type from a  
buffer list.  
imgSessionClearBuffer  
Clears a session’s image data to the  
specified pixel value.  
imgSetArrayPointerValue Constructs an array of 32-bit pointers  
(a Visual Basic helper function).  
imgSetBufferElement  
Sets a buffer list element of a given type  
to a specific value.  
Interface Functions  
Interface functions load and control the selected IMAQ device and  
cameras. These functions use information stored by the IMAQ  
Configuration Utility.  
imgInterfaceLock  
Locks a logical interface so that another  
process cannot use it.  
imgInterfaceQueryNames Returns the interface name identified by  
the index parameter.  
imgInterfaceReset  
imgInterfaceUnlock  
Performs a hardware reset on the  
interface type and returns a status,  
either good or bad.  
Unlocks a logical interface, allowing  
another process to use it.  
Utility Functions  
Use utility functions to display an image in a window, save an image to a  
file, or to get detailed error information.  
imgPlot  
Plots a buffer to a window given a native  
window handle.  
imgSessionSaveBufferEx Saves a buffer of a session to disk in a  
native operating system-specific format  
such as bitmap or tag image file format  
(TIFF).  
imgShowError  
Returns a null terminated string  
describing the error code.  
© National Instruments Corporation  
2-7  
NI-IMAQ User Manual  
 
   
3
Programming with NI-IMAQ  
This chapter contains an overview of the NI-IMAQ library, a description  
of the programming flow of NI-IMAQ, and programming examples.  
Flowcharts are included for the following operations: snap, grab, sequence,  
ring, and StillColor acquisitions.  
Introduction  
The NI-IMAQ API is divided into two groups, the high-level functions  
and the low-level functions. With the high-level functions, you can write  
programs quickly without having to learn the details of the low-level API  
and driver. The low-level functions give you finer granularity and control  
over your image acquisition process, but you must understand the API and  
driver in greater detail.  
Note  
The high-level functions call low-level functions and use certain attributes that  
are listed in the high-level function description in the NI-IMAQ Function  
Reference Manual. Changing the value of these attributes while using low-level  
functions will affect the operation of the high-level functions.  
High-Level Functions  
The high-level function set supports four basic types of image acquisition:  
Snap acquires a single frame or field to a buffer.  
Grab performs an acquisition that loops continually on one buffer; you  
obtain a copy of the acquisition buffer by grabbing a copy to a separate  
buffer that can be used for analysis.  
Sequence performs an acquisition that acquires a specified number of  
buffers, then stops.  
Ring performs an acquisition that loops continually on a specified  
number of buffers.  
The high-level function set also allows simple triggered acquisitions and  
the generation of external signals on the trigger lines.  
© National Instruments Corporation  
3-1  
NI-IMAQ User Manual  
 
           
Chapter 3  
Programming with NI-IMAQ  
Low-Level Functions  
The low-level function set supports all types of acquisition and can be  
used to:  
Create a custom acquisition sequence or ring  
Create and manage your own buffers  
Set session and interface attributes to adjust image quality and size  
Start a synchronous or asynchronous acquisition  
Extract buffers out of a live acquisition for analysis  
Set up and control triggered acquisitions  
Establishing Interface Connections and Sessions  
To acquire images using the high-level or low-level functions, you must  
first learn how to establish a connection to an interface and create a session.  
See the Interface Functions and Session Functions sections in this chapter  
for information on how to manage interfaces and sessions, then refer to the  
high-level or low-level samples for information on acquiring images.  
Interface Functions  
Use interface functions to query the number of available interfaces,  
establish a connection to, control access to, and initialize hardware such as  
the PCI/PXI-1408. All interfaces in NI-IMAQ are specified by a name. By  
default, the system creates default names for the number of boards in your  
system. These names observe the convention shown in Table 3-1.  
Table 3-1. Interface Naming Convention  
Interface Name  
Board Installed  
img0  
img1  
...  
Board 0  
Board 1  
...  
imgn  
Board n  
You can edit existing or create new interfaces by using the IMAQ  
Configuration Utility. You also can use the IMAQ Configuration Utility to  
configure the board serial number and the default state of a particular  
interface.  
NI-IMAQ User Manual  
3-2  
© National Instruments Corporation  
 
           
Chapter 3  
Programming with NI-IMAQ  
Before you can acquire image data successfully, you must open an interface  
by using the imgInterfaceOpenfunction. imgInterfaceOpenrequires  
an interface name and returns a handle to this interface. NI-IMAQ then uses  
this handle to reference this interface when using other NI-IMAQ  
functions.  
To establish a connection to the first board in your system, use the  
following program example:  
INTERFACE_ID  
interfaceID;  
if (imgInterfaceOpen(“img0”, &interfaceID) == IMG_ERR_GOOD)  
{
… user code …  
imgClose(interfaceID, FALSE);  
}
This example opens an interface to img0. When the program is finished  
with the interface, it closes the interface using the imgClosefunction.  
For a complete list of the available interface functions, refer to the  
NI-IMAQ Function Reference Manual.  
Session Functions  
Use session functions to configure the type of acquisition you want  
to perform on a particular interface. After you have established a  
connection to an interface, you need to create a session and configure it  
to perform the type of acquisition you require.  
To create a session, call the imgSessionOpenfunction. This function  
requires a valid interface handle and returns a handle to a session.  
NI-IMAQ then uses this session handle to reference this session when using  
other NI-IMAQ calls.  
To create a session, use the following example program:  
INTERFACE_ID  
SESSION_ID  
interfaceID;  
sessionID;  
if (imgInterfaceOpen(“img0”, &interfaceID) == IMG_ERR_GOOD)  
{
if (imgSessionOpen(interfaceID, &sessionID) == IMG_ERR_GOOD)  
{
… user code …  
imgClose(sessionID, FALSE);  
}
imgClose(interfaceID, FALSE);  
}
© National Instruments Corporation  
3-3  
NI-IMAQ User Manual  
 
   
Chapter 3  
Programming with NI-IMAQ  
This example opens an interface to img0and then creates a session to  
acquire images. When the program is finished with the interface and  
session, it then closes both handles using the imgClosefunction.  
For a complete list of the available session functions, refer to the NI-IMAQ  
Function Reference Manual.  
Managing Buffers  
Buffer management can be performed either by you or automatically by  
NI-IMAQ. If the high-level acquisition routines (imgSnap, imgGrab,  
imgSequenceSetup, and imgRingSetup) are initiated with NULL  
pointers for buffer addresses, NI-IMAQ will automatically allocate a buffer  
and return the value of the buffer pointer to you. After you have a buffer  
pointer, you can use this pointer in successive calls.  
For greater control of the acquisition buffers, such as creating buffers larger  
than the image size for adding borders, you can create them by calling a  
memory allocation routine (for example, malloc) or using the low-level  
function imgCreateBuffer. When creating buffers using either approach,  
dispose of the buffers using freeor imgDisposeBufferwhen applicable  
to free PC memory for maximum performance.  
Camera Attributes  
The camera attributes allow you to control camera functions, such as  
integration time and pixel binning, directly from NI-IMAQ. These camera  
attributes are camera-specific and can also be set in the IMAQ  
Configuration Utility on the Advanced tab. Information about specific  
attributes for your camera is contained in <my camera>.txt, which can  
be found in the ni-imaq/camera infodirectory. For more information  
about camera attributes and their uses, please consult your camera  
documentation.  
Note  
Currently, camera attributes are supported only by the IMAQ PCI-1424.  
The camera attribute file lists all attributes for the camera. Each attribute  
description contains four fields—Attribute Name, Description,  
Data Type, and Possible Values. The Attribute Name field contains the  
name of the attribute in quotes. The Data Type field contains the data type  
of the attribute—String, Integer, or Float. String indicates that there are  
several valid values for this attribute that are expressed as strings. The list  
of valid values is indicated in Possible Values. Integer indicates that the  
NI-IMAQ User Manual  
3-4  
© National Instruments Corporation  
 
   
Chapter 3  
Programming with NI-IMAQ  
attribute value is a numeric value of type integer. Float indicates that the  
attribute value is a numeric value of type floating point. The valid integer  
and float values are indicated in Possible Values.  
Use the imgSetCameraAttributeStringand  
imgGetCameraAttributeStringfunctions to set and get the value of  
String, Float and Integer attributes. Use the  
imgSetCameraAttributeNumericand  
imgGetCameraAttributeNumericfunctions to set and get the value of  
Float and Integer attributes.  
Note  
The spelling and syntax of the Attribute Name and string values must match the  
camera attribute file exactly.  
NI-IMAQ Status Signals  
NI-IMAQ has several status signals that can be used to trigger the  
generation of a pulse or invoke a callback function. Acquisition in  
Progress indicates that the board is acquiring image data. This signal goes  
TRUE when the board initiates the acquisition either through a software or  
hardware triggered start. When the last piece of image data is transferred to  
memory, this signal goes FALSE. If the acquisition is a sequence,  
acquisition in progress will stay TRUE throughout the acquisition until the  
entire sequence is completed. Acquisition Done is the reverse of  
Acquisition in Progress. This signal goes TRUE when the last piece of  
data is transferred to memory indicating that the acquisition has completed.  
Frame Start and Frame Stop indicate the status of an acquisition on a  
buffer basis. Frame Start indicates that a buffer is being acquired. This  
signal goes TRUE when the first valid pixel is detected by the board (even  
if this pixel is not in the current region of interest). The signal goes FALSE  
when the last valid pixel is detected by the board. If the acquisition is a  
sequence or a ring, Frame Start will pulse for every buffer in the  
acquisition. Frame Done is the reverse of Frame Start and indicates when  
the image is transferred from the camera to the IMAQ board.  
Buffer Complete indicates when the image data has been transferred to  
memory and is available for image processing. Buffer Complete will go  
TRUE when the data in an image buffer has been transferred to memory  
(either onboard or system memory, depending on the acquisition).  
© National Instruments Corporation  
3-5  
NI-IMAQ User Manual  
 
 
Chapter 3  
Programming with NI-IMAQ  
Figure 3-1 illustrates the values of the signals during a three-buffer  
sequence acquisition.  
AQ_IN_PROGRESS  
Board Initiates  
Acquisition  
All Image  
Data In  
Memory  
FRAME_START  
First Valid  
Pixel Acquired  
By Board  
Last Valid  
Pixel Acquired  
By Board  
FRAME_DONE  
BUF_COMPLETE  
AQ_DONE  
Buffer 1  
Data In  
Memory  
Buffer 0  
Data In  
Memory  
Buffer 2  
Data In  
Memory  
Board Initiates  
Acquisition  
All Image  
Data In  
Memory  
Figure 3-1. NI-IMAQ Status Signals  
You can use the NI-IMAQ status signals for many purposes. Pulses can be  
generated based on the assertion of any of these signals. This allows you to  
generate specific timing pulses based on acquisitions to control other  
aspects of your system, such as a strobe light. Furthermore, you can  
configure callback functions that are invoked based on any of these signals.  
For example, you may want to initiate an image processing routine as soon  
as an image is in memory. You can configure a callback containing image  
processing code to be invoked when Buffer Complete is asserted.  
Introductory Programming Examples  
This section introduces some examples for performing the different types  
of image acquisition. The error codes that NI-IMAQ returns are not  
included in the examples. In your programs, always check the return code  
for errors.  
Note  
You can find these code examples in the ni-imaq\samplesdirectory.  
NI-IMAQ User Manual  
3-6  
© National Instruments Corporation  
 
     
Chapter 3  
Programming with NI-IMAQ  
High-Level Snap Functions  
A snap acquires a single image into a memory buffer. Snap functions  
include imgSnapand imgSnapArea. Use these functions to acquire a  
single frame or field to a buffer. To use these functions, you must have a  
valid session handle.  
When you invoke a snap, it initializes the board and acquires the next  
incoming video frame (or field) to a buffer. A snap is appropriate for  
low-speed or single-capture applications where ease of programming  
is essential. Figure 3-2 illustrates a typical snap programming order.  
imgInterfaceOpen opens  
and configures the interface  
according to the file setup by the  
IMAQ Configuration Utility.  
imgInterfaceOpen  
imgSessionOpen  
imgSessionOpen opens a session that  
will be used for all acquisition and configuration.  
imgSnap acquires an image into a buffer. The  
buffer may be passed into imgSnap or automatically  
allocated by NI-IMAQ. If no buffer is passed into  
imgSnap, it will automatically snap into a new buffer  
and return a pointer to the buffer.  
imgSnap  
User-Specific Functions  
User-specific image processing  
imgClose  
imgClose closes the interface and session.  
Figure 3-2. Snap Programming Flowchart  
The hlsnap.cexample demonstrates how to perform a single snap using  
imgSnap. The example opens an interface and a session and then performs  
a single snap. The buffer pointer that is passed to imgSnapis initialized to  
NULL, which instructs imgSnapto automatically allocate a buffer for the  
image. The size of the buffer is calculated based on the region of interest  
(ROI) and the rowPixel attributes: ROI height multiplied by rowPixel  
multiplied by the number of bytes per pixel. When you open a session, the  
ROI values are initialized from the acquisition window (ACQWINDOW)  
dimensions that are configured in the IMAQ Configuration Utility. The  
ACQWINDOW dimensions will vary depending on the type of camera you  
are using.  
© National Instruments Corporation  
3-7  
NI-IMAQ User Manual  
 
     
Chapter 3  
Programming with NI-IMAQ  
The sample then calls a process function to analyze the image. When the  
program is finished, it calls imgClosewith the interface handle and sets  
the freeResources flag to TRUE. This instructs NI-IMAQ to free all of the  
resources associated with this interface, which releases the session as well  
as the memory buffer allocated by imgSnap.  
High-Level Grab Functions  
A grab is a continuous high-speed acquisition of data to a single buffer in  
host memory. Grab functions include imgGrabSetup, imgGraband  
imgGrabArea. You can use these functions to perform an acquisition that  
loops continually on one buffer. A copy of the acquisition buffer is  
obtained by grabbing a copy to a separate buffer. To use these functions,  
you must have a valid session handle.  
Calling imgGrabSetupinitializes a session for a grab acquisition.  
After imgGrabSetup, each successive grab will copy the last acquired  
buffer into a user buffer where you can perform processing on the image. A  
grab is appropriate for high-speed applications where you need processing  
performed on only one image at a time. Figure 3-3 illustrates a typical grab  
programming order.  
NI-IMAQ User Manual  
3-8  
© National Instruments Corporation  
 
 
Chapter 3  
Programming with NI-IMAQ  
imgInterfaceOpen opens  
and configures the interface  
according to the file setup by the  
IMAQ Configuration Utility.  
imgInterfaceOpen  
imgSessionOpen opens a session that  
imgSessionOpen  
imgGrabSetup  
will be used for all acquisition and configuration.  
imgGrabSetup configures the interface for a  
continuous acquisition.  
imgSessionStartAcquisition starts  
the acquisition into a driver buffer.  
imgSessionStartAcquisition  
imgGrab copies the contents of the driver buffer  
to a user buffer. This function can be synchronized  
to a vertical blank or initiated asynchronously. The  
buffer can be passed into imgGrab or automatically  
allocated by NI-IMAQ. imgGrab can be called  
multiple times for high-speed acquisition.  
imgGrab  
User-Specific Functions  
imgSessionStopAcquisition  
imgClose  
User-specific image processing  
(Loop)  
imgSessionStopAcquisition stops  
the grab function.  
imgClose closes the interface and session.  
Figure 3-3. Grab Programming Flowchart  
The hlgrab.c example demonstrates how to perform a grab using  
imgGrabArea. The example performs multiple grabs until an appropriate  
condition is met. The program configures the session to perform a grab  
operation by calling the imgGrabSetupfunction. The program then  
calculates the area to grab using the current ROI, rowPixels, and  
BYTESPERPIXEL, and the acquisition is started by calling  
imgSessionStartAcquisition. In this example, we allocate our  
own user buffer for grabbing and pass this buffer to imgGrabArea. When  
the acquisition is complete, it stops. The program then frees the user buffer  
and all of the resources associated with this interface by calling imgClose.  
© National Instruments Corporation  
3-9  
NI-IMAQ User Manual  
 
   
Chapter 3  
Programming with NI-IMAQ  
High-Level Sequence Functions  
Sequence functions include imgSequenceSetup,  
imgSessionStartAcquisitionand imgStopAcquisition. A  
sequence initiates a variable-length and variable-delay transfer to multiple  
buffers. You can configure the delay between acquisitions with  
SequenceSetupand specify both the buffer list that will be used for  
transfers and the number of buffers. After imgSequenceSetup, you can  
monitor the status of the transfer and perform processing on any of the  
buffers in the sequence or you can wait until the acquisition completes and  
process all buffers simultaneously.  
A sequence is appropriate for applications where you need to perform  
processing on multiple images. You can configure a sequence to acquire  
every frame or skip a variable number of frames between each image.  
Figure 3-4 illustrates a typical sequence programming order.  
imgInterfaceOpen opens  
and configures the interface  
according to the file setup by the  
IMAQ Configuration Utility.  
imgInterfaceOpen  
imgSessionOpen opens a session that  
will be used for all acquisition and configuration.  
imgSessionOpen  
You must set up your buffer list and the  
number of the frames/fields that need to  
be skipped between each acquisition.  
Buffer list setup  
imgSequenceSetup initiates a sequence to a  
programmable number of buffers. These buffers can be  
created either by the driver (using imgCreateBuffer  
or passing a NULL) or by you.  
imgSequenceSetup  
imgSessionStatus  
imgSessionStatus gives the current status of  
the sequence, including the buffer number of the last buffer  
that was successfully transferred. With this information,  
you can determine which buffer you want to process.  
User-Specific Functions  
User-specific image processing.  
(Loop)  
imgClose  
imgClose closes the interface and session.  
Figure 3-4. Sequence Programming Flowchart  
NI-IMAQ User Manual  
3-10  
© National Instruments Corporation  
 
     
Chapter 3  
Programming with NI-IMAQ  
The HLSeq.cexample demonstrates how to perform a sequence  
acquisition using imgSequenceSetup. The example sets up a sequence  
that uses 10 user-allocated buffers. Unlike the ring example, each buffer in  
the sequence has its own skip count associated with it. The skip count is the  
number of frames to skip prior to acquiring the next image. The acquisition  
is started at setup time and the setup call is synchronous.  
High-Level Ring Functions  
Ring and sequence functions include imgRingSetup,  
imgSessionStartAcquisitionand imgStopAcquisition. Use  
these functions to perform a continuous acquisition that loops or stops after  
a certain number of images have been captured.  
A ring initiates a continuous high-speed acquisition to multiple buffers.  
Calling imgRingSetupinitiates a ring. imgRingSetupspecifies both the  
buffer list that will be used for transfers and the number of buffers. After  
imgRingSetupis called, you can monitor the status of the transfer and  
perform processing on any of the buffers in the ring. A ring is appropriate  
for high-speed applications where you need to perform processing on every  
image. You must use multiple buffers because processing times may vary  
depending on other applications and processing results. You can configure  
a ring to acquire every frame or to skip a fixed number of frames between  
each acquisition.  
For certain applications, you can temporarily extract a buffer from the ring  
to prevent it from being overwritten during the ring’s next pass. Use the  
imgSessionExamineBufferand imgSessionReleaseBuffer  
functions to do this. Figure 3-5 illustrates a typical ring programming order.  
© National Instruments Corporation  
3-11  
NI-IMAQ User Manual  
 
 
Chapter 3  
Programming with NI-IMAQ  
imgInterfaceOpen opens  
and configures the interface  
according to the file setup by the  
IMAQ Configuration Utility.  
imgInterfaceOpen  
imgSessionOpen opens a session that  
imgSessionOpen  
imgRingSetup  
will be used for all acquisition and configuration.  
imgRingSetup sets up a ring acquisition to a  
programmable number of buffers. These buffers  
can be created either by the driver (using  
imgCreateBuffer or passing a NULL)  
or by you.  
imgSessionStartAcquisition starts  
imgSessionStartAcquisition  
imgSessionStatus  
the acquisition into a driver buffer.  
imgSessionStatus gives the current status of  
the ring, including the buffer number of the last buffer  
that was successfully transferred. With this information,  
you can determine which buffer you want to process  
or copy to a private location.  
User-Specific Functions  
imgSessionStopAcquisition  
imgClose  
User-specific image processing  
(Loop)  
imgSessionStopAcquisition stops  
the ring function.  
imgClose closes the interface and session.  
Figure 3-5. Ring Programming Flowchart  
The HLRing.cexample demonstrates how to perform a ring acquisition  
using imgRingSetup. The example sets up a ring containing six buffers  
and sets the skip count to three, which causes the program to acquire on  
every third frame. Unlike the sequence example, the skip count is set to the  
same value for every buffer in the ring. A skip count is the number of frames  
skipped prior to acquiring an image to a buffer. The program then loops,  
waiting for the next buffer to be acquired. The imgSessionStatus  
function queries NI-IMAQ for the buffer number of the last valid buffer that  
has been acquired. The last valid buffer is defined as the buffer that contains  
NI-IMAQ User Manual  
3-12  
© National Instruments Corporation  
 
   
Chapter 3  
Programming with NI-IMAQ  
the most recent video image. This process will continue until a designated  
condition is met and then the acquisition stops.  
High-Level Signal I/O Functions  
The signal I/O functions fall into two categories, triggering acquisitions  
and driving the external trigger lines. Triggered acquisitions allow images  
to be acquired precisely when an external event occurs, such as a sensor  
activating. The driving of external trigger lines allows external devices to  
be controlled in sync with the image acquisition. For example, a strobe light  
could be fired when a sequence acquisition begins.  
Any of the four types of acquisitions can be initiated from an external  
trigger source by using imgSessionTriggerConfigure. For sequence  
and ring, just the first buffer in the list can be triggered or each buffer in the  
list can be triggered. After using this function to set up the trigger, any  
acquisition performed on the session will wait for a trigger. Use  
imgSessionTriggerClearto remove the trigger settings from the  
session.  
Some applications need to send signals out from the IMAQ hardware to an  
external device. Many types of signals can be driven out of the trigger lines  
by using imgSessionTriggerDrive. This function takes a trigger line  
number, the polarity the line should be driven, and what to drive on the line.  
This can be a steady state value of high or low or it can be one of the internal  
state signals of the hardware, such as acquisition in progress. When specific  
pulses need to be generated, imgPulseCreateand imgPulseStartcan  
be used.  
Figure 3-6 shows the outline of a program that waits for an external trigger  
on line 1 before acquiring a single image. It also configures the driver to  
assert RTSI trigger line 3 when the acquisition is finished. The  
trigsnap.c example contains C code that implements this program.  
© National Instruments Corporation  
3-13  
NI-IMAQ User Manual  
 
 
Chapter 3  
Programming with NI-IMAQ  
imgInterfaceOpen opens and configures the  
interface according to the file set up by the  
IMAQ Configuration Utility.  
imgInterfaceOpen  
imgSessionOpen  
imgSessionOpen opens a session that  
will be used for an acquisition.  
imgSessionTriggerConfigure configures the  
session so that an acquisition will not occur until a trigger  
is received on external trigger line 1.  
imgSessionTriggerConfigure  
imgSessionTriggerDrive  
imgSessionTriggerDrive configures the session  
so that RTSI trigger line 3 will be driven high when the  
acquisition has completed.  
imgSnap starts the acquisition. The actual snap will  
imgSnap  
User-Specific Functions  
imgClose  
not occur until the trigger is received.  
User-specific image processing.  
imgClose closes the session and interface.  
Figure 3-6. Signal I/O Function Programming Flowchart  
Advanced Programming Examples  
You can use low-level functions or combine high-and low-level functions  
for more advanced programming techniques, including snap, grab,  
sequence, ring, and color image acquisitions.  
Performing a Snap Using Low-Level Functions  
The LLSnap.c example demonstrates how to perform a snap acquisition  
using low-level calls. The example sets up a single-frame acquisition to a  
buffer allocated by NI-IMAQ. The program retrieves the acquisition  
window width of the selected camera and aligns it on a 32-bit boundary.  
You must align both the acquisition window width and rowPixels on a  
32-bit boundary to ensure that your image is acquired properly. The  
software does not perform this alignment for you unless you select a scaling  
option. Although the IMAQ Configuration Utility performs this alignment  
NI-IMAQ User Manual  
3-14  
© National Instruments Corporation  
 
       
Chapter 3  
Programming with NI-IMAQ  
for you when you acquire an image with it, you must perform the alignment  
yourself if you use window widths not aligned on a 32-bit boundary.  
After the program sets the ROI, it locks the memory and acquires the  
image. If you choose to plot the image using the imgPlotfunction,  
you must align the image width on a 32-bit boundary as well.  
Performing a Grab Using Low-Level Functions  
The LLGrab.cexample demonstrates how to perform a grab acquisition  
using low-level calls. The example sets up a continuous acquisition to a  
single user-allocated buffer.  
As described in the low-level snap example, the program retrieves the  
acquisition window width of the selected camera and aligns it on a 32-bit  
boundary. The program creates a buffer list to describe the acquisition  
buffers. Next, the program sets the ROI to the acquisition window width.  
The program performs a calculation to determine the correct memory  
requirements of the user buffer. The program creates the buffer and  
configures buffer element 0 for a single continuous acquisition. The  
program then locks the memory and starts the image acquisition  
asynchronously. The main processing loop of the code shows how to wait  
for vertical blank and copy the buffer to an analysis buffer.  
Keep your analysis code fast to minimize the number of missed frames  
during analysis. If you need more time to examine a buffer, set up a  
multiple-buffer ring and call imgSessionExamineBufferto extract  
the desired buffer from the live sequence.  
Performing a Sequence Acquisition Using Low-Level Functions  
The LLSeq.c example demonstrates how to perform a sequence  
acquisition using low-level calls. The example sets up a sequence  
acquisition to multiple buffers allocated by NI-IMAQ. As described in the  
low-level snap example, the program retrieves the acquisition window  
width of the selected camera and aligns it on a 32-bit boundary. It creates a  
buffer list to describe the acquisition buffers. Next, the program sets the  
ROI to the acquisition window width. The program calculates the correct  
memory requirements of the frame buffer. However, this is not necessary  
if you choose to use the default acquisition window width, rowPixels, and  
ROI. In this case, NI-IMAQ will allocate the correct size buffer if you pass  
a NULL as the size parameter to imgCreateBuffer. The program creates  
the buffer and configures the buffer list for each buffer element in the ring.  
The program locks the memory and starts the image acquisition  
asynchronously.  
© National Instruments Corporation  
3-15  
NI-IMAQ User Manual  
 
   
Chapter 3  
Programming with NI-IMAQ  
The main processing loop of the code shows how to process each buffer  
acquired in sequential order.  
Performing a Ring Acquisition Using Low-Level Functions  
The LLRing.c example demonstrates how to perform a ring acquisition  
using low-level calls. The example sets up a continuous acquisition to  
multiple buffers allocated by NI-IMAQ.  
As described in the low-level snap example, the program retrieves the  
acquisition window width of the selected camera and aligns it on a 32-bit  
boundary. It then creates a buffer list to describe the acquisition buffers.  
Next, the program sets the ROI to the acquisition window width. The  
program calculates the correct memory requirements of the frame buffer.  
However, this is not necessary if you choose to use the default acquisition  
window width, rowPixels, and ROI. In this case, NI-IMAQ will allocate the  
correct size buffer if you pass a NULL as the size parameter to  
imgCreateBuffer. The buffer is created and the buffer list is configured  
for each buffer element in the ring. The memory is locked and the image  
acquisition is started asynchronously.  
The main processing loop of the code shows how to wait for the first buffer  
to be filled and subsequently processed. NI-IMAQ returns a value of  
0xFFFFFFFFas the IMG_ATTR_LAST_VALID_BUFFER attribute until  
the successful acquisition of the first buffer. To guarantee that you wait for  
the acquisition of a new buffer in a ring with more than one buffer, you can  
loop on the attribute IMG_ATTR_LAST_VALID_BUFFER until it  
changes. If your buffer analysis requires many computations, call  
imgSessionExamineBufferto extract the desired buffer from the live  
sequence. When using imgSessionExamineBuffer, the buffer requested  
is literally pulled from the looping sequence for the duration of the analysis.  
Use imgSessionReleaseBufferto return the buffer to the continuous  
sequence.  
StillColor Snap Programming  
You can use the high-level snap function to acquire StillColor images from  
either composite or RGB video sources. As shown in Figure 4-6, acquiring  
a StillColor image is identical to acquiring a monochrome image except for  
two session attribute settings. For more information on StillColor, see  
Appendix A, StillColor.  
NI-IMAQ User Manual  
3-16  
© National Instruments Corporation  
 
   
Chapter 3  
Programming with NI-IMAQ  
imgInterfaceOpen opens  
and configures the interface  
according to the file setup by the  
IMAQ Configuration Utility.  
imgInterfaceOpen  
imgSessionOpen opens a session that  
imgSessionOpen  
imgSetAttribute  
will be used for all acquisition and configuration.  
imgSetAttribute configures the StillColor  
mode to acquire a StillColor image from  
a composite source using the attribute  
IMG_ATTR_COLOR_MODE.  
imgSetAttribute configures the image  
representation for 32-bit RGB mode using the attribute  
IMG_ATTR_COLOR_IMAGE_REP.  
imgSetAttribute  
imgSnap  
imgSnap acquires an image into a buffer. The  
buffer may be passed into imgSnap or automatically  
allocated by NI-IMAQ. If no buffer is passed into  
imgSnap, then imgSnap will automatically snap into  
a new buffer and return a pointer to the buffer.  
User-Specific Functions  
User-specific image processing.  
imgClose  
imgClose closes the interface and session.  
Figure 3-7. Composite StillColor Snap Programming Flowchart  
The SCSnap.cexample demonstrates how to perform a single, composite  
StillColor snap. The example first opens an interface and a session. The  
example then uses imgSetAttributeto enable and configure StillColor  
mode to acquire a composite image. The example also configures the  
image data representation to 32-bit RGB mode. imgSnapacquires a  
StillColor image and returns the image data in the buffer. After the example  
processes the image, it calls imgCloseto close the handles and free all of  
the resources associated with the interface.  
© National Instruments Corporation  
3-17  
NI-IMAQ User Manual  
 
 
A
StillColor  
This appendix describes the different methods you can use to acquire a  
color image using the IMAQ PCI/PXI-1408 and National Instruments  
StillColor technology, explains basic color theories, and describes the  
different output options supported by StillColor.  
Introduction  
You can use two basic video camera types for color acquisition—RGB  
cameras and composite color video cameras.  
An RGB camera delivers the three basic color components—red, green  
and blue—on three different wires. This type of camera often uses three  
independent CCD sensors to acquire the three color signals. RGB cameras  
are used for very accurate color acquisition.  
A composite color camera transmits the video signal on a single wire. The  
signal is composed of two components that are added together. These  
components are:  
A monochrome video signal that contains the gray level information  
from the image and the composite synchronization signals. This signal  
is the same as a standard monochrome video signal, such as RS-170  
(NTSC) or CCIR-601 (PAL).  
A modulated signal that contains the color information from the image.  
The format of this signal depends on your camera. The three main  
color standards are as follows:  
M-NTSC (also called NTSC), which is used mainly in the US  
and Japan  
B/G-PAL (also called PAL), which is used mainly in Europe,  
India, and Australia  
SECAM, which is used mainly in France and the former Soviet  
Republics. SECAM is only used for broadcasting, so SECAM  
countries often use PAL as the local color image format.  
© National Instruments Corporation  
A-1  
NI-IMAQ User Manual  
 
       
Appendix A  
StillColor  
StillColor  
StillColor is a technique you can use to acquire color images from  
composite color video or RGB cameras using the PCI/PXI-1408  
monochrome device. Use StillColor Composite mode to acquire color  
images from a composite color video camera. Use StillColor RGB mode  
to acquire color images from an RGB camera. StillColor composite  
acquisition results in an image of much higher quality than the traditional  
color decoding that can be obtained with a color image acquisition board.  
To acquire a color image, the PCI/PXI-1408 acquires multiple frames from  
the camera. Your computer CPU then processes the frames using the  
StillColor algorithm and creates a single color image. Because StillColor  
uses your computer CPU to process the image, the acquisition time for a  
single image depends on your system performance. You can acquire  
StillColor composite images at rates of up to 2 frames/s and StillColor  
RGB images at rates of up to 10 frames/s.  
You can use StillColor in applications that require high-quality images of  
still or very slowly moving objects. StillColor supports many different  
image representations used in scientific or industrial applications, such as  
RGB bitmap and single plane hue, saturation, luminance, and intensity.  
StillColor also supports image averaging of up to 128 frames to increase the  
dynamic range of the StillColor image. See the Introduction to Color  
section later in this appendix for more information on image  
representations.  
StillColor Composite  
In a composite color video signal, the color information (chroma) is  
modulated in phase and amplitude around a sub-carrier frequency of  
3.58 MHz (NTSC) or 4.43 MHz (PAL). The modulated signal is then  
added to the luminance information and the entire signal including  
synchronization pulses is transmitted on a single line.  
Traditional Color Decoding  
On the receiver side or in your IMAQ board, the luminance and the chroma  
signals must be separated before the color image can be decoded and  
rebuilt. However, the modulated color information and some of the  
high-frequency luminance information share the same frequency range  
around the sub-carrier frequency. This sharing makes it impossible to  
separate the two signals perfectly and, therefore, perfect reconstruction of  
the original color image is not possible.  
NI-IMAQ User Manual  
A-2  
© National Instruments Corporation  
 
Appendix A  
StillColor  
All of the traditional ways to separate the two signals result in visual  
artifacts on the final picture. Techniques such as frequency-band filtering  
or comb filtering can minimize some of these artifacts, but most techniques  
are optimized to obtain the best picture for visualization of a continuous  
acquisition. The composite color formats are designed so that artifacts  
resulting from one frame are almost cancelled by artifacts in following  
frames. This system takes advantage of the slow response time of the  
human eye to obscure most of these problems.  
The situation is different in a single frame acquisition where a single image  
is needed. A single image usually clearly shows the result of a bad  
color/luminance separation. Typical weakness of traditional separation  
techniques are:  
Reduced luminance bandwidth, resulting in a blurry image.  
Cross-color modulation where rapidly changing colors affect the  
luminance of the image, as shown on the edges of the parrot’s head  
in Figure A-1.  
Cross-luminance modulation where rapidly changing luminance  
(stripes) results in irritating random color patterns, as shown on the  
black and white stripes around the parrot’s eye in Figure A-1.  
© National Instruments Corporation  
A-3  
NI-IMAQ User Manual  
 
Appendix A  
StillColor  
Figure A-1. Classical Decoding  
Figure A-2. StillColor Decoding  
Note  
You can find color versions of the illustrations in this appendix in the online  
version of this document included with your NI-IMAQ software kit.  
Both pictures are approximately 80 by 80 pixels in size and are acquired  
using an NTSC composite video signal. Figure A-1 uses classic decoding  
algorithms including bandpass/bandstop and comb filtering. Figure A-2  
was acquired using the PCI/PXI-1408 and the StillColor algorithm.  
NI-IMAQ User Manual  
A-4  
© National Instruments Corporation  
 
     
Appendix A  
StillColor  
Why StillColor?  
StillColor is optimized for single-frame acquisition. A StillColor  
Composite acquisition acquires multiple consecutive frames. Assuming  
that all frames represent the same scene of still objects, the algorithm then  
uses knowledge about the composite color format to perfectly separate the  
color and the luminance information.  
In an NTSC video signal, two consecutive frames representing the same  
object will contain the same luminance information but will have chroma  
signals that are opposite in phase. By adding the two frames together, the  
chroma information is cancelled, and by subtracting the two frames from  
each other, the luminance signal is cancelled. The resulting separation is  
now perfect, as shown in Figure A-2.  
Color and luminance separation is more complex in a PAL video signal.  
The IMAQ device must acquire three consecutive frames, but the same  
perfect separation of the color and luminance information can be achieved  
after manipulation of these images.  
After separating the color and luminance signals, the StillColor algorithm  
then decodes and rebuilds the color image. As shown in Figure A-2, the  
result does not show any of the artifacts encountered in traditional color  
decoding methods.  
Composite Color Acquisition  
The PCI/PXI-1408, in conjunction with NI-IMAQ, supports acquisition of  
color images from an NTSC or PAL composite color video camera.  
NI-IMAQ can acquire the multiple frames, decode the color information,  
and rebuild the image automatically. The output image can be a simple  
RGB color image or one of many image representations supported by  
NI-IMAQ. See the Introduction to Color section later in this appendix for  
more information on image representations.  
You can connect the composite video signal to any of the four input  
channels on the PCI/PXI-1408. Since StillColor is used for still scenes, you  
can perform only a snap (a single-image acquisition).  
© National Instruments Corporation  
A-5  
NI-IMAQ User Manual  
 
Appendix A  
StillColor  
StillColor RGB  
RGB cameras output a color image using three lines. StillColor RGB will  
acquire the three signals and construct a color image. The three lines are  
connected to three channels on the PCI/PXI-1408. One frame is acquired  
from each of the three channels, which represent the red, green, and blue  
planes of the image. StillColor combines these frames to construct the color  
image.  
RGB Color Acquisition  
color images from an RGB camera.  
The NI-IMAQ driver can acquire the three frames and rebuild the image  
automatically. The output image can be a simple RGB color image or  
one of many image representations supported by the driver. See the  
Introduction to Color section later in this appendix for more information  
on image representations.  
For a StillColor RGB snap, connect the three camera channels—red, green,  
and blue—to Video 1, Video 2, and Video 3, respectively, on the  
PCI/PXI-1408 device. Specify a channel for the video synchronization  
signal by selecting that channel as the sync source using the Operating  
Mode tab in the IMAQ Configuration Utility. A typical RGB camera  
includes the composite video synchronization signal in the green signal.  
You can also use other synchronization sources, such as an external  
composite video signal that can be connected to Video 0 or an external TTL  
composite synchronization signal that can be connected to the CSYNCIN  
pin of the DSUB connector. (See Chapter 4, Signal Connections, of your  
hardware user manual for signal connection information.)  
Introduction to Color  
Color is the wavelength of the light we receive in our eye when we look at  
an object. In theory, the color spectrum is infinite. Humans, however, can  
see only a small portion of this spectrum—the portion that goes from the  
red edge of infrared light (the longest wavelength) to the blue edge of  
ultraviolet light (the shortest wavelength). This continuous spectrum is  
called the visible spectrum, as shown in Figure A-3.  
NI-IMAQ User Manual  
A-6  
© National Instruments Corporation  
 
 
Appendix A  
StillColor  
Figure A-3. White Light and the Visible Spectrum  
White light is a combination of all colors at once. The spectrum of white  
light is continuous and goes from ultraviolet to infrared in a smooth  
transition. You can represent a good approximation of white light by  
selecting a few reference colors and weighting them appropriately. The  
most common way to represent white light is to use three reference  
components, such as red, green, and blue (R, G, and B primaries). You can  
simulate most colors of the visible spectrum using these primaries. For  
example, video projectors use red, green, and blue light generators, and an  
RGB camera uses red, green, and blue sensors.  
The perception of a color depends on many factors, such as:  
Hue, which is the perceived dominant color. Hue depends directly on  
the wavelength of a color.  
Saturation, which is dependent on the amount of white light present in  
a color. Pastels typically have a low saturation while very rich colors  
have a high saturation. For example, pink typically has a red hue but  
has a low saturation.  
Luminance, which is the brightness information in the video picture.  
The luminance signal amplitude varies in proportion to the brightness  
of the video signal and corresponds exactly to the monochrome  
picture.  
Intensity, which is the brightness of a color and which is usually  
expressed as light or dark. For example, orange and brown may have  
the same hue and saturation; however, orange has a greater intensity  
than brown.  
© National Instruments Corporation  
A-7  
NI-IMAQ User Manual  
 
   
Appendix A  
StillColor  
Image Representations  
Color images can be represented in several different formats. These formats  
can contain all color information from the image or they can consist of just  
one aspect of the color information, such as hue or luminance. The  
following image representations can be produced using NI-IMAQ and  
StillColor.  
RGB  
The most common image representation is 32-bit RGB format. In this  
representation, the three 8-bit color planes—red, green and blue—are  
packed into an array of 32-bit integers. This representation is useful for  
displaying the image on your monitor. The 32-bit integer organized as:  
0
RED  
GREEN  
BLUE  
where the high-order byte is not used and blue is the low-order byte.  
The system also supports a 24-bit and a 16-bit representation of the RGB  
image. The 24-bit representation is equivalent to the 32-bit representation;  
however, there is no unused byte. For the 16-bit representation, the image  
is packed into an array of 16-bit integers where each 16-bit pixel contains  
red, green, and blue, encoded with only five bits each. The most significant  
bit of the integer is always 0.  
Color Planes  
Each color plane can be returned individually. The red, green, or blue plane  
is extracted from the RGB image and represented as an array of 8-bit  
integers.  
Hue, Saturation, Luminance, and Intensity Planes  
The hue, saturation, luminance, and intensity planes can also be returned  
individually if you want to analyze the image. You can retrieve the data in  
8-bit format to reduce the amount of data to be processed or in 16-bit format  
to take advantage of the higher precision available when using averaging.  
The 16-bit image representation is scaled so that the pixel values are always  
positive. The value range is 0 to +32,767, so it is compatible with both  
16-bit signed and 16-bit unsigned integers. On average, the 16-bit  
representation of a plane is equal to 128 times the 8-bit representation of  
the plane from the same image. The 16-bit representation is generally only  
NI-IMAQ User Manual  
A-8  
© National Instruments Corporation  
 
Appendix A  
StillColor  
used if you are performing averaging on your image. For example,  
averaging an image 16 times requires four extra bits (16 = 24 ) to represent  
the increased dynamic range. In this case, using the 16-bit representation  
may increase the dynamic range of your image.  
Luminance, Intensity, Hue, or Saturation are defined using the Red, Green,  
and Blue values in the following formulas:  
Luminance = 0.299 × Red + 0.587 × Green + 0.114 × Blue  
Intensity = (Red + Green + Blue) / 3  
Hue = ATN2 (Y, X)  
where  
Y = (Green - Blue) / 2 and  
X = (2 × Red - Green - Blue) / 6  
Saturation = X2 × Y2  
where  
Y = (Green - Blue) / 2 and  
X = (2 × Red - Green - Blue) / 6  
32-Bit HSL and HSI  
You can also pack the three 8-bit Hue, Saturation, and Luminance planes  
(HSL) or the three Hue, Saturation, and Intensity planes (HSI) in one array  
of 32-bit integers, which is equivalent to the 32-bit RGB representation.  
© National Instruments Corporation  
A-9  
NI-IMAQ User Manual  
 
B
Customer Communication  
For your convenience, this appendix contains forms to help you gather the information necessary  
to help us solve your technical problems and a form you can use to comment on the product  
documentation. When you contact us, we need the information on the Technical Support Form and  
the configuration form, if your manual contains one, about your system configuration to answer your  
questions as quickly as possible.  
National Instruments has technical assistance through electronic, fax, and telephone systems to quickly  
provide the information you need. Our electronic services include a bulletin board service, an FTP site,  
a fax-on-demand system, and e-mail support. If you have a hardware or software problem, first try the  
electronic support systems. If the information available on these systems does not answer your  
questions, we offer fax and telephone support through our technical support centers, which are staffed  
by applications engineers.  
Electronic Services  
Bulletin Board Support  
National Instruments has BBS and FTP sites dedicated for 24-hour support with a collection of files  
and documents to answer most common customer questions. From these sites, you can also download  
the latest instrument drivers, updates, and example programs. For recorded instructions on how to use  
the bulletin board and FTP services and for BBS automated information, call 512 795 6990. You can  
access these services at:  
United States: 512 794 5422  
Up to 14,400 baud, 8 data bits, 1 stop bit, no parity  
United Kingdom: 01635 551422  
Up to 9,600 baud, 8 data bits, 1 stop bit, no parity  
France: 01 48 65 15 59  
Up to 9,600 baud, 8 data bits, 1 stop bit, no parity  
FTP Support  
To access our FTP site, log on to our Internet host, ftp.natinst.com, as anonymousand use  
your Internet address, such as [email protected], as your password. The support files and  
documents are located in the /supportdirectories.  
© National Instruments Corporation  
B-1  
NI-IMAQ User Manual  
 
     
Fax-on-Demand Support  
Fax-on-Demand is a 24-hour information retrieval system containing a library of documents on a wide  
range of technical information. You can access Fax-on-Demand from a touch-tone telephone at  
512 418 1111.  
E-Mail Support (Currently USA Only)  
You can submit technical support questions to the applications engineering team through e-mail at the  
Internet address listed below. Remember to include your name, address, and phone number so we can  
contact you with solutions and suggestions.  
Telephone and Fax Support  
National Instruments has branch offices all over the world. Use the list below to find the technical  
support number for your country. If there is no National Instruments office in your country, contact  
the source from which you purchased your software to obtain support.  
Country  
Telephone  
Fax  
Australia  
Austria  
Belgium  
Brazil  
Canada (Ontario)  
Canada (Québec)  
Denmark  
Finland  
03 9879 5166  
0662 45 79 90 0  
02 757 00 20  
011 288 3336  
905 785 0085  
514 694 8521  
45 76 26 00  
09 725 725 11  
01 48 14 24 24  
089 741 31 30  
2645 3186  
03 6120092  
02 413091  
03 5472 2970  
02 596 7456  
5 520 2635  
03 9879 6277  
0662 45 79 90 19  
02 757 03 11  
011 288 8528  
905 785 0086  
514 694 4399  
45 76 26 02  
09 725 725 55  
01 48 14 24 14  
089 714 60 35  
2686 8505  
France  
Germany  
Hong Kong  
Israel  
Italy  
Japan  
03 6120095  
02 41309215  
03 5472 2977  
02 596 7455  
5 520 3282  
Korea  
Mexico  
Netherlands  
Norway  
Singapore  
Spain  
Sweden  
Switzerland  
Taiwan  
0348 433466  
32 84 84 00  
2265886  
91 640 0085  
08 730 49 70  
056 200 51 51  
02 377 1200  
01635 523545  
512 795 8248  
0348 430673  
32 84 86 00  
2265887  
91 640 0533  
08 730 43 70  
056 200 51 55  
02 737 4644  
01635 523154  
512 794 5678  
United Kingdom  
United States  
NI-IMAQ User Manual  
B-2  
© National Instruments Corporation  
 
Technical Support Form  
Photocopy this form and update it each time you make changes to your software or hardware, and use  
the completed copy of this form as a reference for your current configuration. Completing this form  
accurately before contacting National Instruments for technical support helps our applications  
engineers answer your questions more efficiently.  
If you are using any National Instruments hardware or software products related to this problem,  
include the configuration forms from their user manuals. Include additional pages if necessary.  
Name __________________________________________________________________________  
Company _______________________________________________________________________  
Address ________________________________________________________________________  
_______________________________________________________________________________  
Fax ( ___ ) ________________Phone ( ___ ) __________________________________________  
Computer brand____________ Model ___________________Processor_____________________  
Operating system (include version number) ____________________________________________  
Clock speed ______MHz RAM _____MB  
Display adapter __________________________  
Mouse ___yes ___no Other adapters installed_______________________________________  
Hard disk capacity _____MB Brand_________________________________________________  
Instruments used _________________________________________________________________  
_______________________________________________________________________________  
National Instruments hardware product model _____________ Revision ____________________  
Configuration ___________________________________________________________________  
National Instruments software product ___________________ Version _____________________  
Configuration ___________________________________________________________________  
The problem is: __________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
List any error messages: ___________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
The following steps reproduce the problem: ___________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
 
NI-IMAQ Hardware and Software Configuration Form  
Record the settings and revisions of your hardware and software on the line to the right of each item.  
Complete a new copy of this form each time you revise your software or hardware configuration, and  
use this form as a reference for your current configuration. Completing this form accurately before  
contacting National Instruments for technical support helps our applications engineers answer your  
questions more efficiently.  
National Instruments Products  
IMAQ hardware _________________________________________________________________  
Interrupt level of hardware _________________________________________________________  
Address of hardware ______________________________________________________________  
Programming choice _____________________________________________________________  
NI-IMAQ, IMAQ Vision, LabVIEW, BridgeVIEW, or ComponentWorks version _____________  
Other boards in system ____________________________________________________________  
Base I/O address of other boards ____________________________________________________  
DMA channels of other boards _____________________________________________________  
Interrupt level of other boards ______________________________________________________  
Other Products  
Computer make and model ________________________________________________________  
Microprocessor __________________________________________________________________  
Clock frequency or speed __________________________________________________________  
PCI chipset _____________________________________________________________________  
Type of video board installed _______________________________________________________  
Operating system version __________________________________________________________  
Operating system mode ___________________________________________________________  
Programming language ___________________________________________________________  
Programming language version _____________________________________________________  
Other boards in system ____________________________________________________________  
Base I/O address of other boards ____________________________________________________  
DMA channels of other boards _____________________________________________________  
Interrupt level of other boards ______________________________________________________  
 
Documentation Comment Form  
National Instruments encourages you to comment on the documentation supplied with our products.  
This information helps us provide quality products to meet your needs.  
Title:  
NI-IMAQ User Manual  
Edition Date: June 1998  
Part Number: 371443A-01  
Please comment on the completeness, clarity, and organization of the manual.  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
If you find errors in the manual, please record the page numbers and describe the errors.  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
_______________________________________________________________________________  
Thank you for your help.  
Name _________________________________________________________________________  
Title __________________________________________________________________________  
Company _______________________________________________________________________  
Address ________________________________________________________________________  
_______________________________________________________________________________  
E-Mail Address __________________________________________________________________  
Phone ( ___ ) __________________________ Fax ( ___ ) _______________________________  
Mail to: Technical Publications  
National Instruments Corporation  
Fax to: Technical Publications  
National Instruments Corporation  
512 794 5678  
6504 Bridge Point Parkway  
Austin, Texas 78730-5039  
 
Glossary  
Prefix  
p-  
Meanings  
pico  
Value  
10–12  
10–9  
10– 6  
10–3  
103  
n-  
nano-  
micro-  
milli-  
kilo-  
µ-  
m-  
k-  
M-  
G-  
mega-  
giga-  
106  
109  
Numbers/Symbols  
+5V  
5 V signal  
negative of, or minus  
ohm  
/
per  
%
±
percent  
plus or minus  
positive of, or plus  
+
A
A
amperes  
AC  
alternating current  
acquisition window  
the image size specific to a video standard or camera resolution  
© National Instruments Corporation  
G-1  
NI-IMAQ User Manual  
 
   
Glossary  
active line region  
active pixel region  
the region of lines actively being stored; defined by a line start (relative to  
VSYNC) and a line count  
the region of pixels actively being stored; defined by a pixel start (relative  
to HSYNC) and a pixel count  
A/D  
analog-to-digital  
ADC  
analog-to-digital converter—an electronic device, often an integrated  
circuit, that converts an analog voltage to a digital number  
address  
character code that identifies a specific location (or series of locations)  
in memory  
ANSI  
American National Standards Institute  
antichrominance filter  
API  
removes the color information from the video signal  
application programming interface  
AQ_DONE  
AQ_IN_PROGRESS  
area  
signals that the acquisition of a frame or field is completed  
signals that the acquisition of video data is in progress  
a rectangular portion of an acquisition window or frame that is controlled  
and defined by software  
array  
ordered, indexed set of data elements of the same type  
ASIC  
Application-Specific Integrated Circuit—a proprietary semiconductor  
component designed and manufactured to perform a set of specific  
functions for a specific customer  
aspect ratio  
the ratio of a picture or image’s width to its height  
B
b
bit—one binary digit, either 0 or 1  
B
byte—eight related bits of data, an eight-bit binary number; also used to  
denote the amount of memory required to store one byte of data  
back porch  
the area of the video signal between the rising edge of the horizontal sync  
signal and the active video information  
NI-IMAQ User Manual  
G-2  
© National Instruments Corporation  
 
Glossary  
black reference level  
the level that represents the darkest an image can get. See also white  
reference level.  
buffer  
bus  
temporary storage for acquired data  
the group of conductors that interconnect individual circuitry in a  
computer, such as the PCI bus; typically the expansion vehicle to  
which I/O or other devices are connected  
C
C
Celsius  
cache  
high-speed processor memory that buffers commonly used instructions or  
data to increase processing throughput  
CCIR  
Comite Consultatif International des Radiocommunications—a committee  
that developed standards for color video signals  
chrominance  
CMOS  
the color information in a video signal  
complementary metal-oxide semiconductor  
compiler  
a software utility that converts a source program in a high-level  
programming language, such as Basic, C or Pascal, into an object or  
compiled program in machine language. Compiled programs run 10 to  
1,000 times faster than interpreted programs. See also Interpreter.  
conversion device  
device that transforms a signal from one form to another; for  
example, analog-to-digital converters (ADCs) for analog input  
and digital-to-analog converters (DACs) for analog output  
CPU  
central processing unit  
CSYNC  
composite sync signal; a combination of the horizontal and vertical  
sync pulses  
CSYNCIN  
composite sync in signal  
composite sync out signal  
CSYNCOUT  
© National Instruments Corporation  
G-3  
NI-IMAQ User Manual  
 
Glossary  
D
D/A  
digital-to-analog  
DAC  
digital-to-analog converter; an electronic device, often an integrated circuit,  
that converts a digital number into a corresponding analog voltage or  
current  
DAQ  
data acquisition—(1) collecting and measuring electrical signals from  
sensors, transducers, and test probes or fixtures and inputting them to  
a computer for processing; (2) collecting and measuring the same kinds of  
electrical signals with A/D or DIO boards plugged into a computer, and  
possibly generating control signals with D/A and/or DIO boards in the  
same computer  
dB  
decibel—the unit for expressing a logarithmic measure of the ratio of two  
signal levels: dB = 20log10 V1/V2, for signals in volts  
DC  
direct current  
default setting  
a default parameter value recorded in the driver; in many cases, the default  
input of a control is a certain value (often 0) that means use the current  
default setting  
DIN  
DLL  
Deutsche Industrie Norme  
dynamic link library—a software module in Microsoft Windows  
containing executable code and data that can be called or used by Windows  
applications or other DLLs; functions and data in a DLL are loaded and  
linked at run time when they are referenced by a Windows application or  
other DLLs  
DMA  
direct memory access—a method by which data can be transferred to and  
from computer memory from and to a device or memory on the bus while  
the processor does something else; DMA is the fastest method of  
transferring data to/from computer memory  
DRAM  
drivers  
dynamic RAM  
software that controls a specific hardware device such as an IMAQ or  
DAQ device  
NI-IMAQ User Manual  
G-4  
© National Instruments Corporation  
 
Glossary  
dynamic range  
the ratio of the largest signal level a circuit can handle to the smallest signal  
level it can handle (usually taken to be the noise level), normally expressed  
in decibels  
E
EEPROM  
electrically erasable programmable read-only memory—ROM that can be  
erased with an electrical signal and reprogrammed  
external trigger  
a voltage pulse from an external source that triggers an event such as A/D  
conversion  
F
field  
For an interlaced video signal, a field is half the number of horizontal lines  
needed to represent a frame of video; the first field of a frame contains all  
the odd-numbered lines, the second field contains all of the even-numbered  
lines.  
FIFO  
first-in first-out memory buffer—the first data stored is the first data sent to  
the acceptor; FIFOs are used on IMAQ devices to temporarily store  
incoming data until that data can be retrieved. For example, an analog input  
FIFO stores the results of A/D conversions until the data can be retrieved  
into system memory, a process that requires the servicing of interrupts and  
often the programming of the DMA controller. This process can take  
several milliseconds in some cases. During this time, data accumulates in  
the FIFO for future retrieval.  
flash ADC  
an ADC whose output code is determined in a single step by a bank of  
comparators and encoding logic  
frame  
a complete image; in interlaced formats, a frame is composed of two fields  
front porch  
the area of a video signal between the start of the horizontal blank and the  
start of the horizontal sync  
ft  
feet  
© National Instruments Corporation  
G-5  
NI-IMAQ User Manual  
 
Glossary  
function  
a set of software instructions executed by a single line of code that may  
have input and/or output parameters and returns a value when executed;  
examples of functions are:  
y = COS (x)  
status = AO_config(board, channel, range)  
G
gamma  
the nonlinear change in the difference between the video signal’s brightness  
level and the voltage level needed to produce that brightness  
genlock  
circuitry that aligns the video timing signals by locking together the  
horizontal, vertical, and color subcarrier frequencies and phases and  
generates a pixel clock to clock pixel data into memory for display or into  
another circuit for processing  
GND  
GUI  
ground signal  
graphical user interface—an intuitive, easy-to-use means of  
communicating information to and from a computer program by means of  
graphical screen displays; GUIs can resemble the front panels of  
instruments or other objects associated with a computer program.  
H
h
hour  
hardware  
the physical components of a computer system, such as the circuit boards,  
plug-in boards, chassis, enclosures, peripherals, cables, and so on  
HSYNC  
horizontal sync signal—the synchronization pulse signal produced at the  
beginning of each video scan line that keeps a video monitor's horizontal  
scan rate in step with the transmission of each new line  
HSYNCIN  
hue  
horizontal sync input signal  
represents the dominant color of a pixel. The hue function is a continuous  
function that covers all the possible colors generated using the R, G, and B  
primaries. See also RGB.  
Hz  
hertz—the number of scans read or updates written per second  
NI-IMAQ User Manual  
G-6  
© National Instruments Corporation  
 
Glossary  
I
IC  
integrated circuit  
ID  
identification  
IEEE  
in.  
Institute of Electrical and Electronics Engineers  
inches  
INL  
integral nonlinearity—A measure in LSB of the worst-case deviation from  
the ideal A/D or D/A transfer characteristic of the analog I/O circuitry  
instrument driver  
a set of high-level software functions, such as NI-IMAQ, that controls  
specific plug-in computer boards; instrument drivers are available in  
several forms, ranging from a function callable from a programming  
language to a virtual instrument (VI) in LabVIEW  
interlaced  
interpreter  
a video frame composed of two interleaved fields; the number of lines in a  
field are half the number of lines in an interlaced frame  
a software utility that executes source code from a high-level language such  
as Basic, C or Pascal, by reading one line at a time and executing the  
specified operation. See also compiler.  
interrupt  
a computer signal indicating that the CPU should suspend its current task  
to service a designated activity  
interrupt level  
I/O  
the relative priority at which a device can interrupt  
input/output—the transfer of data to/from a computer system involving  
communications channels, operator interface devices, and/or data  
acquisition and control interfaces  
IRE  
IRQ  
a relative unit of measure (named for the Institute of Radio Engineers).  
0 IRE corresponds to the blanking level of a video signal, 100 IRE to the  
white level. Note that for CIR/PAL video the black level is equal to the  
blanking level or 0 IRE, while for RS-170/NTSC video the black level is  
at 7.5 IRE.  
interrupt request  
© National Instruments Corporation  
G-7  
NI-IMAQ User Manual  
 
Glossary  
K
k
kilo—the standard metric prefix for 1,000, or 103, used with units of  
measure such as volts, hertz, and meters  
K
kilo—the prefix for 1,024, or 210, used with B in quantifying data or  
computer memory  
kbytes/s  
Kword  
a unit for data transfer that means 1,000 or 103 bytes/s  
1,024 words of memory  
L
library  
a file containing compiled object modules, each comprised of one of more  
functions, that can be linked to other object modules that make use of these  
functions.  
line count  
LSB  
the total number of horizontal lines in the picture  
least significant bit  
luminance  
the brightness information in the video picture. The luminance signal  
amplitude varies in proportion to the brightness of the video signal and  
corresponds exactly to the monochrome picture.  
LUT  
look-up table—a selection in the IMAQ Configuration Utility that contains  
formulas that let you implement simple imaging operations such as contrast  
enhancement, data inversion, gamma manipulation, or other nonlinear  
transfer functions  
M
m
meters  
M
(1) Mega, the standard metric prefix for 1 million or 106, when used with  
units of measure such as volts and hertz; (2) mega, the prefix for 1,048,576,  
or 220, when used with B to quantify data or computer memory  
MB  
megabytes of memory  
Mbytes/s  
a unit for data transfer that means 1 million or 106 bytes/s  
NI-IMAQ User Manual  
G-8  
© National Instruments Corporation  
 
Glossary  
memory buffer  
See buffer.  
memory window  
continuous blocks of memory that can be accessed quickly by changing  
addresses on the local processor  
MSB  
MTBF  
mux  
most significant bit  
mean time between failure  
multiplexer—a switching device with multiple inputs that selectively  
connects one of its inputs to its output  
N
NI-IMAQ  
driver software for National Instruments IMAQ hardware  
noninterlaced  
a video frame where all the lines are scanned sequentially, instead of  
divided into two frames as in an interlaced video frame  
NTSC  
National Television Standards Committee—the committee that developed  
the color video standard used primarily in North America, which uses  
525 lines per frame. See also PAL.  
NVRAM  
nonvolatile RAM—RAM that is not erased when a device loses power or is  
turned off  
O
operating system  
base-level software that controls a computer, runs programs, interacts with  
users, and communicates with installed hardware or peripheral devices  
P
PAL  
Phase Alternation Line—one of the European video color standards; uses  
625 lines per frame. See also NTSC.  
PCI  
Peripheral Component Interconnect—a high-performance expansion bus  
architecture originally developed by Intel to replace ISA and EISA; it is  
achieving widespread acceptance as a standard for PCs and workstations  
and offers a theoretical maximum transfer rate of 132 Mbytes/s  
PCLK  
pixel clock signal—times the sampling of pixels on a video line  
© National Instruments Corporation  
G-9  
NI-IMAQ User Manual  
 
Glossary  
PCLKIN  
PFI  
pixel clock in signal  
programmable function input  
programmable gain instrumentation amplifier  
PGIA  
picture aspect ratio  
the ratio of the active pixel region to the active line region; for standard  
video signals like RS-170 or CCIR, the full-size picture aspect ratio  
normally is 4/3 (1.33)  
pixel  
picture element—the smallest division that makes up the video scan line;  
for display on a computer monitor, a pixel’s optimum dimension is square  
(aspect ratio of 1:1, or the width equal to the height)  
pixel aspect ratio  
the ratio between the physical horizontal size and the vertical size of the  
region covered by the pixel; an acquired pixel should optimally be square,  
thus the optimal value is 1.0, but typically it falls between 0.95 and 1.05,  
depending on camera quality  
pixel clock  
pixel count  
divides the incoming horizontal video line into pixels  
the total number of pixels between two HYSNCs; the pixel count  
determines the frequency of the pixel clock  
PLL  
phase-locked loop—circuitry that provides a very stable pixel clock that is  
referenced to another signal, for example, an incoming HSYNC signal  
protocol  
the exact sequence of bits, characters, and control codes used to transfer  
data between computers and peripherals through a communications  
channel  
pts  
points  
R
RAM  
random-access memory  
real time  
a property of an event or system in which data is processed as it is acquired  
instead of being accumulated and processed at a later time  
relative accuracy  
a measure in LSB of the accuracy of an ADC; it includes all nonlinearity  
and quantization errors but does not include offset and gain errors of the  
circuitry feeding the ADC  
NI-IMAQ User Manual  
G-10  
© National Instruments Corporation  
 
Glossary  
resolution  
RGB  
the smallest signal increment that can be detected by a measurement  
system; resolution can be expressed in bits, in proportions, or in percent of  
full scale. For example, a system has 12-bit resolution, one part in 4,096  
resolution, and 0.0244 percent of full scale.  
red, green, and blue—the three primary colors used to represent a color  
picture. An RGB camera is a camera that deliver three signals, one for each  
primary.  
ribbon cable  
ROI  
a flat cable in which the conductors are side by side  
region-of-interest— a hardware-programmable rectangular portion of the  
acquisition window  
ROM  
read-only memory  
RS-170  
RTSI bus  
the U.S. standard used for black-and-white television  
Real-Time System Integration Bus—the National Instruments timing bus  
that connects IMAQ and DAQ boards directly, by means of connectors on  
top of the boards, for precise synchronization of functions  
S
s
seconds  
saturation  
the richness of a color. A saturation of zero corresponds to no color, that is,  
a gray pixel. Pink is a red with low saturation.  
scaling down circuitry  
scatter-gather DMA  
SRAM  
circuitry that scales down the resolution of a video signal  
a type of DMA that allows the DMA controller to reconfigure on-the-fly  
static RAM  
StillColor  
a post-processing algorithm that allows the acquisition of high-quality  
color images generated either by an RGB or composite (NTSC or PAL)  
camera using a monochrome video acquisition board.  
sync  
tells the display where to put a video picture; the horizontal sync indicates  
the picture’s left-to-right placement and the vertical sync indicates  
top-to-bottom placement  
© National Instruments Corporation  
G-11  
NI-IMAQ User Manual  
 
Glossary  
syntax  
the set of rules to which statements must conform in a particular  
programming language  
system RAM  
RAM installed on a personal computer and used by the operating system,  
as contrasted with onboard RAM  
T
transfer rate  
the rate, measured in bytes/s, at which data is moved from source to  
destination after software initialization and set up operations; the maximum  
rate at which the hardware can operate  
TRIG  
trigger signal  
trigger  
any event that causes or starts some form of data capture  
trigger control and  
mapping circuitry  
circuitry that routes, monitors, and drives the external and RTSI bus trigger  
lines; you can configure each of these lines to start or stop acquisition on a  
rising or falling edge.  
TTL  
transistor-transistor logic  
U
UV plane  
See YUV.  
V
V
volts  
VCO  
voltage-controlled oscillator—an oscillator that changes frequency  
depending on a control signal; used in a PLL to generate a stable pixel clock  
VI  
Virtual Instrument—(1) a combination of hardware and/or software  
elements, typically used with a PC, that has the functionality of a classic  
stand-alone instrument (2) a LabVIEW software module (VI), which  
consists of a front panel user interface and a block diagram program  
video line  
a video line consists of a HSYNC, back porch, active pixel region, and a  
front porch  
NI-IMAQ User Manual  
G-12  
© National Instruments Corporation  
 
Glossary  
VSYNC  
vertical sync signal—the synchronization pulse generated at the beginning  
of each video field that tells the video monitor when to start a new field  
VSYNCIN  
vertical sync in signal  
W
white reference level  
the level that defines what is white for a particular video system  
See also black reference level.  
Y
YUV  
a representation of a color image used for the coding of NTSC or PAL video  
signals. The luminance information is called Y, while the chrominance  
information is represented by two components, U and V representing the  
coordinates in a color plane.  
© National Instruments Corporation  
G-13  
NI-IMAQ User Manual  
 
Index  
A
D
acquisition functions, 2-5  
application development, 1-2 to 1-4  
creating applications, 1-3  
NI-IMAQ libraries, 1-2  
documentation  
conventions used in manual, x  
how to use NI-IMAQ manual set, ix  
National Instruments documentation, xi  
organization of manual, ix-x  
attribute functions, 2-6  
related documentation, xi  
dynamic link libraries (DLLs), 1-2  
B
buffer management functions  
list of functions, 2-6 to 2-7  
programming considerations, 3-4  
bulletin board support, B-1  
E
electronic support services, B-1 to B-2  
e-mail support, B-2  
example programs  
advanced programming examples,  
3-14 to 3-17  
C
camera attributes, 3-4 to 3-5  
color, A-6 to A-9. See also StillColor.  
definition, A-6  
low-level grab functions, 3-15  
low-level ring functions, 3-16  
low-level sequence functions,  
3-15 to 3-16  
hue, A-7  
image representations, A-8 to A-9  
32-bit HSL and HSI, A-9  
color planes, A-8  
low-level snap functions, 3-14 to 3-15  
StillColor snap programming,  
3-16 to 3-17  
introductory programming examples,  
3-6 to 3-14  
hue, saturation, luminance, and  
intensity planes, A-8 to A-9  
RGB, A-8  
high-level grab functions, 3-8 to 3-9  
high-level ring functions, 3-11 to 3-13  
high-level sequence functions,  
3-10 to 3-11  
high-level signal I/O functions,  
3-13 to 3-14  
intensity, A-7  
luminance, A-7  
perception of color, A-7  
saturation, A-7  
white light and visible spectrum  
(figure), A-2  
high-level snap functions, 3-7 to 3-8  
location (note), 3-6  
composite color cameras, A-1  
customer communication, xi, B-1 to B-2  
location of files, 1-4  
© National Instruments Corporation  
I-1  
NI-IMAQ User Manual  
 
   
Index  
F
H
fax and telephone support numbers, B-2  
Fax-on-Demand support, B-2  
files required for application development, 1-3  
FTP support, B-1  
header files, 1-3  
high-level functions, 2-2 to 2-4  
grab functions, 2-2 to 2-3  
introductory programming examples,  
3-6 to 3-14  
functions  
grab functions, 3-8 to 3-9  
ring functions, 3-11 to 3-13  
sequence functions, 3-10 to 3-11  
signal I/O functions, 3-13 to 3-14  
snap functions, 3-7 to 3-8  
miscellaneous functions, 2-4  
programming considerations, 3-1  
ring and sequence functions, 2-3  
signal I/O functions, 2-3 to 2-4  
snap functions, 2-2  
generic functions, 2-2  
high-level functions, 2-2 to 2-4  
grab functions, 2-2 to 2-3  
miscellaneous functions, 2-4  
programming considerations, 3-1  
programming examples, 3-6 to 3-14  
ring and sequence functions, 2-3  
session functions, 2-4, 3-3 to 3-4  
signal I/O functions, 2-3 to 2-4  
snap functions, 2-2  
hue, A-7  
hue planes, A-8 to A-9  
low-level functions, 2-5 to 2-7  
acquisition functions, 2-5  
attribute functions, 2-6  
buffer management functions,  
2-6 to 2-7, 3-4  
interface functions, 2-7, 3-2  
programming considerations, 3-2  
programming examples, 3-14 to 3-17  
utility functions, 2-7  
I
import libraries  
IMAQ.LIB required for application  
development, 1-3  
location (table), 1-3  
purpose and use, 1-2  
overview, 2-1  
intensity, A-7  
intensity planes, A-8 to A-9  
interface functions  
G
interface naming convention (table), 3-2  
list of functions, 2-7  
generic functions, 2-2  
grab acquisition, 3-1  
programming considerations, 3-2 to 3-3  
grab functions  
list of functions, 2-2 to 2-3  
programming examples  
high-level functions, 3-8 to 3-9  
low-level functions, 3-15  
L
low-level functions, 2-5 to 2-7  
acquisition functions, 2-5  
advanced programming examples,  
3-14 to 3-17  
grab functions, 3-15  
ring functions, 3-16  
NI-IMAQ User Manual  
I-2  
© National Instruments Corporation  
 
Index  
sequence functions, 3-15 to 3-16  
snap functions, 3-14 to 3-15  
attribute functions, 2-6  
buffer management, 3-4  
camera attributes, 3-4 to 3-5  
high-level functions, 3-1  
buffer management functions, 2-6 to 2-7,  
3-4  
interface functions, 3-2 to 3-3  
introductory examples, 3-6 to 3-14  
interface functions, 2-7, 3-2 to 3-3  
programming considerations, 3-2  
utility functions, 2-7  
high-level grab functions, 3-8 to 3-9  
high-level ring functions,  
3-11 to 3-13  
luminance, A-7  
luminance planes, A-8 to A-9  
high-level sequence functions,  
3-10 to 3-11  
high-level signal I/O functions,  
3-13 to 3-14  
high-level snap functions, 3-7 to 3-8  
location (note), 3-6  
M
manual. See documentation.  
miscellaneous high-level functions, 2-4  
low-level functions, 3-2  
session functions, 3-3 to 3-4  
status signals, 3-5 to 3-6  
programming environments supported by  
NI-IMAQ software, 1-2  
N
NI-IMAQ header files, 1-3  
NI-IMAQ libraries, 1-2  
NI-IMAQ software. See also functions.  
application development, 1-2 to 1-4  
application development  
environments, 1-2  
R
RGB cameras, A-1  
RGB image representations, A-8  
ring functions. See also sequence functions.  
list of functions, 2-3  
features and overview, 1-1  
NI-IMAQ libraries, 1-2  
sample programs, 1-4  
programming example  
_NIWIN constant, 1-3  
high-level functions, 3-11 to 3-13  
low-level functions, 3-16  
P
S
programming  
advanced examples, 3-14 to 3-17  
low-level grab functions, 3-15  
low-level ring functions, 3-16  
low-level sequence functions,  
3-15 to 3-16  
sample programs. See example programs.  
saturation, A-7  
saturation planes, A-8 to A-9  
sequence acquisition, 3-1  
sequence functions. See also ring functions.  
list of functions, 2-3  
low-level snap functions, 3-14 to  
3-15  
programming example  
StillColor snap programming,  
3-16 to 3-17  
high-level functions, 3-10 to 3-11  
low-level functions, 3-15 to 3-16  
© National Instruments Corporation  
I-3  
NI-IMAQ User Manual  
 
Index  
session functions  
T
list of functions, 2-4  
technical support, B-1 to B-2  
telephone and fax support numbers, B-2  
programming considerations, 3-3 to 3-4  
signal I/O functions  
list of functions, 2-3 to 2-4  
programming example, 3-13 to 3-14  
snap acquisition, 3-1  
U
utility functions, 2-7  
snap functions  
list of functions, 2-2  
V
programming example  
high-level functions, 3-7 to 3-8  
low-level functions, 3-14 to 3-15  
status signals, 3-5 to 3-6  
video cameras for color acquisition, A-1  
visible spectrum, A-6 to A-7  
StillColor, A-1 to A-6  
W
advantages, A-5  
white light, A-7  
composite color acquisition, A-5  
composite color video signals, A-2 to A-4  
overview, A-1  
purpose and use, A-2  
RGB color acquisition, A-6  
snap programming example, 3-16 to 3-17  
traditional color decoding, A-2 to A-3  
NI-IMAQ User Manual  
I-4  
© National Instruments Corporation  
 

Minolta Universal Remote SRU 3040 10 User Manual
MPC Clock OM 20000072 User Manual
MTD Snow Blower 310 200 User Manual
NeumannBerlin Microphone KM 84 User Manual
Nikon Digital Camera 1797 User Manual
NordicTrack Treadmill NTL119090 User Manual
NuTone Door LA107WH User Manual
Omega Thermometer 24 User Manual
OWI Portable Speaker AMPMOVC User Manual
Panasonic Switch KX T61610 User Manual