UM.
UM.book Page 2 Monday, July 13, 1998 9:49 AM Internet Support E-mail: support@natinst.com FTP Site: ftp.natinst.com Web Address: http://www.natinst.
UM.book Page 3 Monday, July 13, 1998 9:49 AM 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.
UM.book Page v Monday, July 13, 1998 9:49 AM Contents About This Manual How to Use the NI-IMAQ Manual Set ..........................................................................ix Organization of This Manual .........................................................................................ix Conventions Used in This Manual.................................................................................x National Instruments Documentation ...........................................................
UM.book Page vi Monday, July 13, 1998 9:49 AM Contents Chapter 3 Programming with NI-IMAQ Introduction ................................................................................................................... 3-1 High-Level Functions ..................................................................................... 3-1 Low-Level Functions ...................................................................................... 3-2 Establishing Interface Connections and Sessions..................
UM.book Page vii Monday, July 13, 1998 9:49 AM Contents Figures Figure 3-1. Figure 3-2. Figure 3-3. Figure 3-4. Figure 3-5. Figure 3-6. Figure 3-7. NI-IMAQ Status Signals .......................................................................3-6 Snap Programming Flowchart...............................................................3-7 Grab Programming Flowchart...............................................................3-9 Sequence Programming Flowchart ..............................................
UM.book Page ix Monday, July 13, 1998 9:49 AM 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.
UM.book Page x Monday, July 13, 1998 9:49 AM 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.
UM.book Page xi Monday, July 13, 1998 9:49 AM 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.
UM.book Page 1 Monday, July 13, 1998 9:49 AM Introduction to NI-IMAQ 1 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.
UM.book Page 2 Monday, July 13, 1998 9:49 AM 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: Note • 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.
UM.book Page 3 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 4 Monday, July 13, 1998 9:49 AM Chapter 1 Introduction to NI-IMAQ Sample Programs Please refer to the readme.txt file located in your target installation directory for the latest details on NI-IMAQ sample programs. These programs are installed in the sample subdirectory under the target installation folder if you elected to install the sample files.
UM.book Page 1 Monday, July 13, 1998 9:49 AM 2 Software Overview This chapter describes the classes of NI-IMAQ functions and briefly describes each function.
UM.book Page 2 Monday, July 13, 1998 9:49 AM 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 Opens a session of an unknown type and returns a session ID. imgClose Closes a session or interface and unlocks and releases all buffers associated with the data type.
UM.book Page 3 Monday, July 13, 1998 9:49 AM Chapter 2 Software Overview Performs a transfer from a continuous acquisition. Call this function only after calling imgGrabSetup. imgGrabArea 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.
UM.book Page 4 Monday, July 13, 1998 9:49 AM Chapter 2 Software Overview imgSessionWaitSignalAsync Monitors for a signal to be asserted and invokes a user-defined callback when the signal is asserted. imgPulseCreate 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 Disposes of a pulse ID.
UM.book Page 5 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 6 Monday, July 13, 1998 9:49 AM Chapter 2 Software Overview Attribute Functions Use attribute functions to examine and change NI-IMAQ or camera attributes. Returns an attribute for an interface or session. imgGetAttribute 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.
UM.book Page 7 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 1 Monday, July 13, 1998 9:49 AM Programming with NI-IMAQ 3 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.
UM.
UM.book Page 3 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ Before you can acquire image data successfully, you must open an interface by using the imgInterfaceOpen function. imgInterfaceOpen requires 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.
UM.book Page 4 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ This example opens an interface to img0 and then creates a session to acquire images. When the program is finished with the interface and session, it then closes both handles using the imgClose function. 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.
UM.book Page 5 Monday, July 13, 1998 9:49 AM 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 imgSetCameraAttributeString and imgGetCameraAttributeString functions to set and get the value of String, Float and Integer attributes.
UM.book Page 6 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 7 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ High-Level Snap Functions A snap acquires a single image into a memory buffer. Snap functions include imgSnap and 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.
UM.book Page 8 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ The sample then calls a process function to analyze the image. When the program is finished, it calls imgClose with 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.
UM.book Page 9 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ imgInterfaceOpen opens imgInterfaceOpen imgSessionOpen imgGrabSetup imgSessionStartAcquisition and configures the interface according to the file setup by the IMAQ Configuration Utility. imgSessionOpen opens a session that will be used for all acquisition and configuration. imgGrabSetup configures the interface for a continuous acquisition. imgSessionStartAcquisition starts the acquisition into a driver buffer.
UM.book Page 10 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ High-Level Sequence Functions Sequence functions include imgSequenceSetup, imgSessionStartAcquisition and imgStopAcquisition. A sequence initiates a variable-length and variable-delay transfer to multiple buffers. You can configure the delay between acquisitions with SequenceSetup and specify both the buffer list that will be used for transfers and the number of buffers.
UM.book Page 11 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ The HLSeq.c example 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.
UM.book Page 12 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ imgInterfaceOpen opens imgInterfaceOpen imgSessionOpen and configures the interface according to the file setup by the IMAQ Configuration Utility. imgSessionOpen opens a session that will be used for all acquisition and configuration. imgRingSetup sets up a ring acquisition to a imgRingSetup imgSessionStartAcquisition imgSessionStatus User-Specific Functions programmable number of buffers.
UM.book Page 13 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 14 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ imgInterfaceOpen opens and configures the imgInterfaceOpen imgSessionOpen imgSessionTriggerConfigure interface according to the file set up by the IMAQ Configuration Utility. 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.
UM.book Page 15 Monday, July 13, 1998 9:49 AM 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 imgPlot function, you must align the image width on a 32-bit boundary as well. Performing a Grab Using Low-Level Functions The LLGrab.
UM.book Page 16 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 17 Monday, July 13, 1998 9:49 AM Chapter 3 Programming with NI-IMAQ imgInterfaceOpen opens imgInterfaceOpen imgSessionOpen and configures the interface according to the file setup by the IMAQ Configuration Utility. imgSessionOpen opens a session that will be used for all acquisition and configuration. imgSetAttribute configures the StillColor imgSetAttribute mode to acquire a StillColor image from a composite source using the attribute IMG_ATTR_COLOR_MODE.
UM.book Page 1 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 2 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 3 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 4 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 5 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 6 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 7 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 8 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 9 Monday, July 13, 1998 9:49 AM Appendix A StillColor used if you are performing averaging on your image. For example, 4 averaging an image 16 times requires four extra bits (16 = 2 ) 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.
UM.book Page 1 Monday, July 13, 1998 9:49 AM Customer Communication B 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.
UM.book Page 2 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 3 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 5 Monday, July 13, 1998 9:49 AM 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.
UM.book Page 7 Monday, July 13, 1998 9:49 AM 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.
UM.
UM.
UM.book Page 3 Monday, July 13, 1998 9:49 AM Glossary black reference level the level that represents the darkest an image can get. See also white reference level.
UM.
UM.
UM.
UM.book Page 7 Monday, July 13, 1998 9:49 AM Glossary I IC integrated circuit ID identification IEEE Institute of Electrical and Electronics Engineers in.
UM.
UM.book Page 9 Monday, July 13, 1998 9:49 AM Glossary memory buffer See buffer.
UM.book Page 10 Monday, July 13, 1998 9:49 AM Glossary PCLKIN pixel clock in signal PFI programmable function input PGIA programmable gain instrumentation amplifier 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.
UM.book Page 11 Monday, July 13, 1998 9:49 AM Glossary resolution 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. RGB 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.
UM.
UM.book Page 13 Monday, July 13, 1998 9:49 AM 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.
UM.
UM.
UM.
UM.
