National Instruments NI-IMAQ, User Manual

Page 1: ...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 ...

Page 2: ...00 Finland 09 725 725 11 France 01 48 14 24 24 Germany 089 741 31 30 Greece 30 1 42 96 427 Hong Kong 2645 3186 India 91805275406 Israel 03 6120092 Italy 02 413091 Japan 03 5472 2970 Korea 02 596 7456 Mexico 5 280 7625 Netherlands 0348 433466 New Zealand 09 914 0488 Norway 32 27 73 00 Poland 0 22 528 94 06 Portugal 351 1 726 9011 Singapore 2265886 Spain 91 640 0085 Sweden 08 587 895 00 Switzerland ...

Page 3: ...ct owner s abuse misuse or negligent acts and power failure or surges fire flood accident actions of third parties or other events outside reasonable control Copyright Under the copyright laws this publication may not be reproduced or transmitted in any form electronic or mechanical including photocopying recording storing in an information retrieval system or translating in whole or in part witho...

Page 4: ...ext denotes variables emphasis a cross reference or an introduction to a key concept This font also denotes text that is a placeholder for a word or value that you must supply monospace Text in this font denotes text or characters that you should enter from the keyboard sections of code programming examples and syntax examples This font is also used for the proper names of disk drives paths direct...

Page 5: ...Creating an Application 1 4 Sample Programs 1 5 Chapter 2 Software Overview Introduction 2 1 Generic Functions 2 1 High Level Functions 2 2 Snap Functions 2 2 Grab Functions 2 2 Sequence Functions 2 3 Trigger Functions 2 3 Miscellaneous Functions 2 3 Low Level Functions 2 3 Acquisition Functions 2 3 Attribute Functions 2 4 Utility Functions 2 5 Chapter 3 Programming with NI IMAQ for 1394 Introduct...

Page 6: ... an Asynchronous Snap Using Low Level Functions 3 10 Performing an Asynchronous Grab using Low Level Functions 3 10 Chapter 4 Programming with NI IMAQ for 1394 VIs Introduction 4 1 Location of NI IMAQ for 1394 Examples 4 2 Location of the NI IMAQ for 1394 VIs 4 2 Common NI IMAQ for 1394 VI Parameters 4 3 Buffer Management 4 4 NI IMAQ for 1394 Acquisition Types 4 5 Snap 4 5 Grab 4 5 Sequence 4 6 Ac...

Page 7: ... where to find sample programs About the NI IMAQ Software NI IMAQ for 1394 gives you the ability to use industrial digital video cameras with the NI IMAQ driver software and IMAQ Vision You can use cameras with the following output formats Monochrome 8 bits pixel Monochrome 16 bits pixel RGB 24 bits pixel YUV 4 1 1 12 bits pixel YUV 4 2 2 16 bits pixel YUV 4 4 4 24 bits pixel The cameras may opera...

Page 8: ... and higher Note Although NI IMAQ for 1394 has been tested and found to work with these ADEs other ADEs may also work Configuring Your IEEE 1394 Camera You can use National Instruments Measurement Automation Explorer MAX to configure your IEEE 1394 camera Set your camera s properties by right clicking on your camera in the IMAQ IEEE 1394 Devices folder in the MAX configuration tree Select Properti...

Page 9: ...tions 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 Figure 1 1 NI IMAQ for 1394 Architecture LabVIEW LabWindows CVI Visual C Borland IMAQ Vision IMAQ Vision IMAQ1394 DLL IMAQ1394 SYS 1394BUS SYS OCHI1394 SYS TILYNX SYS Application Level Kernel ...

Page 10: ... function declarations Your NI IMAQ for 1394 software kit contains function prototypes for all routines Creating an Application This section outlines the process for developing NI IMAQ for 1394 applications using C for Windows 2000 Me 98 Detailed instructions on creating project and source files are not included For information on creating and managing project files consult the documentation inclu...

