National Instruments NI-IMAQdx User Manual
NI-IMAQdx
NI-IMAQdx User Manual
Image Acquisition Software
NI-IMAQdx User Manual
TM
February 2007
371970B-01
Support
Worldwide Technical Support and Product Information
ni.com
National Instruments Corporate Headquarters
11500 North Mopac Expressway Austin, Texas 78759-3504 USA Tel: 512 683 0100
Worldwide Offices
Australia 1800 300 800, Austria 43 662 457990-0, Belgium 32 (0) 2 757 0020, Brazil 55 11 3262 3599,
Canada 800 433 3488, China 86 21 6555 7838, Czech Republic 420 224 235 774, Denmark 45 45 76 26 00,
Finland 385 (0) 9 725 72511, France 33 (0) 1 48 14 24 24, Germany 49 89 7413130, India 91 80 41190000,
Israel 972 3 6393737, Italy 39 02 413091, Japan 81 3 5472 2970, Korea 82 02 3451 3400,
Lebanon 961 (0) 1 33 28 28, Malaysia 1800 887710, Mexico 01 800 010 0793, Netherlands 31 (0) 348 433 466,
New Zealand 0800 553 322, Norway 47 (0) 66 90 76 60, Poland 48 22 3390150, Portugal 351 210 311 210,
Russia 7 495 783 6851, Singapore 1800 226 5886, Slovenia 386 3 425 42 00, South Africa 27 0 11 805 8197,
Spain 34 91 640 0085, Sweden 46 (0) 8 587 895 00, Switzerland 41 56 2005151, Taiwan 886 02 2377 2222,
Thailand 662 278 6777, Turkey 90 212 279 3031, United Kingdom 44 (0) 1635 523545
For further support information, refer to the Technical Support and Professional Services appendix. To comment
on National Instruments documentation, refer to the National Instruments Web site at ni.com/info and enter
the info code feedback.
© 2006–2007 National Instruments Corporation. All rights reserved.
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. National Instruments does not warrant that the operation of the software shall be
uninterrupted or error free.
A Return Material Authorization (RMA) number must be obtained from the factory and clearly marked on the outside of the package before
any equipment will be accepted for warranty work. National Instruments will pay the shipping costs of returning to the owner parts which are
covered by warranty.
National Instruments believes that the information in this document is accurate. The document has been carefully reviewed for technical
accuracy. In the event that technical or typographical errors exist, National Instruments reserves the right to make changes to subsequent
editions of this document without prior notice to holders of this edition. The reader should consult National Instruments if errors are suspected.
In no event shall National Instruments be liable for any damages arising out of or related to this document or the information contained in it.
E
XCEPT AS SPECIFIED HEREIN, NATIONAL INSTRUMENTS MAKES NO WARRANTIES, EXPRESS OR IMPLIED, AND SPECIFICALLY DISCLAIMS ANY WARRANTY OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE . CUSTOMER’S RIGHT TO RECOVER DAMAGES CAUSED BY FAULT OR NEGLIGENCE ON THE PART OF
N
ATIONAL INSTRUMENTS SHALL BE LIMITED TO THE AMOUNT THERETOFORE PAID BY THE CUSTOMER. NATIONAL INSTRUMENTS WILL NOT BE LIABLE FOR
DAMAGES RESULTING FROM LOSS OF DATA, PROFITS, USE OF PRODUCTS, OR INCIDENTAL OR CONSEQUENTIAL DAMAGES, EVEN IF ADVISED OF THE POSS IBILITY
THEREOF. This limitation of the liability of National Instruments will apply regardless of the form of action, whether in contract or tort, including
negligence. Any action against National Instruments must be brought within one year after the cause of action accrues. National Instruments
shall not be liable for any delay in performance due to causes beyond its reasonable control. The warranty provided herein does not cover
damages, defects, malfunctions, or service failures caused by owner’s failure to follow the National Instruments installation, operation, or
maintenance instructions; owner’s modification of the product; 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, without the prior written consent of National
Instruments Corporation.
National Instruments respects the intellectual property of others, and we ask our users to do the same. NI software is protected by copyright
and other intellectual property laws. Where NI software may be used to reproduce software or other materials belonging to others, you may
use NI software only to reproduce materials that you may reproduce in accordance with the terms of any applicable license or other legal
restriction.
Trademarks
National Instruments, NI, ni.com, and LabVIEW are trademarks of National Instruments Corporation. Refer to the Terms of Use section
on ni.com/legal for more information about National Instruments trademarks.
Other product and company names mentioned herein are trademarks or trade names of their respective companies.
Members of the National Instruments Alliance Partner Program are business entities independent from National Instruments and have no
agency, partnership, or joint-venture relationship with National Instruments.
Patents
For patents covering National Instruments products, refer to the appropriate location: Help»Patents in your software, the patents.txt file
on your CD, or
ni.com/patents.
WARNING REGARDING USE OF NATIONAL INSTRUMENTS PRODUCTS
(1) NATIONAL INSTRUMENTS PRODUCTS ARE NOT DESIGNED WITH COMPONENTS AND TESTING FOR A LEVEL OF
RELIABILITY SUITABLE FOR USE IN OR IN CONNECTION WITH SURGICAL IMPLANTS OR AS CRITICAL COMPONENTS IN
ANY LIFE SUPPORT SYSTEMS WHOSE FAILURE TO PERFORM CAN REASONABLY BE EXPECTED TO CAUSE SIGNIFICANT
INJURY TO A HUMAN.
(2) IN ANY APPLICATION, INCLUDING THE ABOVE, RELIABILITY OF OPERATION OF THE SOFTWARE PRODUCTS CAN BE
IMPAIRED BY ADVERSE FACTORS, INCLUDING BUT NOT LIMITED TO FLUCTUATIONS IN ELECTRICAL POWER SUPPLY,
COMPUTER HARDWARE MALFUNCTIONS, COMPUTER OPERATING SYSTEM SOFTWARE FITNESS, FITNESS OF COMPILERS
AND DEVELOPMENT SOFTWARE USED TO DEVELOP AN APPLICATION, INSTALLATION ERRORS, SOFTWARE AND
HARDWARE COMPATIBILITY PROBLEMS, MALFUNCTIONS OR FAILURES OF ELECTRONIC MONITORING OR CONTROL
DEVICES, TRANSIENT FAILURES OF ELECTRONIC SYSTEMS (HARDWARE AND/OR SOFTWARE), UNANTICIPATED USES OR
MISUSES, OR ERRORS ON THE PART OF THE USER OR APPLICATIONS DESIGNER (ADVERSE FACTORS SUCH AS THESE ARE
HEREAFTER COLLECTIVELY TERMED “SYSTEM FAILURES”). ANY APPLICATION WHERE A SYSTEM FAILURE WOULD
CREATE A RISK OF HARM TO PROPERTY OR PERSONS (INCLUDING THE RISK OF BODILY INJURY AND DEATH) SHOULD
NOT BE RELIANT SOLELY UPON ONE FORM OF ELECTRONIC SYSTEM DUE TO THE RISK OF SYSTEM FAILURE. TO AVOID
DAMAGE, INJURY, OR DEATH, THE USER OR APPLICATION DESIGNER MUST TAKE REASONABLY PRUDENT STEPS TO
PROTECT AGAINST SYSTEM FAILURES, INCLUDING BUT NOT LIMITED TO BACK-UP OR SHUT DOWN MECHANISMS.
BECAUSE EACH END-USER SYSTEM IS CUSTOMIZED AND DIFFERS FROM NATIONAL INSTRUMENTS' TESTING
PLATFORMS AND BECAUSE A USER OR APPLICATION DESIGNER MAY USE NATIONAL INSTRUMENTS PRODUCTS IN
COMBINATION WITH OTHER PRODUCTS IN A MANNER NOT EVALUATED OR CONTEMPLATED BY NATIONAL
INSTRUMENTS, THE USER OR APPLICATION DESIGNER IS ULTIMATELY RESPONSIBLE FOR VERIFYING AND VALIDATING
THE SUITABILITY OF NATIONAL INSTRUMENTS PRODUCTS WHENEVER NATIONAL INSTRUMENTS PRODUCTS ARE
INCORPORATED IN A SYSTEM OR APPLICATION, INCLUDING, WITHOUT LIMITATION, THE APPROPRIATE DESIGN,
PROCESS AND SAFETY LEVEL OF SUCH SYSTEM OR APPLICATION.
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.
bold Bold text denotes items that you must select or click in the software, such
as menu items and dialog box options. Bold text also denotes parameter
names.
italic Italic text denotes variables, emphasis, a cross-reference, or an introduction
to a key concept. Italic text 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, directories,
programs, subprograms, subroutines, device names, functions, operations,
variables, filenames, and extensions.
monospace bold Bold text in this font denotes the messages and responses that the computer
automatically prints to the screen. This font also emphasizes lines of code
that are different from the other examples.
monospace italic
Italic text in this font denotes text that is a placeholder for a word or value
that you must supply.
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 .....................................................................................................1-3
NI-IMAQdx Libraries .....................................................................................1-4
Example Programs...........................................................................................1-4
Chapter 2
Basic Acquisition with NI-IMAQdx
Introduction....................................................................................................................2-1
Acquisition Flow............................................................................................................2-2
Opening a Camera ...........................................................................................2-2
Camera Name....................................................................................2-3
Camera Control Mode.......................................................................2-4
Configure the Acquisition ...............................................................................2-4
One-Shot/Continuous Acquisition ....................................................2-4
Number of Buffers ............................................................................2-5
Region of Interest..............................................................................2-5
Pixel Format......................................................................................2-6
Acquisition ......................................................................................................2-6
User Buffer........................................................................................2-6
Buffer Number Mode........................................................................2-7
Buffer Number ..................................................................................2-7
Overwrite Mode ................................................................................2-7
Timeouts............................................................................................2-8
Decoding ...........................................................................................2-8
Programming Examples.................................................................................................2-9
High-Level Function Examples.......................................................................2-9
Snap...................................................................................................2-9
Grab...................................................................................................2-10
Sequence ...........................................................................................2-11
Low-Level Function Examples .......................................................................2-11
Snap...................................................................................................2-12
Grab...................................................................................................2-13
Sequence ...........................................................................................2-14
© National Instruments Corporation v NI-IMAQdx User Manual
Contents
Chapter 3
Advanced Programming with NI-IMAQdx
Camera Attributes.......................................................................................................... 3-1
Attribute Name................................................................................................ 3-1
Attribute Type .................................................................................................3-2
Attribute Value................................................................................................ 3-2
Attribute Access.............................................................................................. 3-3
Attribute Range ............................................................................................... 3-3
Broadcasting .................................................................................................................. 3-4
Implementation ............................................................................................... 3-5
Scalable Image Size....................................................................................................... 3-6
Trigger Modes ............................................................................................................... 3-7
Trigger Modes for IIDC Cameras................................................................... 3-7
Trigger Mode 0................................................................................. 3-8
Trigger Mode 1................................................................................. 3-8
Trigger Mode 2................................................................................. 3-9
Trigger Mode 3................................................................................. 3-9
Trigger Mode 4................................................................................. 3-10
Trigger Mode 5................................................................................. 3-10
Trigger Modes for GigE Vision Cameras ....................................................... 3-11
Chapter 4
Using NI-IMAQdx in LabVIEW
Introduction ................................................................................................................... 4-1
Location of the NI-IMAQdx VIs................................................................................... 4-1
Common VI Parameters ................................................................................................ 4-2
IMAQdx Session............................................................................................. 4-2
Image Buffer ................................................................................................... 4-2
Acquisition VIs.............................................................................................................. 4-3
High-Level ...................................................................................................... 4-3
Low-Level....................................................................................................... 4-3
Buffer Management....................................................................................................... 4-4
Acquisition Types.......................................................................................................... 4-5
Snap................................................................................................................. 4-5
Grab................................................................................................................. 4-5
Sequence ......................................................................................................... 4-6
Image Display................................................................................................................ 4-7
Camera Attributes.......................................................................................................... 4-8
Error Handling............................................................................................................... 4-9
NI-IMAQdx User Manual vi ni.com
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 ..................................................................5-2
Appendix A
Register-Level Programming
Appendix B
Technical Support and Professional Services
Glossary
Index
Contents
© National Instruments Corporation vii NI-IMAQdx User Manual
Introduction to NI-IMAQdx
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. You can
use cameras with the following output formats:
• Monochrome (8–16 bits/pixel)
• RGB (24–48 bits/pixel)
• YUV 4:1:1 (12 bits/pixel)
• YUV 4:2:2 (16 bits/pixel)
• YUV 4:4:4 (24 bits/pixel)
• Bayer (8–16 bits/pixel)
1
The cameras may operate at various resolutions and frame rates, depending
on camera capabilities.
NI-IMAQdx complies with the Automated Imaging Association GigE
Vision specification and the 1394 Trade Association Industrial and
Instrumentation specification for Digital Cameras (IIDC), and controls
all available modes and features of the digital camera.
Note Refer to the NI Vision Acquisition Software Release Notes for the specific version of
the IIDC specification or the GigE Vision specification to which this driver complies.
© National Instruments Corporation 1-1 NI-IMAQdx User Manual
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
• Microsoft Visual C/C++ version 6.0 and later
• Microsoft Visual Basic version 6.0 and later
• Microsoft Visual Studio .NET 2003 and later
Note Although the NI-IMAQdx software has been tested and found to work with these
ADEs, other ADEs may also work.
™
/CVI™ version 7.0 and later
Configuring Your Camera
Use National Instruments Measurement & Automation Explorer (MAX) to
configure your camera. Refer to the Measurement & Automation Explorer
Help for NI-IMAQdx for information about configuring your camera. You
can access the Measurement & Automation Explorer Help for NI-IMAQdx
from within MAX by going to Help»Help Topics»NI-IMAQdx.
The camera configuration is saved in a camera file, which the NI-IMAQdx
VIs and functions use to configure a camera and supported attributes.
NI-IMAQdx User Manual 1-2 ni.com
Chapter 1 Introduction to NI-IMAQdx
Fundamentals of Building Applications with NI-IMAQdx
Architecture
Figure 1-1 illustrates the NI-IMAQdx driver architecture.
LabVIEW
NIIMAQDX.DLL
Application Level
Kernel Level
NIIMAQDXK.DLL
Windows Kernel
NIPALK.SYS
1
OCHI1394.SYS
1394BUS.SYS
1
Components provided by the underlying operating system.
TCPIP.SYS
NDIS.SYS
NIGEV.SYS
LabWindows/CVI
Visual C++
LabVIEW RT Kernel
1
11
NIPALP.DLL
TNF.DLL
Figure 1-1. NI-IMAQdx Architecture
The architecture uses a hardware abstraction layer, which separates
software API capabilities, such as general acquisition and control
functions, from hardware-specific information. This layer lets you run
your application on different operating systems and use updated versions
of the driver without having to recompile your application.
© National Instruments Corporation 1-3 NI-IMAQdx User Manual
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. Depending
on the development tools you use, you can give the DLL routines
information through import libraries or through function declarations.
Your NI-IMAQdx software contains function prototypes for all routines.
Example Programs
You can find NI-IMAQdx code examples in the following directories.
Note If you installed NI-IMAQdx in the default location, you can find the following
example directories within
C:\Program Files\National Instruments.
•LabVIEW—
LabVIEW\examples\imaq. For a brief description of
any example VI, open the VI, and select Windows»Show VI Info for
a text description of the example.
Tip You can access the NI-IMAQdx examples from the NI Example Finder. From
LabVIEW, go to Help»Find Examples to launch the NI Example Finder.
•CVI—
•C—
• Visual Basic—
• Microsoft Visual Studio .NET 2003—
CVI\samples\imaqdx.
NI-IMAQdx\examples\MSVC.
NI-IMAQdx\examples\VB.
MSVB.NET
. The .NET examples are converted from the NI-IMAQdx
NI-IMAQdx\examples\
for Visual Basic examples. The .NET examples are written in Visual
Basic .NET and demonstrate use of the NI-IMAQdx 3.0 Assemblies
and the IMAQ Vision 8.2 Viewer control.
Refer to the
readme.rtf file located in your target installation directory
for the latest details about the example programs.
NI-IMAQdx User Manual 1-4 ni.com
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.
• High-level functions—Use to capture images quickly and easily.
If you need more advanced functionality, you can mix high-level
functions with low-level functions.
– Snap functions—Capture all or a portion of a single image to the
user buffer.
– Grab functions—Perform an acquisition that loops continually on
one or more internal buffers. You can copy the last acquired buffer
to a separate user buffer for processing or analysis.
– Sequence functions—Acquire a specified number of internal
buffers and then stops.
• Low-level functions—Use when you require more direct control of the
image acquisition.
– Acquisition functions—Configure, start, stop, and unconfigure an
image acquisition, or examine a user buffer during an acquisition.
– Attribute functions—Examine and change the acquisition or
camera attributes.
– Event functions—Register events.
– Register functions—Access registers.
– Session functions—Open, close, or enumerate sessions.
– Utility functions—Get detailed error information.
2
© National Instruments Corporation 2-1 NI-IMAQdx User Manual
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.
Note The high-level functions call low-level functions and use certain attributes that are
listed in the high-level function description of the NI-IMAQdx Function Reference Help.
Changing the value of these attributes while using low-level functions affects the operation
of the high-level functions.
Acquisition Flow
This section describes the basic steps of performing an acquisition with the
NI-IMAQdx software. The basic steps are initialization, configuration, and
acquisition.
Opening a Camera
To acquire images using the high-level or low-level functions, you first
must open a camera session. A camera session is a process-safe handle to
a camera. The driver uses a camera session to identify the camera to which
further NI-IMAQdx functions apply. You can simultaneously open as many
camera sessions as there are cameras connected to your system.
When opening the camera session, you need to specify two parameters:
camera name and camera control mode. Refer to the following sections for
detailed information about these parameters. When an application is
finished with the camera, call the Close Camera function to close the
camera session.
NI-IMAQdx User Manual 2-2 ni.com
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
cam1
Device 0
Device 1
... ...
cam
n
Every camera has an
.iid interface file and an .icd camera file.
Device n
• 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. Camera files can
be shared between identical cameras. Use MAX to configure the
default state of a particular camera.
Figure 2-1 shows the relationship between cameras, interface files, and
camera files.
MyCam.icdCam0.iid
or
Default.icdCam1.iid
Figure 2-1. Relationship Between Cameras, Interface Files, and Camera Files
Note
Use the Enumerate function to query the number and names of available cameras.
Use the Discover Ethernet Cameras function to find ethernet cameras on the network with
a remote subnet.
© National Instruments Corporation 2-3 NI-IMAQdx User Manual
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
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. The camera file described by
the interface file opens, and all the user attributes are set in the driver. If no
camera of the same make and model is present, the Camera Open 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. Refer to the Broadcasting section of Chapter 3,
Advanced Programming with NI-IMAQdx, for more information about
broadcasting.
Configure the Acquisition
After opening the camera, configure the camera for acquisition by
specifying the following parameters: whether the acquisition is one-shot
or continuous, and the number of internal buffers to use.
n
is the reference to the camera. If the camera
While configuring the camera, the driver validates all the user-configurable
attributes. If any attributes are invalid or out of range, the driver returns an
error and does not configure the acquisition.
If you want to reconfigure the acquisition, call the Unconfigure Acquisition
function before calling the Configure function again.
Note National Instruments recommends that you do not configure an acquisition in a loop
because doing so is time-intensive.
One-Shot/Continuous Acquisition
Use a one-shot acquisition to start an acquisition, perform the acquisition,
and stop the acquisition using a single function. The number of images
acquired is equal to the number of images in the images collection.
With a one-shot acquisition, you specify a certain number of internal
buffers. The camera transfers each image up to and including the specified
number of buffers. The driver acquires every image during a one-shot
NI-IMAQdx User Manual 2-4 ni.com
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. 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.
Number of Buffers
Another aspect of configuration is specifying the number of internal buffers
into which you want to acquire image data. During configuration, buffers
are allocated from system memory and page-locked. Once the acquisition
starts, the camera transfers video data over the IEEE 1394 bus to the
IEEE 1394 interface card FIFO. Then, video data is directly transferred to
the internal buffer. This transfer requires negligible CPU resources. For the
GigE Vision bus, CPU resources are used to pass network packets. For
ethernet, ethernet packets are evaluated by software and copied into an
internal buffer.
Each internal buffer you allocate is the exact size of the raw data being
transmitted by the camera. For continuous acquisitions, allocate three or
more buffers. Allocating a single buffer for a continuous acquisition may
result in a high number of lost images. For one-shot acquisitions, specify
the number of buffers that the application requires. For example, if the
application runs for two seconds, and the camera acquires at 30 frames
per second, allocate 60 buffers to capture each image.
Having more buffers available for the GigE Vision bus can increase the
reliability of data transfer, especially when there are adverse network
conditions.
Region of Interest
The region of interest (ROI) specifies a rectangular portion of the image to
be captured. If the camera supports scalable video modes, the ROI defines
the portion of the image to transfer from the camera to system memory.
If the camera does not support scalable video modes, the entire image is
© National Instruments Corporation 2-5 NI-IMAQdx User Manual
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. Specify a smaller ROI for
the following reasons:
• To acquire only the necessary subset of data
• To increase the acquisition speed by reducing the amount of data
transferred and/or decoded
• To allow for multiple simultaneous acquisitions by reducing
bandwidth usage
Note Although you can specify an ROI of any size, the NI-IMAQdx software coerces the
ROI into one that is more compatible for the given camera. Refer to Chapter 3, Advanced
Programming with NI-IMAQdx, for more information about defining an ROI for scalable
images.
Pixel Format
The pixel format specifies the source type of the image format. Different
pixel formats decode into different image types. Refer to the Decoding
section for more information.
Acquisition
After configuring and starting your acquisition, the camera sends data to
the internal buffers. To process the acquired image data, you must copy the
data from the internal buffer into your user buffer.
User Buffer
Before starting the acquisition, you must allocate a user buffer in addition
to configuring internal buffers. The driver copies or decodes image data
from the internal buffer into the user buffer during acquisition. Then,
process and analyze the image in the user buffer.
When acquiring data into an image, the driver resizes and casts the image
as needed. However, if you acquire data into a user buffer, you must allocate
enough space for one decoded image.
Note Unlike internal buffers, you are responsible for destroying user buffers.
NI-IMAQdx User Manual 2-6 ni.com
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. For example, during a continuous acquisition with
three internal buffers, the buffer number is updated as follows: 0, 1, 2, 3, 4,
5, and so on. Buffer numbers 0 and 3 refer to the same internal buffer in the
buffer ring.
For a one-shot acquisition, you can request only one of the available buffer
numbers. For a continuous acquisition, you can request any present or
future buffer number. You can also request the next logical buffer or the
buffer containing the most recently acquired data. With high-level grab
acquisitions, the buffer number defaults to the next transferred buffer.
When you complete the buffer acquisition step, the driver returns the actual
buffer number with the image.
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. However, if a
delay becomes too long, the camera overwrites the requested buffer with
new image data.
NI-IMAQdx is able to detect overwritten internal buffers. You can configure
the driver to manage an overwritten buffer in one of the following ways:
• Get newest valid buffer
• Get oldest valid buffer
• Fail and return an error
In all cases, the camera continues to transfer data when a buffer is
overwritten.
© National Instruments Corporation 2-7 NI-IMAQdx User Manual
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. If your application requires that every image be
processed, configure the driver to fail when a buffer is overwritten so that
you are alerted.
Timeouts
A timeout is the length of time, in milliseconds, that the driver waits for an
image from the camera before returning an error. A timeout error usually
occurs if the camera has been removed from the system or when the camera
did not receive an external trigger signal.
Decoding
Except for 8-bit monochrome images, all video modes require decoding
before you can interpret the image data. For example, many color cameras
output images of type YUV 4:2:2. However, NI Vision does not natively
support the YUV mode. To process and display the image, the driver
automatically decodes the YUV image into a 32-bit RGB image.
Table 2-2 lists common video modes and their corresponding image types
after being decoded by NI-IMAQdx.
Table 2-2. Decoder Inputs and Corresponding Outputs
Raw Camera Output Decoded Destination Image Type
8-bit monochrome Image_U8
10–16-bit monochrome Image_I16
YUV 4:1:1 Image_RGB
YUV 4:2:2 Image_RGB
YUV 4:4:4 Image_RGB
24-bit RGB Image_RGB
30–48-bit RGB Image_RGB_U64
8-bit Bayer Image_RGB
10–16-bit Bayer Image_RGB
NI-IMAQdx User Manual 2-8 ni.com
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.
High-Level Function Examples
Use high-level functions to write programs quickly without having to learn
the details of the low-level API and driver.
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.
Chapter 2 Basic Acquisition with NI-IMAQdx
Open
Snap
User-Specific Functions
Close
Figure 2-2. High-Level Snap Flowchart
Opens and configures camera
Acquires image into buffer
Executes user-specific image
processing
Closes the camera session
Use a snap for low-speed or one-shot applications where ease of
programming is essential. When you invoke a snap, the driver opens
a session on a camera and initializes the camera. Opening a session
sets the ROI to the size of the settings you configured in MAX.
© National Instruments Corporation 2-9 NI-IMAQdx User Manual
Loading...