IMAQ TM NI-IMAQ for IEEE 1394 Cameras User Manual TM Image Acquisition Software NI-IMAQ for IEEE 1394 Cameras User Manual March 2005 370362C-01
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 note, which alerts you to important information. bold Bold text denotes items that you must select or click 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 a IEEE 1394 Camera...................................................................1-2 Fundamentals of Building Applications with NI-IMAQ for IEEE 1394 Cameras........1-2 Architecture ..................................
Contents Chapter 3 Advanced Programming with NI-IMAQ for IEEE 1394 Cameras Camera Attributes.......................................................................................................... 3-1 Broadcasting .................................................................................................................. 3-1 Implementation ............................................................................................... 3-2 Scalable Image Size..........................................
Contents Appendix A Register-Level Programming Appendix B Technical Support and Professional Services Glossary Index © National Instruments Corporation vii NI-IMAQ for IEEE 1394 Cameras User Manual
Introduction to NI-IMAQ for IEEE 1394 Cameras 1 This chapter describes the NI-IMAQ for IEEE 1394 Cameras software, lists the supported application development environments (ADEs), describes the fundamentals of creating applications using NI-IMAQ for IEEE 1394 Cameras, describes the files used to build these applications, and explains where to find sample programs.
Chapter 1 Introduction to NI-IMAQ for IEEE 1394 Cameras Application Development Environments This release of NI-IMAQ for IEEE 1394 Cameras supports the following ADEs for Windows 2000/XP: • LabVIEW version 7.0 and later • LabVIEW Real-Time Module version 7.0 and later • LabWindows™/CVI™ version 6.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-IMAQ for IEEE 1394 Cameras LabWindows/CVI Visual C++ LabVIEW IMAQ1394.DLL Application Level Kernel Level IMAQ1394K.DLL Windows Kernel LabVIEW RT Kernel NIPALK.SYS NIPALP.DLL OCHI1394.SYS TNF.DLL 1394BUS.SYS Figure 1-1. NI-IMAQ for IEEE 1394 Cameras Architecture The architecture uses a hardware abstraction layer, which separates software API capabilities, such as general acquisition and control functions, from hardware-specific information.
Chapter 1 Introduction to NI-IMAQ for IEEE 1394 Cameras information through import libraries or through function declarations. Your NI-IMAQ for IEEE 1394 Cameras software contains function prototypes for all routines. Example Programs You can find NI-IMAQ for IEEE 1394 Cameras code examples in the following directories. If you installed NI-IMAQ for IEEE 1394 Cameras in the default location, you can find the following example directories within C:\Program Files\ National Instruments.
Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras 2 This chapter contains an overview of the NI-IMAQ for IEEE 1394 Cameras library, a description of the acquisition flow of NI-IMAQ for IEEE 1394 Cameras, and generic programming examples. The chapter also contains flowcharts of high-level and low-level snap, grab, and sequence operations. Introduction The NI-IMAQ for IEEE 1394 Cameras application programming interface (API) is divided two main function groups: high-level and low-level.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras 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-IMAQ for IEEE 1394 Cameras Table 2-1. Camera Naming Convention Camera Name IEEE 1394 Camera Installed cam0 Device 0 cam1 Device 1 ... ... camn Device n Every camera has an .iid interface file and an .icd camera file. • Interface files—Store information about which physical camera is associated with a camera name. Each interface file can be used by only a single camera. • Camera files—Store all the configurable attributes.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras file opens, and all the user attributes are set in the driver. If no camera of the same make and model is present, the Initialize function returns an error. Camera Control Mode The camera control mode parameter has two options: controller and listener. The default option—controller—controls the camera and receives video data. The listener only receives video data. Use the listener option in broadcasting applications.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras the camera and enables you to examine the most current buffer. National Instruments recommends continuous acquisition for real-time acquisition and processing. Note If CPU activity increases during a continuous acquisition, the driver might miss subsequent images. Check the buffer number output to determine if you have missed any images.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras Although you can specify an ROI of any size, the NI-IMAQ for IEEE 1394 Cameras software coerces the ROI into one that is more compatible for the given camera. Refer to Chapter 3, Advanced Programming with NI-IMAQ for IEEE 1394 Cameras, for more information about defining an ROI for Format 7 images. Note Acquisition After configuring and starting your acquisition, the camera sends data to the internal buffers.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras Overwrite Mode Ideally, a continuous acquisition acquires and processes every image that is transferred from the camera. However, because of processing time fluctuations, some images from the camera may not be processed before the camera transfers the next image. Using multiple internal buffers in a continuous acquisition allows for a small amount of jitter.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras Table 2-2 lists common video modes and their corresponding image types after being decoded by NI-IMAQ for IEEE 1394 Cameras. Table 2-2.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras Snap A snap acquires a single image into a user buffer. Figure 2-2 illustrates the typical programming order of a high-level snap acquisition. Initialize Snap User-Specific Functions Close Opens and Configures Camera Acquires Image into Buffer Executes User-Specific Image Processing Closes the Camera Session Figure 2-2. High-Level Snap Flowchart Use a snap for low-speed or one-shot applications where ease of programming is essential.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras Grab A grab initiates a continuous high-speed acquisition of images to one or more internal buffers. Figure 2-3 illustrates the typical programming order of a high-level grab acquisition.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras 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. Initialize Sequence User-Specific Functions Opens and Configures Camera Acquires a Specified Number of Buffers and Stops Executes User-Specific Image Processing (Loop) Close Closes the Camera Session Figure 2-4.
Chapter 2 Basic Acquisition with NI-IMAQ for IEEE 1394 Cameras 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-IMAQ for IEEE 1394 Cameras 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-IMAQ for IEEE 1394 Cameras 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-IMAQ for IEEE 1394 Cameras 3 This chapter contains information about setting camera attributes, broadcasting acquired images to multiple machines, using Format 7 to define the size of transferred images, and triggering. Camera Attributes Use camera attributes to control camera-specific features, such as brightness and shutter speed. You can set camera attributes directly from the NI-IMAQ for IEEE 1394 Cameras software or through the Camera Attributes tab in MAX.
Chapter 3 Advanced Programming with NI-IMAQ for IEEE 1394 Cameras IEEE 1394 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 IEEE 1394 camera broadcasts video data on the IEEE 1394 bus and all the connected host computers receive the same image data. In this scenario, one host computer is designated as the controller.
Chapter 3 Advanced Programming with NI-IMAQ for IEEE 1394 Cameras Next, start the listener(s). On the listening computer, open your camera interface with the 64-bit unique identifier of the target camera, which you can find in the General tab in MAX. The controller can get a unique ID and send it to the listener sessions. Additionally, you must set the listener camera control mode parameter. At this point, both the controller and listener systems are acquiring the same live data from the same camera.
Chapter 3 Advanced Programming with NI-IMAQ for IEEE 1394 Cameras Full Image Size Acquired Sub-Image User-Defined Region Unit Height Unit Width Figure 3-2. Partial Image Size Format (Format 7) Trigger Modes The IIDC 1.31 specification provides several external triggering modes for IEEE 1394 cameras. A IEEE 1394 camera may support one or more of the triggering modes. Refer to your camera documentation to find out which standard modes are implemented.
Chapter 3 Advanced Programming with NI-IMAQ for IEEE 1394 Cameras 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-IMAQ for IEEE 1394 Cameras 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-IMAQ for IEEE 1394 Cameras 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.
Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW 4 This chapter describes how to use NI-IMAQ for IEEE 1394 Cameras VIs in LabVIEW. Introduction The NI-IMAQ for IEEE 1394 Cameras VI library—part of the NI-IMAQ for IEEE 1394 Cameras software—is a group of virtual instruments (VIs) that enable you to use LabVIEW with an IEEE 1394 camera. IMAQ Vision for LabVIEW is the National Instruments image processing and analysis library, which consists of more than 400 VIs.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Location of the NI-IMAQ for IEEE 1394 Cameras VIs You can find the NI-IMAQ for IEEE 1394 Cameras VIs in the LabVIEW Functions palette. From the LabVIEW block diagram, select NI Measurements»Vision»IMAQ IEEE-1394. The most commonly used, high-level VIs are on the IMAQ for IEEE-1394 palette. You can find VIs for basic acquisition and changing attributes.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Image Buffer Many acquisition VIs require an image buffer to receive the captured image. You can create this image buffer with IMAQ Create. Refer to the Buffer Management section of this chapter for more information about using buffers. Image In receives the image buffer. Image Out returns the captured image. Region of Interest The acquisition VIs use the Region of Interest input to specify a rectangular portion of an image frame to be captured.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW 4. Call IMAQ1394 Get Image to obtain a copy of the requested image data. 5. After an acquisition, call IMAQ1394 Stop Acquisition to stop transferring data from the camera. 6. Call IMAQ1394 Clear Acquisition to release the resources associated with the acquisition. 7. Call IMAQ1394 Close to close the camera session.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW IMAQ Dispose, shown in Figure 4-2, frees the memory allocated for the image buffer. Call this VI only after the image is no longer required for processing. Figure 4-2. IMAQ Dispose Acquisition Types The following sections describe snap, grab, and sequence acquisitions in LabVIEW and give examples. Snap Use the IMAQ1394 Snap VI for snap applications. Figure 4-3 shows a simplified block diagram for using IMAQ1394 Snap. Figure 4-3.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Figure 4-4. Acquiring Images Using Grab Sequence Use the IMAQ1394 Sequence VI for sequence applications. IMAQ1394 Sequence starts, acquires, and releases a sequence acquisition. IMAQ1394 Sequence does not return until the entire sequence is acquired. Figure 4-5 shows a simplified block diagram for using IMAQ1394 Sequence. Place the IMAQ Create VI inside a For Loop to create an array of images for the Image In input to IMAQ1394 Sequence.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Triggering Often, you may need to link or coordinate a vision action or function with events external to the computer, such as receiving a strobe pulse for lighting or a pulse from an infrared detector that indicates the position of an item on an assembly line. In these cases, use a triggered image acquisition. Figure 4-6 illustrates using the IMAQ1394 Configure Trigger VI to perform a grab acquisition based on a trigger.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Figure 4-7. Displaying an Image Using an Image Control If you have IMAQ Vision for LabVIEW, you can display an image in an external window using IMAQ WindDraw, located at Vision» Vision Utilities»External Display. Use IMAQ WindDraw when you need more image size and location control. Figure 4-8 illustrates using IMAQ WindDraw to display an image acquired using IMAQ1394 Snap. You can display images in the same way using any acquisition type.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Camera Attributes To modify camera attributes in LabVIEW, use the IMAQ1394 Property Node. Every camera attribute has three parameters: Attribute Key, Attribute Mode, and Attribute Value. • Attribute Key—Select from a list of supported keys, including Brightness, Gain, Shutter Speed, and White Balance. Use IMAQ1394 GetFeatures to return a list of supported camera attributes.
Chapter 4 Using NI-IMAQ for IEEE 1394 Cameras in LabVIEW Figure 4-11. Error Clusters You can use the Simple Error Handler VI, located on the Functions» Time&Dialog 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.
Using NI-IMAQ for IEEE 1394 Cameras in C and .NET 5 This chapter briefly describes how to use NI-IMAQ for IEEE 1394 Cameras function in Microsoft Visual C and Microsoft Visual Studio .NET. Using NI-IMAQ for IEEE 1394 Cameras for C This section outlines the process for developing NI-IMAQ for IEEE 1394 Cameras applications using C for Windows 2000/XP. Detailed instructions about creating project and source files are not included.
Chapter 5 Using NI-IMAQ for IEEE 1394 Cameras in C and .NET include files under the include subdirectory. The import libraries for Microsoft Visual C++ are located under the lib\msvc subdirectory. If you have IMAQ Vision for LabWindows/CVI installed on your computer, you can use the additional Image functions installed with NI-IMAQ for IEEE 1394 Cameras. These functions use the IMAQ Vision memory management feature, which automatically allocates the memory for your image.
Chapter 5 Using NI-IMAQ for IEEE 1394 Cameras in C and .NET If you need to display acquired images, you also must add an IMAQ Vision Viewer control to your toolbox and to your form. Complete the following steps to add the IMAQ Vision Viewer control to the Microsoft Visual Studio .NET 2003 toolbox. 1. With your project open, open a form in Design View. 2. Open the Toolbox (View»Toolbox). 3. Select the category in which you want the IMAQ Vision controls to appear (General, Components, and so on). 4.
Register-Level Programming A This appendix explains how to access and program register locations using the NI-IMAQ for IEEE 1394 Cameras software, and discusses the caveats involved in programming registers. Introduction All IEEE 1394 cameras communicate to the host computer through register maps. The register map reflects the system memory located on the IEEE 1394 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 (1) Send Request (2) Receive Request and Send Pending Packet (3) Receive Pending Packet. Wait for complete (4) Complete Request and Send Result (5) Receive Result Figure A-1. Explanation of Split Transactions NI-IMAQ for IEEE 1394 Cameras 2.0 supports the 1394 Trade Association IIDC 1.31 register specification for industrial cameras. Most of the intricacies of register-level programming are abstracted by the driver.
Appendix A Note Register-Level Programming • Read Quadlet Block—Reads an array of quadlets from a specified memory location and range • Write Quadlet Block—Writes an array of quadlets to a specified memory location In LabVIEW, only the quadlet block variants are exposed. Usage To perform a register-level access, specify a memory location (or offset) and data storage. IEEE 1394 memory locations are specified as 48-bit values. The upper 20 bits are filled in by the driver.
Appendix A Register-Level Programming register (0x480). Add the specified offset to the base register—0xF0F00000 for most IEEE 1394 cameras. 0xF0F00000 + 0x480 = 0xF0F00480 Read the value into storage. read quadlet (0xF0F00480) = where = 0x800000. Now, calculate the offset to the advanced feature offset. You need to multiply the previous result by 4 to convert the quadlet offset value to byte offset.
Appendix A Register-Level Programming Quadlet Array Many IEEE 1394 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. If the camera does not successfully transfer an array of quadlets, attempt to transfer the quadlets one at a time.
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 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. driver Software that controls a specific hardware device, such as an IEEE 1394 camera.
Glossary hue 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 color spectrum. See also RGB. 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. internal buffer A page-locked buffer. See also page-locked buffer.
Glossary 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. 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). process-safe handle A handle that allows only one process to access a camera at any given time.
Glossary S sequence Performs an acquisition that acquires a specified number of buffers, then stops. snap Acquires a single image to a buffer. syntax Set of rules to which statements must conform in a particular programming language. T timeout Length of time, in milliseconds, that the driver waits for an image from the camera before returning an error transfer rate The rate, measured in bytes/s, at which data is moved from source to destination after software initialization and set up operations.
Glossary Y YUV A representation of a color image used for the coding of NTSC or PAL video signals. The luma information is called Y, while the chroma information is represented by two components, U and V representing the coordinates in a color plane. NI-IMAQ for IEEE 1394 Cameras User Manual G-6 ni.
Index Symbols camera attributes, 2-1, 2-3, 2-4, 3-1, 3-3 setting camera attributes in C, 3-1 setting camera attributes in LabVIEW, 4-9 setting camera attributes in Visual Basic and .NET, 3-1 configuration, 1-2 naming convention (table), 2-3 output formats, 1-1 camera control mode, 2-2, 2-4, 3-3 camera files, 1-2, 2-3 configuration camera, 1-2 interface, 2-4 controller broadcasting, 3-2, 3-3 camera control mode, 2-4 conventions used in the manual, iv .
Index initialization, interface, 2-2 instrument drivers (NI resources), B-1 interface file, 2-3, 4-2 internal buffers, 2-1, 2-4 to 2-14, 4-5 introductory programming examples, 2-8 high-level grab functions, 2-10 high-level sequence functions, 2-11 high-level snap functions, 2-9 examples advanced programming examples, 2-11 introductory programming examples, 2-8 location of files, 1-4 examples (NI resources), B-1 F features and overview, 1-1 Format 7 video mode, 2-5, 3-1, 3-3 figure, 3-4 front panel, LabVI
Index R NI-IMAQ for IEEE 1394 Cameras acquisition types grab, 4-5 sequence, 4-6 snap, 4-5 acquisition VIs high-level VIs, 4-3 low-level VIs, 4-3 architecture, 1-2 libraries, 1-3 region of interest.
Index V W VI parameters, 4-2 video mode decoding, 2-7 table, 2-8 ROI considerations, 2-5 Visual Basic programming language, 1-2, 3-1 Visual Studio .NET programming language, 1-2 Visual Studio .NET. See .NET Web resources, B-1 NI-IMAQ for IEEE 1394 Cameras User Manual Y YUV, 1-1, 2-7, 2-8 I-4 ni.