Page 11: ... is C Program Files National Instruments NI IMAQ for IEEE 1394 You can find the include files under the include subdirectory The import libraries are located under the lib environment subdirectory for the following platforms Sample Programs Please refer to the readme txt file located in your target installation directory for the latest details on NI IMAQ for 1394 sample programs These programs are...

Page 12: ...ab functions Sequence functions Trigger functions Low level functions Acquisition functions Attribute functions Utility functions The generic and high level functions appear within each function class in the logical order you might need to use them The low level functions appear within each function class in alphabetical order Generic Functions Use generic functions in both high level and low leve...

Page 13: ...Vision memory management imaq1394Snap Performs a single frame acquisition in a memory buffer which is allocated without using IMAQ Vision memory management Grab Functions Grab functions start a continuous image acquisition to a user buffer Any frame or field can be copied from the grab buffer to another user buffer imaq1394SetupGrab Configures and starts a continuous acquisition imaq1394GrabImage ...

Page 14: ... the trigger mode of the IEEE 1394 camera imaq1394TriggerConfigure Configures an acquisition to start based on an external trigger Miscellaneous Functions Miscellaneous functions return information such as session status imaq1394Status Gets the current session status Low Level Functions Use low level functions when you require more direct control of the acquisition of the images Acquisition Functi...

Page 15: ...hronous acquisition and installs a callback function that will be called when an image is acquired Attribute Functions Use attribute functions to examine and change NI IMAQ or camera attributes imaq1394GetAttribute Returns an attribute for a session imaq1394SetAttribute Sets an attribute for a session imaq1394AttributeInquiry Queries the camera to check that it supports the specified attribute ima...

Page 16: ... 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 ...

Page 17: ...er your image acquisition process but you must understand the API and driver in greater detail Note The high level functions call low level functions and use certain attributes that are listed in the high level function description in the NI IMAQ for 1394 Function Reference online help Changing the value of these attributes while using low level functions will affect the operation of the high leve...

Page 18: ... cameras establish a connection to control access to and initialize hardware All parameters configured in MAX for an IMAQ 1394 device are associated with a camera name You can have one device associated with more than one camera name which allows you to have several different configurations for one device Use the camera name to refer to the IMAQ 1394 device in your programming environment Camera n...

Page 19: ...era it closes the camera using the imaq1394Close function For a complete list of the available camera functions refer to the NI IMAQ for IEEE 1394 Cameras online help Camera Attributes Use camera attributes 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 p...

Page 20: ... functions you must know the size of the image for the selected format and mode to allocate enough memory to contain the image You can obtain the size of the image using the Image Width and Image Height attributes Some IEEE 1394 cameras support the Scalable Image Format format 7 which allows you to define the size of the acquired image If you use this format you must input the image size using the...

Page 21: ...t create an image using imaqCreate and then pass that image to an acquisition function If you do not have IMAQ Vision installed on your computer you must manually allocate the memory for your image Use the attributes ImageWidth ImageHeight and BytesPerPixel to determine how much memory you should allocate Note You can find the code examples discussed in this section in the NI IMAQ for IEEE 1394 sa...

Page 22: ... session the ROI is set to the size of the video mode you selected in MAX The sample then calls a process function to analyze the image When the program is finished it calls imaq1394Close with the camera handle This instructs NI IMAQ to free all of the resources associated with this camera which releases the session High Level Grab Functions A grab is a continuous high speed acquisition of data to...

Page 23: ...on by calling the imaq1394Grab function The program then calculates the area to grab using the current ROI and bytes per pixel In this example the program allocates a user buffer for grabbing and passes this buffer to imaq1394Grab When the acquisition is complete it stops The program then frees the user buffer and all of the resources associated with this camera by calling imaq1394Close imaq1394Ca...

Page 24: ...Flowchart The Sequence1394 c example demonstrates how to perform a sequence acquisition using imaq1394SetupSequence The example sets up a sequence that uses 10 user allocated buffers 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 syn...

