IMAQ ™ NI-IMAQ™ for IEEE-1394 Cameras User Manual Image Acquisition Software NI-IMAQ for IEEE-1394 Cameras User Manual March 2001 Edition Part Number 370362A-01
Worldwide Technical Support and Product Information ni.
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.
Conventions The following conventions are used in this manual: » The » symbol leads you through nested menu items and dialog box options to a final action. The sequence File»Page Setup»Options directs you to pull down the File menu, select the Page Setup item, and select Options from the last dialog box. This icon denotes a note, which alerts you to important information. bold Bold text denotes items that you must select or click on in the software, such as menu items and dialog box options.
Contents Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras About the NI-IMAQ Software .......................................................................................1-1 Application Development Environments ........................................................1-2 Configuring Your IEEE-1394 Camera............................................................1-2 Fundamentals of Building Applications with NI-IMAQ for 1394 ................................1-3 Architecture ..........................
Contents Introductory Programming Examples ........................................................................... 3-5 High-Level Snap Functions ............................................................................ 3-5 High-Level Grab Functions ............................................................................ 3-6 High-Level Sequence Functions ..................................................................... 3-8 Advanced Programming Examples ........................................
Introduction to NI-IMAQ for IEEE-1394 Cameras 1 This chapter describes the NI-IMAQ for IEEE-1394 software and lists the application development environments compatible with NI-IMAQ, describes the fundamentals of creating NI-IMAQ applications for Windows 2000 and Windows Me/98, describes the files used to build these applications, and tells you where to find sample programs.
Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras Application Development Environments This release of NI-IMAQ for 1394 supports the following Application Development Environments (ADEs) for Windows 2000 and Windows Me/98: • LabVIEW version 5.1 and higher • LabWindows/CVI version 5.0 and higher • Borland C++ Builder 3.0 and higher • Microsoft Visual C/C++ version 6.0 and higher Although NI-IMAQ for 1394 has been tested and found to work with these ADEs, other ADEs may also work.
Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras Fundamentals of Building Applications with NI-IMAQ for 1394 Architecture A block diagram of the NI-IMAQ for 1394 architecture shown in Figure 1-1 illustrates the low- and mid-level architecture for IMAQ devices. LabWindows/CVI Visual C++/Borland LabVIEW IMAQ Vision IMAQ Vision IMAQ1394.DLL Application Level Kernel IMAQ1394.SYS 1394BUS.SYS OCHI1394.SYS TILYNX.SYS Figure 1-1.
Chapter 1 Introduction to NI-IMAQ for IEEE-1394 Cameras The NI-IMAQ Libraries The NI-IMAQ for 1394 for Windows 2000/Me/98 function libraries are dynamic link libraries (DLLs), which means that NI-IMAQ for 1394 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.
Chapter 1 • Introduction to NI-IMAQ for IEEE-1394 Cameras When compiling, indicate where the compiler can find the NI-IMAQ header files and shared libraries. You can find most of the files you need for development 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 for IEEE-1394. You can find the include files under the include subdirectory.
2 Software Overview This chapter describes the classes of NI-IMAQ for 1394 functions and briefly describes each function.
Chapter 2 Software Overview 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 capture all or a portion of a single frame or field to the user buffer. imaq1394SnapImage Performs a single frame acquisition in an image buffer, which is allocated using IMAQ Vision memory management.
Chapter 2 Software Overview Sequence Functions Sequence functions start and stop a continuous acquisition of multiple frames. imaq1394SetupSequenceImage Configures and starts a session for acquiring a full sequence into the list of buffers managed by IMAQ Vision. imaq1394SetupSequence Configures and starts a session for acquiring a full sequence in the buffer list. Trigger Functions Trigger functions control the trigger mode of the IEEE-1394 camera.
Chapter 2 Software Overview imaq1394StopAcquisition Stops an asynchronous acquisition or synchronous continuous acquisition immediately. imaq1394GetBuffer Copies a frame buffer to a user-specified buffer. imaq1394GetImage Copies a session’s image data to an IMAQ Vision image. imaq1394InstallCallback Configures an asynchronous acquisition and installs a callback function that will be called when an image is acquired.
Chapter 2 Software Overview Utility Functions Use utility functions to display an image in a window, save an image to a file, or to get detailed error information. imaq1394Plot Plots a buffer to a window given a handle to a window. imaq1394PlotDC Plots a buffer to a window given a handle to a device context. imaq1394SaveBuffer Saves a buffer of a session to disk in bitmap, TIFF, or PNG format. imaq1394ShowError Returns a null-terminated string describing the error code.
3 Programming with NI-IMAQ for 1394 This chapter contains an overview of the NI-IMAQ for 1394 library, a description of the programming flow of NI-IMAQ for 1394, and programming examples. Flowcharts are included for the following operations: snap, grab, and sequence. Introduction The NI-IMAQ for 1394 application programming interface (API) is divided into two groups—high-level functions and low-level functions.
Chapter 3 Programming with NI-IMAQ for 1394 Low-Level Functions The low-level function set supports all types of acquisition. You can use low-level functions to start a synchronous or asynchronous acquisition. Establishing Interface Connections To acquire images using the high-level or low-level functions, you must first learn how to establish a connection to a camera.
Chapter 3 Programming with NI-IMAQ for 1394 Before you can acquire image data successfully, you must open a camera with the imaq1394CameraOpen function. imaq1394CameraOpen requires a camera name and returns a handle to this interface. NI-IMAQ for 1394 then uses this handle to reference this camera when using other NI-IMAQ functions.
Chapter 3 Programming with NI-IMAQ for 1394 Scalable Image Size IEEE-1394 digital cameras support a predefined set of image sizes which you can select through the Format and Mode attributes in MAX. See your camera documentation for a list of supported formats. If you are using IMAQ Vision, the NI-IMAQ for 1394 software recognizes the predefined formats and automatically allocates enough memory to accommodate the image in IMAQ Vision.
Chapter 3 Programming with NI-IMAQ for 1394 Introductory Programming Examples This section introduces some examples for performing the different types of image acquisition. The error codes returned by NI-IMAQ are not included in the examples. Always check the return code for errors in your program. Note If you have IMAQ Vision installed on your computer, you can take advantage of the additional Image functions installed with NI-IMAQ for 1394.
Chapter 3 Programming with NI-IMAQ for 1394 When you invoke a snap, it initializes the IMAQ 1394 device and acquires the next incoming video frame to a buffer. Use a snap for low-speed or single-capture applications where ease of programming is essential. Figure 3-2 illustrates a typical snap programming order. imaq1394CameraOpen opens imaq1394CameraOpen imaq1394Snap and configures the camera according to the file set up by Measurement & Automation Explorer.
Chapter 3 Programming with NI-IMAQ for 1394 Calling imaq1394SetupGrab initializes a session for a grab acquisition. After imaq1394SetupGrab, each successive grab copies the last acquired buffer into a user buffer where you can perform processing on the image. Use grab 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.
Chapter 3 Programming with NI-IMAQ for 1394 High-Level Sequence Functions Sequence functions include imaq1394SetupSequence. A sequence initiates a variable-length and variable-delay transfer to multiple buffers. You can configure the delay between acquisitions with imaq1394SetupSequence and specify both the buffer list used for transfers and the number of buffers. imaq1394SetupSequence is synchronous and returns when all images have been acquired.
Chapter 3 Programming with NI-IMAQ for 1394 Advanced Programming Examples Use low-level functions or combine high-and low-level functions for more advanced programming techniques, including snap, grab, and sequence. Performing a Snap Using Low-Level Functions The LowLevelSnap1394.c example demonstrates how to perform a snap acquisition using low-level calls. The example sets up a single-frame acquisition to a user-allocated buffer. The program retrieves the acquisition window size of the selected camera.
Chapter 3 Programming with NI-IMAQ for 1394 Performing an Asynchronous Snap Using Low-Level Functions The Low-Level Snap1394 Async example demonstrates how to perform an asynchronous acquisition using low-level calls. The example sets up a single-frame acquisition to a buffer. In an asynchronous snap, the program installs a callback function using the imaq1394InstallCallback function and starts the acquisition with the imaq1394StartAcquisition function.
4 Programming with NI-IMAQ for 1394 VIs This chapter describes how to use the NI-IMAQ 1394 VIs in LabVIEW. Introduction The NI-IMAQ for IEEE-1394 Cameras VI Library, a series of virtual instruments (VIs) for using LabVIEW with your IMAQ 1394 device, is included with your NI-IMAQ for 1394 software. IMAQ Vision for LabVIEW is an image processing and analysis library that consists of more than 250 VIs.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Location of NI-IMAQ for 1394 Examples The NI-IMAQ VI for IEEE-1394 Cameras examples illustrate some common applications. You can find these examples in the labview\examples\imaq directory for LabVIEW. For a brief description of any example, open the example VI and choose Windows»Show VI Info for a text description of the example. Location of the NI-IMAQ for 1394 VIs You can find the NI-IMAQ VIs in the Functions palette from your LabVIEW block diagram.
Chapter 4 Programming with NI-IMAQ for 1394 VIs The most commonly used VIs are on the IMAQ for IEEE-1394 palette. You can find VIs for basic acquisition and changing attributes. The Motion and Vision»IMAQ for IEEE-1394»IMAQ Low Level palette contains VIs for more advanced applications. See the NI-IMAQ for IEEE-1394 VI Reference help for more information. Common NI-IMAQ for 1394 VI Parameters IMAQ1394 Session is a unique identifier that specifies the Interface file used for the acquisition.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Buffer Management IMAQ Create and IMAQ Dispose manage image buffers in LabVIEW. IMAQ Create, shown in Figure 4-2, allocates an image buffer. Image Name is a label for the buffer created. Each buffer must have a unique name. Image Type specifies the type of image being created. Use 8 bits for 8-bit monochrome images and 16 bits for 16-bit monochrome images, RGB for RGB color images.
Chapter 4 Programming with NI-IMAQ for 1394 VIs NI-IMAQ for 1394 Acquisition Types Three NI-IMAQ image acquisition types are available in LabVIEW—snap, grab, and sequence. The following sections describe each acquisition type and give examples. Snap A snap acquires a single image into a memory buffer. Use this acquisition mode to acquire a single frame or field to a buffer. When you invoke a snap, it initializes the device and acquires the next incoming video frame to a buffer.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Figure 4-5 shows a simplified block diagram for using IMAQ1394 Grab Setup and IMAQ1394 Grab Acquire. Figure 4-5. Acquiring Images Using Grab Sequence A sequence initiates a variable-length and variable-delay transfer to multiple buffers. Use a sequence for applications that process multiple images. You can configure a sequence to acquire every frame or skip a variable number of frames between each image. Use IMAQ1394 Sequence for sequence applications.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Figure 4-6 shows a simplified block diagram for using IMAQ1394 Sequence. Place IMAQ Create inside a For Loop to create an array of images for the Images in input to IMAQ1394 Sequence. To Decimal and Concatenate create a unique name for each image in the array. Figure 4-6. Acquiring Images Using Sequence Acquisition VIs Two acquisition VI types are available in LabVIEW—high-level and low-level.
Chapter 4 Programming with NI-IMAQ for 1394 VIs 4. Call IMAQ1394 Get Image. 5. After an acquisition, release the resources associated with the acquisition using IMAQ1394 Close. IMAQ1394 Close also stops the acquisition if one is in progress. If you want to stop the acquisition without releasing the resources (such as the image buffers), use IMAQ1394 Stop Acquisition. Examples of the low-level acquisition VIs are included in examples/imaq/IMAQ1394examples.llb.
Chapter 4 Programming with NI-IMAQ for 1394 VIs an image acquired using IMAQ1394 Snap. You can display images in the same way using any acquisition type. For more information on the display capabilities of IMAQ Vision, consult the IMAQ Vision for LabVIEW User Manual. Figure 4-8. Displaying an Image Using IMAQ WindDraw If you do not have IMAQ Vision, you can display an image on a LabVIEW Intensity Graph for 8-bit and 16-bit monochrome images or on a picture control for RGB images.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Your intensity graph now should appear similar to the image shown in Figure 4-9. For more information on the Intensity Graph, consult your LabVIEW documentation Figure 4-9. Intensity Graph for Image Display Use the IMAQ ImageToArray VI to copy an image from an image buffer into a LabVIEW array. Then you can wire this array directly to an Intensity Graph for display.
Chapter 4 Programming with NI-IMAQ for 1394 VIs . Figure 4-11. Using a Picture Control to Display an RGB Image Camera Attributes Camera attributes allow you to control camera-specific features such as brightness and shutter speed directly from NI-IMAQ for 1394. You can also set camera attributes through the feature tab in MAX. All of the configured parameters for a camera are stored in a camera (.icd) file. This file is linked to a specific camera.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Error Handling Every NI-IMAQ for 1394 VI contains an error in input cluster and an error out output cluster, as shown in Figure 4-12. The clusters contain a Boolean value that indicates whether an error occurred, the code for the error, and the source or the name of the VI that returned the error. If error in indicates an error, the VI passes the error information to error out and does not execute any NI-IMAQ for 1394 function. Figure 4-12.
Chapter 4 Programming with NI-IMAQ for 1394 VIs Error Code Format Error format for all NI-IMAQ for 1394 VIs is the same, as follows: error in (no error) is a cluster that describes the error status before this VI executes. If error in indicates that an error occurred before this VI was called, this VI may choose not to execute its function, but just pass the error through to its error out cluster. If no error has occurred, then this VI executes normally and sets its own error status in error out.
Chapter 4 Programming with NI-IMAQ for 1394 VIs code is the number identifying an error or warning. If status is TRUE, code is a non-zero error code. If status is FALSE, code can be zero or a warning code. Use the error handler VIs to look up the meaning of this code and to display the corresponding error message. source is a string that indicates the origin of the error, if any. Usually source is the name of the VI in which the error occurred. NI-IMAQ for IEEE-1394 Cameras User Manual 4-14 ni.
Technical Support Resources A Web Support National Instruments Web support is your first stop for help in solving installation, configuration, and application problems and questions. Online problem-solving and diagnostic resources include frequently asked questions, knowledge bases, product-specific troubleshooting wizards, manuals, drivers, software updates, and more. Web support is available through the Technical Support section of ni.com NI Developer Zone The NI Developer Zone at ni.
Appendix A Technical Support Resources Worldwide Support National Instruments has offices located around the world to help address your support needs. You can access our branch office Web sites from the Worldwide Offices section of ni.com. Branch office Web sites provide up-to-date contact information, support phone numbers, e-mail addresses, and current events.
Glossary A acquisition window The image size specific to a video standard or camera resolution. active pixel region The region of pixels actively being stored. Defined by a pixel start [relative to the horizontal synchronization signal(HSYNC)] and a pixel count. address Value that identifies a specific location (or series of locations) in memory. API Application programming interface. AQ_DONE Signals that the acquisition of a frame or field is completed.
Glossary chrominance See chroma. 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.
Glossary driver Software that controls a specific hardware device, such as an IMAQ or DAQ device. E 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. frame A complete image.
Glossary I I/O Input/output. The transfer of data to/from a computer system involving communications channels, operator interface devices, and/or data acquisition and control interfaces. IEEE Institute of Electrical and Electronics Engineers. instrument driver A set of high-level software functions, such as NI-IMAQ, that control specific plug-in computer boards.
Glossary luma The brightness information in the video picture. The luma signal amplitude varies in proportion to the brightness of the video signal and corresponds exactly to the monochrome picture. luminance See luma. LUT Lookup table. Table containing values used to transform the gray-level values of an image. For each gray-level value in the image, the corresponding new value is obtained from the lookup table.
Glossary O operating system Base-level software that controls a computer, runs programs, interacts with users, and communicates with installed hardware or peripheral devices. P PCI Peripheral Component Interconnect. A high-performance expansion bus architecture originally developed by Intel to replace ISA and EISA. PCI offers a theoretical maximum transfer rate of 132 Mbytes/s. picture aspect ratio The ratio of the active pixel region to the active line region.
Glossary resolution (1) The number of rows and columns of pixels. An image composed of m rows and n columns has a resolution of m × n. This image has n pixels along its horizontal axis and m pixels along its vertical axis. (2) The smallest signal increment that can be detected by a measurement system. Resolution can be expressed in bits, proportions, or a percentage of full scale. For example, a system has 12-bit resolution, one part in 4,096 resolution, and 0.0244 percent of full scale.
Glossary V V Volts. 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. Y YUV A representation of a color image used for the coding of NTSC or PAL video signals.
Index A examples advanced programming examples, 3-9 to 3-10 introductory programming examples, 3-5 to 3-8 acquisition functions, 2-3 advanced programming examples, 3-9 to 3-10 asynchronous grab using low-level functions, 3-10 asynchronous snap using low-level functions, 3-10 grab using low-level functions, 3-9 sequence acquisition using low-level functions, 3-9 snap using low-level functions, 3-9 application development, 1-3 creating an application, 1-4 NI-IMAQ libraries, 1-4 attribute functions, 2-4 F f
Index L S low-level functions acquisition functions, 2-3 attribute functions, 2-4 utility functions, 2-5 scalable image size, 3-4 sequence functions, 2-3 snap functions, 2-2 system integration, by National Instruments, B-1 M T miscellaneous functions, 2-3 technical support resources, B-1 trigger functions, 2-3 triggering, 4-8 N National Instruments Web support, B-1 NI Developer Zone, B-1 NI-IMAQ for 1394 acquisition types, 4-5 grab, 4-5 sequence, 4-6 snap, 4-5 acquisition VIs, 4-7 high level VIs, 4