NI-IMAQdx NI-IMAQdx User Manual Image Acquisition Software NI-IMAQdx User Manual February 2007 371970B-01 TM
Support 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 tip, which alerts you to advisory information. This icon denotes a note, which alerts you to important information.
Contents Chapter 1 Introduction to NI-IMAQdx About the NI-IMAQdx Software ...................................................................................1-1 Application Development Environments ........................................................1-2 Configuring Your Camera...............................................................................1-2 Fundamentals of Building Applications with NI-IMAQdx ...........................................1-3 Architecture ...................................
Contents Chapter 3 Advanced Programming with NI-IMAQdx Camera Attributes.......................................................................................................... 3-1 Attribute Name................................................................................................ 3-1 Attribute Type ................................................................................................. 3-2 Attribute Value.................................................................................
Contents Chapter 5 Using NI-IMAQdx in C and .NET Using NI-IMAQdx for C ...............................................................................................5-1 Using NI-IMAQdx for Microsoft Visual Studio .NET..................................................5-2 Creating a New .NET Application ..................................................................
Introduction to NI-IMAQdx 1 This chapter describes the NI-IMAQdx driver software, lists the supported application development environments (ADEs), describes the fundamentals of creating applications using NI-IMAQdx, describes the files used to build these applications, and explains where to find sample programs. About the NI-IMAQdx Software NI-IMAQdx gives you the ability to use GigE Vision cameras and IEEE 1394 industrial digital video cameras to acquire images.
Chapter 1 Introduction to NI-IMAQdx Application Development Environments This release of NI-IMAQdx supports the following ADEs for Windows Vista/XP/2000: • LabVIEW version 7.1.1 and later • LabVIEW Real-Time Module version 7.1.1 and later • LabWindows™/CVI™ version 7.0 and later • Microsoft Visual C/C++ version 6.0 and later • Microsoft Visual Basic version 6.0 and later • Microsoft Visual Studio .
Chapter 1 Introduction to NI-IMAQdx Fundamentals of Building Applications with NI-IMAQdx Architecture Figure 1-1 illustrates the NI-IMAQdx driver architecture. LabWindows/CVI Visual C++ LabVIEW NIIMAQDX.DLL Application Level Kernel Level NIIMAQDXK.DLL Windows Kernel LabVIEW RT Kernel NIPALK.SYS OCHI1394.SYS 1394BUS.SYS 1 1 NIPALP.DLL TCPIP.SYS NDIS.SYS 1 TNF.DLL 1 NIGEV.SYS 1 Components provided by the underlying operating system. Figure 1-1.
Chapter 1 Introduction to NI-IMAQdx NI-IMAQdx Libraries The NI-IMAQdx function libraries are dynamic link libraries (DLLs), which means that NI-IMAQdx routines are not linked into the executable files of applications. Only the information about the NI-IMAQdx routines in the NI-IMAQdx 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.
2 Basic Acquisition with NI-IMAQdx This chapter contains an overview of the NI-IMAQdx library, a description of the acquisition flow of NI-IMAQdx, and generic programming examples. The chapter also contains flowcharts of high-level and low-level snap, grab, and sequence operations. Introduction The NI-IMAQdx application programming interface (API) is divided into two main function groups: high-level and low-level.
Chapter 2 Basic Acquisition with NI-IMAQdx Both high-level and low-level functions support snap, grab, sequence, and triggered acquisitions. Using 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 the image acquisition process, but you must understand the API and driver in greater detail to use these functions.
Chapter 2 Basic Acquisition with NI-IMAQdx Camera Name NI-IMAQdx references all camera sessions by a name. The driver creates default names for each camera in your system in the order that the cameras are connected. The names observe the convention shown in Table 2-1. Table 2-1. Camera Naming Convention Camera Name Camera Installed cam0 Device 0 cam1 Device 1 ... ... camn Device n Every camera has an .iid interface file and an .icd camera file.
Chapter 2 Basic Acquisition with NI-IMAQdx When you open a camera session with the Camera Open function, the camera with the unique serial number described by the interface file camn.iid opens, where n is the reference to the camera. If the camera is not present and a camera of the same make and model is present, as described in the interface file, the driver opens the available camera. The interface file updates to use the new camera.
Chapter 2 Basic Acquisition with NI-IMAQdx acquisition. National Instruments recommends one-shot acquisition for applications that do not require real-time acquisition or processing. Use a continuous acquisition to start an acquisition, continuously acquire images into the internal buffers, and explicitly stop the acquisition. With continuous acquisition, the driver acquires video data continuously from the camera and enables you to examine the most current buffer.
Chapter 2 Basic Acquisition with NI-IMAQdx transferred from the camera to system memory. In all video modes, the ROI specifies the amount of data decoded by the driver while acquiring into a user buffer. By default, the driver transfers the entire image.
Chapter 2 Basic Acquisition with NI-IMAQdx Buffer Number Mode Specify one of the following options for the buffer number mode. • Buffer Number—Gets the exact buffer number specified in the Buffer Number parameter. • Last—Gets the most recently acquired buffer. • Next—Gets the next incoming buffer. Buffer Number A buffer number is a zero-based index that represents the cumulated transferred image count.
Chapter 2 Basic Acquisition with NI-IMAQdx The default overwrite mode for all types of acquisition is to get the newest valid buffer. This option, which National Instruments recommends for most applications, enables you to process the most recent image. If you need to get the image closest in time to a requested buffer, configure the driver to get the oldest valid buffer.
Chapter 2 Basic Acquisition with NI-IMAQdx Decoding images requires CPU resources. However, many of the decoding algorithms have been optimized in the driver. If you do not want decoded image data, you can use NI-IMAQdx to get a copy of the raw camera output. Programming Examples This section contains examples of high-level and low-level image acquisitions. Refer to the Example Programs section of Chapter 1, Introduction to NI-IMAQdx, for directory paths to the code examples discussed in this section.
Chapter 2 Basic Acquisition with NI-IMAQdx Note If you do not have a valid session, a temporary session is created using cam0. Then, the snap acquires the next incoming image into a user buffer. After the image is acquired, the program calls image processing and analysis functions. When the processing and analysis functions are finished, the program calls the Close Camera function using the camera handle.
Chapter 2 Basic Acquisition with NI-IMAQdx Calling the Configure Grab function opens a session for a grab acquisition. During acquisition, each successive grab copies the last acquired internal buffer into a user buffer where you can process the image. Sequence A sequence acquires a specified number of internal buffers and then stops. Figure 2-4 illustrates the typical programming order of a high-level sequence acquisition.
Chapter 2 Basic Acquisition with NI-IMAQdx Snap The low-level snap examples set up a one-shot, single-image acquisition and start the acquisition. The program acquires an image and processes it. Finally, the program stops the acquisition, unconfigures the acquisition, and closes the session. Figure 2-5 illustrates the programming order of a low-level snap acquisition.
Chapter 2 Basic Acquisition with NI-IMAQdx Grab The low-level grab examples demonstrate how to perform a grab acquisition using low-level function calls. The program sets up a continuous acquisition into three internal buffers and starts the acquisition. The main loop iterates continuously. In the main processing loop, the program acquires an image and processes it. After the loop, the program stops the acquisition, unconfigures the acquisition, and closes the session.
Chapter 2 Basic Acquisition with NI-IMAQdx Sequence The low-level sequence examples demonstrate how to perform a sequence acquisition using low-level calls. The program sets up a one-shot, multi-image acquisition and starts the acquisition. The main loop iterates once for each internal buffer. In the main processing loop, the program acquires an image and processes it. After the loop, the program stops the acquisition, unconfigures the acquisition, and closes the session.
Advanced Programming with NI-IMAQdx 3 This chapter contains information about setting camera attributes, broadcasting acquired images to multiple machines, using scale to define the size of transferred images, and triggering. Camera Attributes After opening a camera, configure the camera attributes by specifying the following parameters: the attribute name, the attribute type, and the attribute value. Specify the same attributes when querying the camera attributes.
Chapter 3 Advanced Programming with NI-IMAQdx Attribute Type The attribute type determines how a camera attribute is stored in the driver and the camera. Use the Get Attribute Type function to query the type of a given attribute. Each attribute is represented as one of the following types. Table 3-1.
Chapter 3 Advanced Programming with NI-IMAQdx The following value types are compatible for any given attribute type. Table 3-3. Attribute Types and Compatible Value Types Attribute Type Compatible Value Types U32 U32, I64, F64, String I64 U32, I64, F64, String F64 U32, I64, F64, String String String Enum U32, I64, F64, String, EnumItem Bool U32, I64, F64, String, Bool Command U32, I64, F64, String, Bool The bolded compatible value type indicates the native value type.
Chapter 3 Advanced Programming with NI-IMAQdx The following range is applicable for any given attribute. Table 3-4. Attribute Types and Compatible Range Attribute Type Compatible Range U32 Minimum, Maximum, Increment I64 Minimum, Maximum, Increment F64 Minimum, Maximum, Increment String N/A Enum Attribute Values Bool N/A Command N/A Broadcasting Many machine vision applications involve a single host computer acquiring data from a single industrial camera.
Chapter 3 Advanced Programming with NI-IMAQdx Camera Broadcast PX I-1 00B Host Computer (Listener) Host Computer (Controller) Host Computer (Listener) Figure 3-1. One Camera Broadcasting to Multiple Host Computers The camera broadcasts video data on the camera bus and all the connected host computers receive the same image data. In this scenario, one host computer is designated as the controller. The controller is responsible for starting/stopping the camera feed.
Chapter 3 Advanced Programming with NI-IMAQdx For GigE Vision cameras, you can configure the camera to broadcast or multicast image data to all nodes on the network. Broadcast is not routable, and everyone on the same network sees the data, even if they are not listening. Multicast is routable if the network is configured properly. A multicast configuration is preferred if supported by the camera because only interested parties can see the data traffic. Next, start the listener(s).
Chapter 3 Advanced Programming with NI-IMAQdx The Increment values are camera-specific. Refer to the camera documentation or query the Increment attributes for width and height to obtain the actual values. (0,0) Offset Y Acquired Sub-Image Height Increment Width Increment (max width, max height) Offset X Figure 3-2. Partial Image Size Format (Scalable) Trigger Modes The IIDC 1.31 and GigE Vision 1.0 specifications provide several external triggering modes for cameras.
Chapter 3 Advanced Programming with NI-IMAQdx • TriggerParameter—Certain trigger modes require an additional parameter. Refer to the following sections to see if the optional parameter is required. Trigger Mode 0 With trigger mode 0, the camera starts frame integration when the external trigger input changes to an active value. The frame is exposed for a duration specified by the shutter attribute before the camera transfers the image to the host computer. No optional parameter is required.
Chapter 3 Advanced Programming with NI-IMAQdx Trigger Mode 2 With trigger mode 2, the camera starts frame integration when the external trigger input changes to an active value. The same frame is exposed for multiple triggers. The number of triggers is specified by the optional parameter, which must have a value of 2 or more.
Chapter 3 Advanced Programming with NI-IMAQdx Trigger Mode 4 With trigger mode 4, the camera starts frame integration when the external trigger input changes to an active value. Multiple frames are exposed before the camera transfers the image to the host computer. Each frame is exposed for a duration specified by the shutter attribute. The number of frames is specified by the optional parameter, which must have a value of 1 or more.
Chapter 3 Advanced Programming with NI-IMAQdx Trigger Modes for GigE Vision Cameras Note All triggering modes and parameters for GigE Vision cameras are subject to camera vendor implementation. Refer to your camera documentation for triggering modes and parameters available for your camera. Most GigE Vision cameras that support triggering have the following attributes: • TriggerSelector—Specifies the type of trigger to control.
Using NI-IMAQdx in LabVIEW 4 This chapter describes how to use NI-IMAQdx VIs in LabVIEW. Introduction The NI-IMAQdx VI library—part of the NI-IMAQdx software—is a group of virtual instruments (VIs) that enable you to use LabVIEW with your camera. NI Vision for LabVIEW is the National Instruments image processing and analysis library, which consists of more than 400 VIs. Some of the basic NI Vision VIs are shared with NI-IMAQdx.
Chapter 4 Using NI-IMAQdx in LabVIEW The Vision and Motion»NI-IMAQdx»NI-IMAQdx Low Level palette contains VIs for more advanced applications. Refer to the NI-IMAQdx VI Reference Help for more information about using these VIs. Common VI Parameters The following sections describe commonly used VIs and important parameters common to many VIs. IMAQdx Session IMAQdx Session is a unique identifier that specifies which interface file to use for the acquisition.
Chapter 4 Using NI-IMAQdx in LabVIEW Acquisition VIs Two types of acquisition VIs are available in LabVIEW: high-level and low-level. High-Level Use the high-level acquisition VIs for basic image acquisition applications. VIs are included for snap, grab, and sequence, as described in the Acquisition Types section of this chapter. Low-Level Use the low-level acquisition VIs for more advanced image acquisition applications.
Chapter 4 Using NI-IMAQdx in LabVIEW Buffer Management The IMAQ Create VI and IMAQ Dispose VI manage image buffers in LabVIEW. IMAQ Create, shown in Figure 4-1, 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 Grayscale (U8) for 8-bit monochrome images, Grayscale (I16) for 16-bit monochrome images, and RGB (U32) for RGB color images.
Chapter 4 Using NI-IMAQdx in LabVIEW Acquisition Types The following sections describe snap, grab, and sequence acquisitions in LabVIEW and give examples. Snap Use the IMAQdx Snap VI for snap applications. Figure 4-3 shows a simplified block diagram for using IMAQdx Snap. Figure 4-3. Acquiring an Image Using Snap Grab Use two VIs—IMAQdx Configure Grab and IMAQdx Grab—for a grab acquisition in LabVIEW.
Chapter 4 Using NI-IMAQdx in LabVIEW Figure 4-4 shows a simplified block diagram for using IMAQdx Configure Grab and IMAQdx Grab. Figure 4-4. Acquiring Images Using Grab Sequence Use the IMAQdx Sequence VI for sequence applications. IMAQdx Sequence starts, acquires, and releases a sequence acquisition. IMAQdx Sequence does not return until the entire sequence is acquired. Figure 4-5 shows a simplified block diagram for using IMAQdx Sequence.
Chapter 4 Using NI-IMAQdx in LabVIEW Image Display Many image acquisition applications require that one or more images be displayed. You have several options for displaying images in LabVIEW. You can display an image directly on the front panel using an Image Display control, which is available on the Vision Controls palette. To display an image on an Image Display control, place the control on the front panel of your VI.
Chapter 4 Using NI-IMAQdx in LabVIEW If you have LabVIEW RT, you can use IMAQ RT Video Out, located at Vision and Motion»Vision Utilities»IMAQ RT, to display an image on the monitor connected to your RT device. Use IMAQ Video Out Display Mode, located at Vision and Motion»Vision Utilities»IMAQ RT, to configure the monitor for display. Figure 4-8 illustrates configuring the monitor and displaying an image acquired with IMAQdx Snap. Figure 4-8.
Chapter 4 Using NI-IMAQdx in LabVIEW Figure 4-9 shows how to set camera attributes with the property nodes in NI-IMAQdx. Figure 4-9. Setting Camera Attributes with Property Nodes Error Handling Every NI-IMAQdx VI contains an error in input cluster and an error out output cluster. The clusters, shown in Figure 4-10, 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.
Chapter 4 Using NI-IMAQdx in LabVIEW You can use the Simple Error Handler VI, located on the Functions» Dialog & User Interface palette, to check for errors that occur while executing a VI. If you wire an error cluster to the Simple Error Handle VI, the VI deciphers the error information and displays a dialog box that describes the error. If no error occurred, the Simple Error Handler VI does nothing. Figure 4-11 illustrates wiring an NI-IMAQdx VI to the Simple Error Handler VI. Figure 4-11.
Using NI-IMAQdx in C and .NET 5 This chapter briefly describes how to use NI-IMAQdx functions in Microsoft Visual C and Microsoft Visual Studio .NET. Using NI-IMAQdx for C This section outlines the process for developing NI-IMAQdx applications using C. Detailed instructions about creating project and source files are not included. For information about creating and managing project files, refer to the documentation included with your particular development environment.
Chapter 5 Using NI-IMAQdx in C and .NET You can use the additional Image functions installed with NI-IMAQdx. These functions use the NI Vision memory management feature, which automatically allocates the memory for your image. To use these Image functions, first create an image using imaqCreate, and then pass that image to an acquisition function. Using NI-IMAQdx for Microsoft Visual Studio .NET NI-IMAQdx installs the following assemblies that enable .
Chapter 5 Using NI-IMAQdx in C and .NET 4. Select Tools»Add/Remove Toolbox Items. 5. Under the .NET Framework Components tab, select the CWIMAQViewer control. When the Viewer control is in the toolbox, you can add it to your forms by clicking on the tool and drawing an area on the form. References to the NI Vision Interop Assemblies are automatically added to your project. NI-IMAQdx User Manual 5-3 ni.
Register-Level Programming A This appendix explains how to access and program register locations using the NI-IMAQdx software, and discusses the caveats involved in programming registers. Introduction All cameras communicate to the host computer through register maps. The register map reflects the system memory located on the camera. The register map allows the host computer to read and write information with minimal overhead.
Appendix A Register-Level Programming Host Computer IEEE 1394 Camera GigE Vision Camera (1) Send Request (2) Receive Request (2) Receive Request and Send Pending Packet (3) Send Result (3) Receive Pending Packet. Wait for complete (4) Complete Request and Send Result (5) Receive Result (4) Receive Result Figure A-1. Explanation of Split Transactions NI-IMAQdx supports the 1394 Trade Association IIDC 1.31 register specification and the GigE Vision 1.0 specification for industrial cameras.
Appendix A Register-Level Programming The NI-IMAQdx software provides the following register-level primitives: • Read Register—Reads 32-bits of data from a specified memory location • Write Register—Writes 32-bits of data to a specified memory location • Read Memory—Reads an array of bytes from a specified memory location and range • Write Memory—Writes an array of bytes to a specified memory location Usage To perform a register-level access, specify a memory location (or offset) and data storage.
Appendix A Register-Level Programming Advanced Example The advanced feature described in this example is specific to Basler IEEE 1394 cameras. The advanced feature replaces the live video feed with a static test pattern. According to the user documentation for the Basler A601f camera, the TEST_IMAGE register is located at advanced offset 0x0098. You can enable a static test pattern by setting bit 17 of the TEST_IMAGE register.
Appendix A Register-Level Programming endian data. To correct for this discrepancy, NI-IMAQdx byte-swaps every quadlet that is read or written with low-level register primitives. Byte Array Many cameras allow register-level access to more than 32 bits of data per communication request. In most cases, you can safely write and read a large, contiguous block of data to and from the connected camera. Some cameras fail when trying to access large payloads.
Technical Support and Professional Services B Visit the following sections of the National Instruments Web site at ni.com for technical support and professional services: • Support—Online technical support resources at ni.
Glossary A acquisition window The image size specific to a video standard or camera resolution. address Value that identifies a specific location (or series of locations) in memory. API Application programming interface. area 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. aspect ratio The ratio of a picture or image’s width to its height.
Glossary D 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). DLL 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.
Glossary GigE Vision A camera interface standard developed using the Gigabit Ethernet communication protocol. 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. H hardware abstraction layer Separates software API capabilities, such as general acquisition and control functions, from hardware-specific information. hue Represents the dominant color of a pixel.
Glossary M MAX Measurement & Automation Explorer—A controlled, centralized configuration environment that allows you to configure all of your NI devices. N NI-IMAQ Driver software for National Instruments image acquisition hardware. P page-locked buffer Memory page that is marked as non-pagable by the virtual file system. Page-locked buffers remain in physical memory and do not cause page faults pixel Picture element. The smallest division that makes up the video scan line.
Glossary R 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. resolution (1) The number of rows and columns of pixels. An image composed of m rows and n columns has a resolution of n × m. 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.
Glossary U user buffer A memory buffer created by the user as a destination for the image. In LabVIEW, this is created with the IMAQ Create VI. UV plane See YUV. V 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.
Index A configuration, 1-2 naming convention (table), 2-3 output formats, 1-1 camera control mode, 2-2, 2-4, 3-6 camera files, 1-2, 2-3, 2-4 configuration camera, 1-2 interface, 2-4 controller broadcasting, 3-5, 3-6 camera control mode, 2-4 conventions used in the manual, iv advanced programming examples grab using low-level functions, 2-13 sequence using low-level functions, 2-14 snap using low-level functions, 2-12 application development, 1-3 C, 5-1 environments, 1-2 LabVIEW, 4-1 LabVIEW Real-Time Modu
Index F K features and overview, 1-1 Format 7 video mode, 3-1, 3-6 front panel, LabVIEW, 4-1, 4-7 KnowledgeBase, B-1 G LabVIEW programming language, 1-2, 3-6, 4-1 block diagram, 4-1, 4-5 to 4-7 front panel, 4-1, 4-7 property nodes, 4-2, 4-8, 4-9 LabVIEW Real-Time Module, 1-2, 4-1 LabWindows/CVI programming language, 1-2 listener broadcasting, 3-5, 3-6 camera control mode, 2-4 L grab high-level, 2-1, 2-7, 2-10, 4-5 flowchart, 2-10 in LabVIEW (figure), 4-6 low-level, 2-13 flowchart, 2-13 H help, tech
Index S architecture, 1-3 libraries, 1-4 scalable image size, 3-6 sequence high-level, 2-1, 4-6 flowchart, 2-11 in LabVIEW (figure), 4-6 low-level, 2-14 flowchart, 2-14 snap high-level, 2-1, 4-5 flowchart, 2-9 in LabVIEW (figure), 4-5 low-level, 2-12 flowchart, 2-12 software (NI resources), B-1 static test pattern, A-4 support, technical, B-1 O overwrite mode, 2-7 P programming guidelines for C, 5-1 high-level functions, 2-1 introduction to programming with NI-IMAQdx, 2-1 low-level functions, 2-1 regis
Index V W VI parameters, 4-2 video mode decoding, 2-8 table, 2-8 ROI considerations, 2-6 Visual Basic programming language, 1-2 Visual Studio .NET programming language, 1-2 Visual Studio .NET. See .NET Web resources, B-1 NI-IMAQdx User Manual Y YUV, 1-1, 2-8 I-4 ni.