Page 25: ...sets up a continuous acquisition to a single user allocated buffer The program retrieves the acquisition window size of the selected camera and performs a calculation to determine the correct memory requirements of the user buffer The program then creates the buffer The main processing loop of the code shows how to copy the buffer to an analysis buffer Performing a Sequence Acquisition Using Low L...

Page 26: ...ntage of an asynchronous snap is that you can start the acquisition and then perform other tasks while waiting for the signal that the image is ready Note Since the callback function is called in a different thread than the main program you should make sure that all of your processing is thread safe Performing an Asynchronous Grab using Low Level Functions The Low LevelGrab1394 Async example demon...

Page 27: ... purchased the IMAQ Vision image processing and analysis libraries you can use the four IMAQ Vision VIs included with your NI IMAQ for 1394 software If you use these basic functions you can later upgrade your programs to use IMAQ Vision processing capabilities without any changes to your image acquisition VIs Before you start building your IMAQ application you should know the following basic IMAQ ...

Page 28: ...abview 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 Select the Motion and Vision palette and then select the Image Acquisition palette as shown in Figure 4 1...

Page 29: ...94 Grab Setup and IMAQ1394 Sequence require you to wire IMAQ1394 Session In only if you are using an interface other than the default cam0 if you are using multiple cameras or if you need to set IMAQ 1394 properties before the acquisition Many acquisition VIs require that you supply an image buffer to receive the captured image You can create this image buffer with the IMAQ Create VI Consult the B...

Page 30: ... with the current video mode it will automatically change to a compatible value New Image contains pointer information to the buffer which is initially empty When you wire New Image to the Image in input of an image acquisition VI the image acquisition VI allocates the correct amount of memory for the acquisition If you are going to process the image you might need to wire to Border Size Border Si...

Page 31: ...plications Figure 4 4 shows a simplified block diagram for using IMAQ1394 Snap Figure 4 4 Acquiring an Image Using Snap Grab A grab is a continuous high speed acquisition of data to a single buffer in host memory This function performs an acquisition that loops continually on one buffer You can get a copy of the acquisition buffer by grabbing a copy to a LabVIEW image buffer You must use two VIs I...

Page 32: ...d 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 IMAQ1394 Sequence starts acquires and releases a sequence acquisition The input Skip Table is an array containing the number of frames to ...

Page 33: ...cations VIs are included for snap grab and sequence as described in the NI IMAQ for 1394 Acquisition Types section of this chapter You can find examples of using the high level acquisition VIs in the examples imaq IMAQ1394examples llb file Low Level Use the low level acquisition VIs for more advanced image acquisition applications The low level VIs configure an acquisition start an acquisition ret...

Page 34: ...ents 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 Timeout specifies the amount of time in milliseconds to wait for the trigger Figure 4 7 shows how to use IMAQ1394 Configure Trigger to perform a snap acquisition based on a trigger Figure 4 7 IMAQ Triggering Image Display Many i...

Page 35: ...rol for RGB images Before you can properly display an image on an Intensity Graph you need to make some minor changes to the default properties of the Intensity Graph Perform the following steps to modify the properties 1 Place the Intensity Graph on the front panel pop up on the graph and choose Transpose Array 2 Create the correct grayscale color palette by popping up on the marker labeled 50 on...

Page 36: ...10 illustrates using an Intensity Graph to display an image acquired using IMAQ1394 Snap Figure 4 10 Displaying an Image Using an Intensity Graph To display an RGB image on a picture control place the picture control on the front panel of your VI Use the IMAQ ColorImageToArray VI to copy an image from an image buffer into a LabVIEW array Then you can wire this array to the Draw True Color Pixmap V...

Page 37: ... 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 The following attributes are defined in the IEEE 1394 Based Digital Camera Specifications Brightness Auto_Exposure Sharpness White_Balance Hue Saturation Gamma Shutter Gain Iris Focus Temperature Zoom Pan Tilt and Optical Filter To modify these attr...

Page 38: ...n error the VI passes the error information to error out and does not execute any NI IMAQ for 1394 function Figure 4 12 Error Clusters You can use the Simple Error Handler VI Functions Time Dialog palette to check for errors that occur while executing a VI If you wire an error cluster to the Simple Error Handler VI the VI deciphers the error information and displays a dialog box that describes the...

Page 39: ...s TRUE code is a non zero error code If status is FALSE code can be zero or a warning code 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...

Page 40: ...arning 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 ...

Page 41: ...ly access the latest example programs system configurators tutorials technical news as well as a community of developers ready to share their own techniques Customer Education National Instruments provides a number of alternatives to satisfy your training needs from self paced tutorials videos and interactive CDs to instructor led hands on courses at locations around the world Visit the Customer E...

Page 42: ...ffice 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 If you have searched the technical support resources on our Web site and still cannot find the answers you need contact your local office or National Instruments corporate Phone numbers for our worldwide offices are li...

Page 43: ...me or field is completed AQ_IN_PROGRESS Signals that the acquisition of video data is in progress 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 B b Bit One binary digit either 0 or 1 B Byte Eight related bits of dat...

Page 44: ...and measuring electrical signals from sensors transducers and test probes or fixtures and inputting them to a computer for processing 2 Collecting and measuring the same kinds of electrical signals with A D or DIO boards plugged into a computer and possibly generating control signals with D A and or DIO boards in the same computer default setting A default parameter value recorded in the driver In...

Page 45: ...le line of code that may have input and or output parameters and returns a value when executed G gamma The nonlinear change in the difference between the video signal s brightness level and the voltage level needed to produce that brightness GUI Graphical user interface An intuitive easy to use means of communicating information to and from a computer program by means of graphical screen displays ...

Page 46: ... number of lines in a field are half the number of lines in an interlaced frame interpreter A software utility that executes source code from a high level language such as Basic C or Pascal by reading one line at a time and executing the specified operation See also compiler K k Kilo The standard metric prefix for 1 000 or 103 used with units of measure such as volts hertz and meters K Kilo The pr...

Page 47: ...n used with units of measure such as volts and hertz 2 Mega the prefix for 1 048 576 or 220 when used with B to quantify data or computer memory MB Megabyte of memory Mbytes s A unit for data transfer that means 1 million or 106 bytes s memory buffer See buffer memory window Continuous blocks of memory that can be accessed quickly by changing addresses on the local processor MSB Most significant b...

Page 48: ...3 pixel Picture element The smallest division that makes up the video scan line For display on a computer monitor a pixel s optimum dimension is square aspect ratio of 1 1 or the width equal to the height pixel aspect ratio The ratio between the physical horizontal size and the vertical size of the region covered by the pixel An acquired pixel should optimally be square thus the optimal value is 1...

Page 49: ...B color information where each pixel in the color image is encoded using 32 bits 8 bits for red 8 bits for green 8 bits for blue and 8 bits for the alpha value unused ROI Region of interest 1 An area of the image that is graphically selected from a window displaying the image This area can be used focus further processing 2 A hardware programmable rectangular portion of the acquisition window ROM ...

Page 50: ...ctionality 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 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 ...

Page 51: ...tributes in C and C 3 3 using camera attributes in LabVIEW 4 11 camera configuration 1 2 camera functions 3 2 conventions iv customer education B 1 E error code format 4 13 to 4 14 error handling 4 12 example programs location of files 1 5 examples advanced programming examples 3 9 to 3 10 introductory programming examples 3 5 to 3 8 F features and overview 1 1 G generic functions 2 1 grab functio...

Page 52: ...evel functions 3 1 introduction to programming with NI IMAQ for 1394 3 1 low level functions 3 2 programming environments supported by NI IMAQ for 1394 software 1 2 programming with NI IMAQ for 1394 VIs 4 4 buffer management 4 4 examples 4 2 introduction 4 1 location 4 2 parameters 4 3 S scalable image size 3 4 sequence functions 2 3 snap functions 2 2 system integration by National Instruments B ...