image acquisition toolbox 3

Image Acquisition Toolbox 3Users Guide

Downloaded from www.Manualslib.com manuals search engine

How to Contact The MathWorks

www.mathworks.com Webcomp.soft-sys.matlab Newsgroupwww.mathworks.com/contact_TS.html Technical [email protected] Product enhancement [email protected] Bug [email protected] Documentation error [email protected] Order status, license renewals, [email protected] Sales, pricing, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc.3 Apple Hill DriveNatick, MA 01760-2098For contact information about worldwide offices, see the MathWorks Web site.Image Acquisition Toolbox Users Guide COPYRIGHT 20032010 by The MathWorks, Inc.The software described in this document is furnished under a license agreement. The software may be usedor copied only under the terms of the license agreement. No part of this manual may be photocopied orreproduced in any form without prior written consent from The MathWorks, Inc.FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentationby, for, or through the federal government of the United States. By accepting delivery of the Programor Documentation, the government hereby agrees that this software or documentation qualifies ascommercial computer software or commercial computer software documentation as such terms are usedor defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms andconditions of this Agreement and only those rights specified in this Agreement, shall pertain to and governthe use, modification, reproduction, release, performance, display, and disclosure of the Program andDocumentation by the federal government (or other entity acquiring for or through the federal government)and shall supersede any conflicting contractual terms or conditions. If this License fails to meet thegovernments needs or is inconsistent in any respect with federal procurement law, the government agreesto return the Program and Documentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. Seewww.mathworks.com/trademarks for a list of additional trademarks. Other product or brandnames may be trademarks or registered trademarks of their respective holders.Patents

The MathWorks products are protected by one or more U.S. patents. Please seewww.mathworks.com/patents for more information.


Revision HistoryMarch 2003 First printing New for Version 1.0 (Release 13+)September 2003 Online only Revised for Version 1.1 (Release 13SP1)June 2004 Online only Revised for Version 1.5 (Release 14)July 2004 Online only Revised for Version 1.6 (Release 14+)October 2004 Online only Revised for Version 1.7 (Release 14SP1)March 2005 Online only Revised for Version 1.8 (Release 14SP2)March 2005 Second printing Minor Revision for Version 1.8August 2005 Third printing Minor Revision for Version 1.8September 2005 Online only Revised for Version 1.9 (Release 14SP3)March 2006 Fourth printing Revised for Version 1.10 (Release 2006a)September 2006 Online only Revised for Version 2.0 (Release 2006b)March 2007 Online only Revised for Version 2.1 (Release 2007a)September 2007 Fifth printing Revised for Version 3.0 (Release 2007b)March 2008 Online only Revised for Version 3.1 (Release 2008a)October 2008 Online only Revised for Version 3.2 (Release 2008b)March 2009 Online only Revised for Version 3.3 (Release 2009a)September 2009 Online only Revised for Version 3.4 (Release 2009b)March 2010 Online only Revised for Version 3.5 (Release 2010a)


Contents

Getting Started

1Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2Installation and Configuration Notes . . . . . . . . . . . . . . . . . 1-3The Image Processing Toolbox Software Required to Usethe Image Acquisition Toolbox Software . . . . . . . . . . . . . 1-3

Related Products . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4Supported Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4

Image Acquisition Tool (GUI) . . . . . . . . . . . . . . . . . . . . . . . 1-5

Basic Image Acquisition Procedure . . . . . . . . . . . . . . . . . 1-6Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-6Step 1: Install Your Image Acquisition Device . . . . . . . . . . 1-7Step 2: Retrieve Hardware Information . . . . . . . . . . . . . . . 1-8Step 3: Create a Video Input Object . . . . . . . . . . . . . . . . . . 1-10Step 4: Preview the Video Stream (Optional) . . . . . . . . . . . 1-12Step 5: Configure Object Properties (Optional) . . . . . . . . . . 1-14Step 6: Acquire Image Data . . . . . . . . . . . . . . . . . . . . . . . . . 1-17Step 7: Clean Up . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-21

Introduction2

Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-2Toolbox Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3The Image Processing Toolbox Software Required to Usethe Image Acquisition Toolbox Software . . . . . . . . . . . . . 2-4

The Image Acquisition Tool (GUI) . . . . . . . . . . . . . . . . . . . . 2-4Supported Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-4

v


Setting Up Image Acquisition Hardware . . . . . . . . . . . . . 2-6Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Setting Up Frame Grabbers . . . . . . . . . . . . . . . . . . . . . . . . . 2-6Setting Up Generic Windows Video Acquisition Devices . . 2-7Setting Up DCAM Devices . . . . . . . . . . . . . . . . . . . . . . . . . . 2-7Resetting Your Image Acquisition Hardware . . . . . . . . . . . 2-7A Note About Frame Rates and Processing Speed . . . . . . . 2-7

Previewing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-9Opening a Video Preview Window . . . . . . . . . . . . . . . . . . . . 2-10Stopping the Preview Video Stream . . . . . . . . . . . . . . . . . . 2-11Closing a Video Preview Window . . . . . . . . . . . . . . . . . . . . . 2-12Previewing Data in Custom GUIs . . . . . . . . . . . . . . . . . . . . 2-12Performing Custom Processing of Previewed Data . . . . . . . 2-14

Using the Image Acquisition Tool GUI

3The Image Acquisition Tool Desktop . . . . . . . . . . . . . . . . 3-2Opening the Tool . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2Parts of the Desktop . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-2

Selecting Your Device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-5Selecting a Device and Format . . . . . . . . . . . . . . . . . . . . . . . 3-5Adding New Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-6Using a Camera File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7

Setting Acquisition Parameters . . . . . . . . . . . . . . . . . . . . . 3-8Using the Acquisition Parameters Pane . . . . . . . . . . . . . . . 3-8Setting Frames Per Trigger . . . . . . . . . . . . . . . . . . . . . . . . . 3-9Setting the Color Space . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-10Setting Device-Specific Parameters . . . . . . . . . . . . . . . . . . . 3-10Logging Your Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-13Setting Up Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-15Setting a Region of Interest . . . . . . . . . . . . . . . . . . . . . . . . . 3-18Restoring Default Parameters . . . . . . . . . . . . . . . . . . . . . . . 3-24

Previewing and Acquiring Data . . . . . . . . . . . . . . . . . . . . . 3-25

vi Contents


The Preview Window . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-25Previewing Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-27Acquiring Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-28

Exporting Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-32

Saving Image Acquisition Tool Configurations . . . . . . . 3-35

Exporting Hardware Configurations to MATLAB . . . . . 3-37

Saving and Copying the Session Log . . . . . . . . . . . . . . . . 3-39About the Session Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39Saving the Session Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-39Copying the Session Log . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-40

Registering a Third-Party Adaptor . . . . . . . . . . . . . . . . . . 3-42

Connecting to Hardware

4Getting Hardware Information . . . . . . . . . . . . . . . . . . . . . 4-2Getting Hardware Information . . . . . . . . . . . . . . . . . . . . . . 4-2Determining the Device Adaptor Name . . . . . . . . . . . . . . . . 4-2Determining the Device ID . . . . . . . . . . . . . . . . . . . . . . . . . . 4-3Determining Supported Video Formats . . . . . . . . . . . . . . . . 4-5

Creating Image Acquisition Objects . . . . . . . . . . . . . . . . . 4-8Types of Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Video Input Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Video Source Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-8Creating a Video Input Object . . . . . . . . . . . . . . . . . . . . . . . 4-9Specifying the Video Format . . . . . . . . . . . . . . . . . . . . . . . . 4-11Specifying the Selected Video Source Object . . . . . . . . . . . . 4-14Getting Information About a Video Input Object . . . . . . . . 4-15

Configuring Image Acquisition Object Properties . . . . 4-16About Image Acquisition Object Properties . . . . . . . . . . . . . 4-16

vii


Viewing the Values of Object Properties . . . . . . . . . . . . . . . 4-17Viewing the Value of a Particular Property . . . . . . . . . . . . 4-19Getting Information About Object Properties . . . . . . . . . . . 4-20Setting the Value of an Object Property . . . . . . . . . . . . . . . 4-20

Starting and Stopping a Video Input Object . . . . . . . . . . 4-23

Deleting Image Acquisition Objects . . . . . . . . . . . . . . . . . 4-27

Saving Image Acquisition Objects . . . . . . . . . . . . . . . . . . . 4-29Using the save Command . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-29Using the obj2mfile Command . . . . . . . . . . . . . . . . . . . . . . . 4-29

Acquiring Image Data

5Data Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-2Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-3

Setting the Values of Trigger Properties . . . . . . . . . . . . . 5-5About Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-5Specifying Trigger Type, Source, and Condition . . . . . . . . . 5-5

Specifying the Trigger Type . . . . . . . . . . . . . . . . . . . . . . . . 5-8Comparison of Trigger Types . . . . . . . . . . . . . . . . . . . . . . . . 5-8Example: Using an Immediate Trigger . . . . . . . . . . . . . . . . 5-9Example: Using a Manual Trigger . . . . . . . . . . . . . . . . . . . 5-12Example: Using a Hardware Trigger . . . . . . . . . . . . . . . . . . 5-14Setting DCAM-Specific Trigger Modes . . . . . . . . . . . . . . . . 5-18

Controlling Logging Parameters . . . . . . . . . . . . . . . . . . . . 5-25Data Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25Specifying Logging Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-25Specifying the Number of Frames to Log . . . . . . . . . . . . . . 5-26Determining How Much Data Has Been Logged . . . . . . . . 5-28Determining How Many Frames Are Available . . . . . . . . . 5-30Delaying Data Logging After a Trigger . . . . . . . . . . . . . . . . 5-33

viii Contents


Specifying Multiple Triggers . . . . . . . . . . . . . . . . . . . . . . . . 5-34

Waiting for an Acquisition to Finish . . . . . . . . . . . . . . . . . 5-36Using the wait Function . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-36Example: Blocking the Command Line Until an AcquisitionCompletes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-37

Managing Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40Monitoring Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . . . 5-40Modifying the Frame Memory Limit . . . . . . . . . . . . . . . . . . 5-41Freeing Memory . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-42

Logging Image Data to Disk . . . . . . . . . . . . . . . . . . . . . . . . 5-45Logging Data to Disk . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-45Creating an AVI File Object for Logging . . . . . . . . . . . . . . . 5-46Example: Logging Data to Disk . . . . . . . . . . . . . . . . . . . . . . 5-48

Working with Acquired Image Data

6Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-2

Bringing Image Data into the MATLAB Workspace . . . 6-3Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3Moving Multiple Frames into the Workspace . . . . . . . . . . . 6-4Viewing Frames in the Memory Buffer . . . . . . . . . . . . . . . . 6-6Bringing a Single Frame into the Workspace . . . . . . . . . . . 6-10

Working with Image Data in the MATLABWorkspace . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-12Understanding Image Data . . . . . . . . . . . . . . . . . . . . . . . . . 6-12Determining the Dimensions of Image Data . . . . . . . . . . . . 6-13Determining the Data Type of Image Frames . . . . . . . . . . . 6-16Specifying the Color Space . . . . . . . . . . . . . . . . . . . . . . . . . . 6-17Viewing Acquired Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-19

Retrieving Timing Information . . . . . . . . . . . . . . . . . . . . . 6-20

ix


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-20Determining When a Trigger Executed . . . . . . . . . . . . . . . . 6-20Determining When a Frame Was Acquired . . . . . . . . . . . . . 6-21Example: Determining the Frame Delay Duration . . . . . . 6-22

Using Events and Callbacks

7Example: Using the Default Callback Function . . . . . . . 7-2

Event Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-4

Retrieving Event Information . . . . . . . . . . . . . . . . . . . . . . 7-7Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Event Structures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-7Example: Accessing Data in the Event Log . . . . . . . . . . . . . 7-9

Creating and Executing Callback Functions . . . . . . . . . 7-12Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-12Creating Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . 7-12Specifying Callback Functions . . . . . . . . . . . . . . . . . . . . . . . 7-14Example: Viewing a Sample Frame . . . . . . . . . . . . . . . . . . . 7-16Example: Monitoring Memory Usage . . . . . . . . . . . . . . . . . 7-17

Using the From Video Device Block in Simulink

8Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-2

Opening the Block Library . . . . . . . . . . . . . . . . . . . . . . . . . 8-3Using the imaqlib Command . . . . . . . . . . . . . . . . . . . . . . . . 8-3Using the Simulink Library Browser . . . . . . . . . . . . . . . . . . 8-3

Example: Saving Video Data to a File . . . . . . . . . . . . . . . . 8-5

x Contents


Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-5Step 1: Open the Image Acquisition Toolbox Library . . . . . 8-5Step 2: Open a Model or Create a New Model . . . . . . . . . . . 8-6Step 3: Drag the From Video Device Block into theModel . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-7

Step 4: Drag Other Blocks to Complete the Model . . . . . . . 8-8Step 5: Connect the Blocks . . . . . . . . . . . . . . . . . . . . . . . . . . 8-9Step 6: Specify From Video Device Block ParameterValues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-10

Step 7: Run the Simulation . . . . . . . . . . . . . . . . . . . . . . . . . 8-12

Adding Support for Additional Hardware

9Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-2

For More Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9-3

Troubleshooting

10Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-2

Troubleshooting DALSA Coreco IFC Hardware . . . . . . 10-3Troubleshooting DALSA Coreco IFC Devices . . . . . . . . . . . 10-3Determining the Driver Version for DALSA Coreco IFCDevices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-4

Troubleshooting DALSA Coreco Sapera Hardware . . . 10-5Troubleshooting DALSA Coreco Sapera Devices . . . . . . . . 10-5Determining the Driver Version for DALSA Coreco SaperaDevices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-6

Troubleshooting Data Translation Hardware . . . . . . . . 10-7

xi


Troubleshooting DCAM IEEE 1394 (FireWire)Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-8Troubleshooting DCAM IEEE 1394 Hardware . . . . . . . . . . 10-8Installing the CMU DCAM Driver . . . . . . . . . . . . . . . . . . . . 10-9Running the CMU Camera Demo Application . . . . . . . . . . 10-10

Troubleshooting Hamamatsu Hardware . . . . . . . . . . . . . 10-15

Troubleshooting Matrox Hardware . . . . . . . . . . . . . . . . . . 10-16Troubleshooting Matrox Devices . . . . . . . . . . . . . . . . . . . . . 10-16Determining the Driver Version for Matrox Devices . . . . . 10-17

Troubleshooting QImaging Hardware . . . . . . . . . . . . . . . 10-18Troubleshooting QImaging Devices . . . . . . . . . . . . . . . . . . . 10-18Determining the Driver Version for QImaging Devices . . . 10-19

Troubleshooting National Instruments Hardware . . . . 10-20Troubleshooting National Instruments Devices . . . . . . . . . 10-20Determining the Driver Version for National InstrumentsDevices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-21

Troubleshooting Windows Video Hardware . . . . . . . . . . 10-22Troubleshooting Windows Video Devices . . . . . . . . . . . . . . 10-22Determining the Microsoft DirectX Version . . . . . . . . . . . . 10-23

Troubleshooting a Video Preview Window . . . . . . . . . . . 10-25

Contacting The MathWorks and Using the imaqsupportFunction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-26

Function Reference11

General-Purpose Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-2

Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3

xii Contents


Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-3

Tools . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11-4

Getting Command-Line Function Help . . . . . . . . . . . . . . 11-5

Functions Alphabetical List

12

Property Reference

13Video Input Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2General . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2Callback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-3Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-4Acquisition Source . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-5

Video Source Objects . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-6

xiii


Properties Alphabetical List

14

Block Reference15

Examples

AFundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Previewing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-2

Image Acquisition Tool (GUI) . . . . . . . . . . . . . . . . . . . . . . . A-2

Acquiring Image Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Working with Acquired Data . . . . . . . . . . . . . . . . . . . . . . . A-3

Events and Callbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . A-3

Index

xiv Contents


1Getting Started

The best way to learn about Image Acquisition Toolbox capabilities is tolook at a simple example. This chapter introduces the toolbox and illustratesthe basic steps to create an image acquisition application by implementinga simple motion detection application. The example cross-references othersections that provide more details about relevant concepts.

Product Overview on page 1-2 Image Acquisition Tool (GUI) on page 1-5 Basic Image Acquisition Procedure on page 1-6


1 Getting Started

Product Overview

In this section...

Introduction on page 1-2Installation and Configuration Notes on page 1-3The Image Processing Toolbox Software Required to Use the ImageAcquisition Toolbox Software on page 1-3Related Products on page 1-4Supported Hardware on page 1-4

IntroductionThe Image Acquisition Toolbox software is a collection of functions thatextend the capability of the MATLAB numeric computing environment. Thetoolbox supports a wide range of image acquisition operations, including:

Acquiring images through many types of image acquisition devices, fromprofessional grade frame grabbers to USB-based webcams

Viewing a preview of the live video stream Triggering acquisitions (includes external hardware triggers) Configuring callback functions that execute when certain events occur Bringing the image data into the MATLAB workspace

Many of the toolbox functions are MATLAB files. You can view the MATLABcode for these functions using this statement:

type function_name

You can extend Image Acquisition Toolbox capabilities by writing your ownMATLAB files, or by using the toolbox in combination with other toolboxes,such as the Image Processing Toolbox software and the Data AcquisitionToolbox software.

1-2


Product Overview

The Image Acquisition Toolbox software also includes a Simulink block,called From Video Device, that you can use to bring live video data intoa model.

Installation and Configuration NotesTo determine if the Image Acquisition Toolbox software is installed on yoursystem, type this command at the MATLAB prompt:

ver

When you enter this command, MATLAB displays information about theversion of MATLAB you are running, including a list of all toolboxes installedon your system and their version numbers.

For information about installing the toolbox, see the MATLAB InstallationGuide for your platform.

For the most up-to-date information about system requirements, see thesystem requirements page, available in the products area at the MathWorksWeb site (www.mathworks.com).

The Image Processing Toolbox Software Required toUse the Image Acquisition Toolbox SoftwareThe Image Acquisition Toolbox product, including the Image AcquisitionTool, now requires you to have a license for the Image Processing Toolboxproduct starting in R2008b.

If you already have the Image Processing Toolbox product, you do not need todo anything.

If you do not have the Image Processing Toolbox product, the ImageAcquisition Toolbox software R2008a and earlier will continue to work. If youwant to use R2008b or future releases, and you have a current active licensefor the Image Acquisition Toolbox software, you can download the ImageProcessing Toolbox product for free. New customers will need to purchaseboth products to use the Image Acquisition Toolbox product.

If you have any questions, please contact MathWorks customer service.

1-3


1 Getting Started

Related ProductsThe MathWorks provides several products that are relevant to the kindsof tasks you can perform with the Image Acquisition Toolbox software andthat extend the capabilities of MATLAB. For information about these relatedproducts, see www.mathworks.com/products/imaq/related.html.

Supported HardwareThe list of hardware that the Image Acquisition Toolbox software supportscan change in each release, since hardware support is frequently added. TheMathWorks Web site is the best place to check for the most up to date listing.

To see the full list of hardware that the toolbox supports, visit theImage Acquisition Toolbox product page at the MathWorks Web sitewww.mathworks.com/products/imaq and click the Supported Hardwarelink.

1-4


Image Acquisition Tool (GUI)

Image Acquisition Tool (GUI)In Version 3.0 of the toolbox, the functionality of the Image AcquisitionToolbox software is available in a desktop application. You connect directly toyour hardware in the tool and can set acquisition parameters, and previewand acquire image data. You can log the data to MATLAB in several formats,and also generate an AVI file, right from the tool.

To open the tool, select Start > Toolboxes > Image Acquisition > ImageAcquisition Tool from MATLAB. The tool has extensive Help in the desktop.As you click in different panes of the user interface, the relevant Help appearsin the Image Acquisition Tool Help pane.

Most of the Users Guide describes performing tasks using the toolbox via theMATLAB command line. To learn how to use the desktop tool, see Chapter 3,Using the Image Acquisition Tool GUI.

1-5


1 Getting Started

Basic Image Acquisition Procedure

In this section...

Overview on page 1-6Step 1: Install Your Image Acquisition Device on page 1-7Step 2: Retrieve Hardware Information on page 1-8Step 3: Create a Video Input Object on page 1-10Step 4: Preview the Video Stream (Optional) on page 1-12Step 5: Configure Object Properties (Optional) on page 1-14Step 6: Acquire Image Data on page 1-17Step 7: Clean Up on page 1-21

OverviewThis section illustrates the basic steps required to create an image acquisitionapplication by implementing a simple motion detection application. Theapplication detects movement in a scene by performing a pixel-to-pixelcomparison in pairs of incoming image frames. If nothing moves in the scene,pixel values remain the same in each frame. When something moves in theimage, the application displays the pixels that have changed values.

The example highlights how you can use the Image Acquisition Toolboxsoftware to create a working image acquisition application with only a fewlines of code.

Note To run the sample code in this example, you must have an imageacquisition device connected to your system. The device can be a professionalgrade image acquisition device, such as a frame grabber, or a genericMicrosoft Windows image acquisition device, such as a webcam. The codecan be used with various types of devices with only minor changes.

1-6



To use the Image Acquisition Toolbox software to acquire image data, youmust perform the following basic steps.

Step Description

Step 1: Install and configure your image acquisition deviceStep 2: Retrieve information that uniquely identifies your image

acquisition device to the Image Acquisition Toolbox softwareStep 3: Create a video input objectStep 4: Preview the video stream (Optional)Step 5: Configure image acquisition object properties (Optional)Step 6: Acquire image dataStep 7: Clean up

Step 1: Install Your Image Acquisition DeviceFollow the setup instructions that come with your image acquisition device.Setup typically involves:

Installing the frame grabber board in your computer. Installing any software drivers required by the device. These are suppliedby the device vendor.

Connecting a camera to a connector on the frame grabber board. Verifying that the camera is working properly by running the applicationsoftware that came with the camera and viewing a live video stream.

Generic Windows image acquisition devices, such as webcams and digitalvideo camcorders, typically do not require the installation of a frame grabberboard. You connect these devices directly to your computer via a USB orFireWire port.

After installing and configuring your image acquisition hardware, startMATLAB on your computer by double-clicking the icon on your desktop. Youdo not need to perform any special configuration of MATLAB to performimage acquisition.

1-7


1 Getting Started

Step 2: Retrieve Hardware InformationIn this step, you get several pieces of information that the toolbox needs touniquely identify the image acquisition device you want to access. You usethis information when you create an image acquisition object, described inStep 3: Create a Video Input Object on page 1-10.

The following table lists this information. You use the imaqhwinfo functionto retrieve each item.

DeviceInformation Description

Adaptor name An adaptor is the software that the toolbox uses tocommunicate with an image acquisition device via itsdevice driver. The toolbox includes adaptors for certainvendors of image acquisition equipment and for particularclasses of image acquisition devices. See Determining theAdaptor Name on page 1-9 for more information.

Device ID The device ID is a number that the adaptor assigns touniquely identify each image acquisition device with whichit can communicate. See Determining the Device ID onpage 1-9 for more information.

Note Specifying the device ID is optional; the toolboxuses the first available device ID as the default.

Video format The video format specifies the image resolution (widthand height) and other aspects of the video stream. Imageacquisition devices typically support multiple videoformats. See Determining the Supported Video Formatson page 1-10 for more information.

Note Specifying the video format is optional; the toolboxuses one of the supported formats as the default.

1-8



Determining the Adaptor NameTo determine the name of the adaptor, enter the imaqhwinfo function at theMATLAB prompt without any arguments.

imaqhwinfoans =

InstalledAdaptors: {'dcam' 'winvideo'}MATLABVersion: '7.4 (R2007a)'

ToolboxName: 'Image Acquisition Toolbox'ToolboxVersion: '2.1 (R2007a)'

In the data returned by imaqhwinfo, the InstalledAdaptors field lists theadaptors that are available on your computer. In this example, imaqhwinfofound two adaptors available on the computer: 'dcam' and 'winvideo'. Thelisting on your computer might contain only one adaptor name. Select theadaptor name that provides access to your image acquisition device. For moreinformation, see Determining the Device Adaptor Name on page 4-2.

Determining the Device IDTo find the device ID of a particular image acquisition device, enter theimaqhwinfo function at the MATLAB prompt, specifying the name of theadaptor as the only argument. (You found the adaptor name in the first call toimaqhwinfo, described in Determining the Adaptor Name on page 1-9.) Inthe data returned, the DeviceIDs field is a cell array containing the deviceIDs of all the devices accessible through the specified adaptor.

Note This example uses the DCAM adaptor. You should substitute the nameof the adaptor you would like to use.

info = imaqhwinfo('dcam')info =

AdaptorDllName: [1x77 char]AdaptorDllVersion: '2.1 (R2007a)'

AdaptorName: 'dcam'DeviceIDs: {[1]}

1-9


1 Getting Started

DeviceInfo: [1x1 struct]

Determining the Supported Video FormatsTo determine which video formats an image acquisition device supports, lookin the DeviceInfo field of the data returned by imaqhwinfo. The DeviceInfofield is a structure array where each structure provides information about aparticular device. To view the device information for a particular device, youcan use the device ID as a reference into the structure array. Alternatively,you can view the information for a particular device by calling the imaqhwinfofunction, specifying the adaptor name and device ID as arguments.

To get the list of the video formats supported by a device, look atSupportedFormats field in the device information structure. TheSupportedFormats field is a cell array of strings where each string is thename of a video format supported by the device. For more information, seeDetermining Supported Video Formats on page 4-5.

dev_info = imaqhwinfo('dcam',1)

dev_info =

DefaultFormat: 'F7_Y8_1024x768'DeviceFileSupported: 0

DeviceName: 'XCD-X700 1.05'DeviceID: 1

ObjectConstructor: 'videoinput('dcam', 1)'SupportedFormats: {'F7_Y8_1024x768' 'Y8_1024x768'}

Step 3: Create a Video Input ObjectIn this step you create the video input object that the toolbox uses to representthe connection between MATLAB and an image acquisition device. Using theproperties of a video input object, you can control many aspects of the imageacquisition process. For more information about image acquisition objects, seeChapter 4, Connecting to Hardware.

To create a video input object, use the videoinput function at the MATLABprompt. The DeviceInfo structure returned by the imaqhwinfo functioncontains the default videoinput function syntax for a device in the

1-10



ObjectConstructor field. For more information the device informationstructure, see Determining the Supported Video Formats on page 1-10.

The following example creates a video input object for the DCAM adaptor.Substitute the adaptor name of the image acquisition device available onyour system.

vid = videoinput('dcam',1,'Y8_1024x768')

The videoinput function accepts three arguments: the adaptor name,device ID, and video format. You retrieved this information in step 2. Theadaptor name is the only required argument; the videoinput function canuse defaults for the device ID and video format. To determine the defaultvideo format, look at the DefaultFormat field in the device informationstructure. See Determining the Supported Video Formats on page 1-10for more information.

Instead of specifying the video format, you can optionally specify the name ofa device configuration file, also known as a camera file. Device configurationfiles are typically supplied by frame grabber vendors. These files containall the required configuration settings to use a particular camera with thedevice. See Using Device Configuration Files (Camera Files) on page 4-13for more information.

Viewing the Video Input Object SummaryTo view a summary of the video input object you just created, enter thevariable name (vid) at the MATLAB command prompt. The summaryinformation displayed shows many of the characteristics of the object, suchas the number of frames that will be captured with each trigger, the triggertype, and the current state of the object. You can use video input objectproperties to control many of these characteristics. See Step 5: ConfigureObject Properties (Optional) on page 1-14 for more information.

vid

Summary of Video Input Object Using 'XCD-X700 1.05'.

Acquisition Source(s): input1 is available.

Acquisition Parameters: 'input1' is the current selected source.

1-11


1 Getting Started

10 frames per trigger using the selected source.

'Y8_1024x768' video data to be logged upon START.

Grabbing first of every 1 frame(s).

Log data to 'memory' on trigger.

Trigger Parameters: 1 'immediate' trigger(s) on START.

Status: Waiting for START.

0 frames acquired since starting.

0 frames available for GETDATA.

Step 4: Preview the Video Stream (Optional)After you create the video input object, MATLAB is able to access the imageacquisition device and is ready to acquire data. However, before you begin,you might want to see a preview of the video stream to make sure that theimage is satisfactory. For example, you might want to change the positionof the camera, change the lighting, correct the focus, or make some otherchange to your image acquisition setup.

Note This step is optional at this point in the procedure because you canpreview a video stream at any time after you create a video input object.

To preview the video stream in this example, enter the preview functionat the MATLAB prompt, specifying the video input object created in step 3as an argument.

preview(vid)

The preview function opens a Video Preview figure window on your screencontaining the live video stream. To stop the stream of live video, you cancall the stoppreview function. To restart the preview stream, call previewagain on the same video input object.

While a preview window is open, the video input object sets the value of thePreviewing property to 'on'. If you change characteristics of the imageby setting image acquisition object properties, the image displayed in thepreview window reflects the change.

1-12



The following figure shows the Video Preview window for the example.

Video Preview Window

To close the Video Preview window, click the Close button in the title baror use the closepreview function, specifying the video input object as anargument.

closepreview(vid)

Calling closepreview without any arguments closes all open Video Previewwindows.

1-13


1 Getting Started

Step 5: Configure Object Properties (Optional)After creating the video input object and previewing the video stream, youmight want to modify characteristics of the image or other aspects of theacquisition process. You accomplish this by setting the values of imageacquisition object properties. This section

Describes the types of image acquisition objects used by the toolbox Describes how to view all the properties supported by these objects, withtheir current values

Describes how to set the values of object properties

Types of Image Acquisition ObjectsThe toolbox uses two types of objects to represent the connection with animage acquisition device:

Video input objects Video source objects

A video input object represents the connection between MATLAB and a videoacquisition device at a high level. The properties supported by the video inputobject are the same for every type of device. You created a video input objectusing the videoinput function in step 3.

When you create a video input object, the toolbox automatically creates one ormore video source objects associated with the video input object. Each videosource object represents a collection of one or more physical data sources thatare treated as a single entity. The number of video source objects the toolboxcreates depends on the device and the video format you specify. At any onetime, only one of the video source objects, called the selected source, can beactive. This is the source used for acquisition. For more information aboutthese image acquisition objects, see Creating Image Acquisition Objectson page 4-8.

Viewing Object PropertiesTo view a complete list of all the properties supported by a video input objector a video source object, use the get function. To list the properties of thevideo input object created in step 3, enter this code at the MATLAB prompt.

1-14



get(vid)

The get function lists all the properties of the object with their current values.

General Settings:DeviceID = 1DiskLogger = []DiskLoggerFrameCount = 0EventLog = [1x0 struct]FrameGrabInterval = 1FramesAcquired = 0FramesAvailable = 0FramesPerTrigger = 10Logging = offLoggingMode = memoryName = Y8_1024x768-dcam-1NumberOfBands = 1Previewing = onReturnedColorSpace = grayscaleROIPosition = [0 0 1024 768]Running = offTag =Timeout = 10Type = videoinputUserData = []VideoFormat = Y8_1024x768VideoResolution = [1024 768]...

To view the properties of the currently selected video source object associatedwith this video input object, use the getselectedsource function inconjunction with the get function. The getselectedsource function returnsthe currently active video source. To list the properties of the currentlyselected video source object associated with the video input object created instep 3, enter this code at the MATLAB prompt.

get(getselectedsource(vid))

The get function lists all the properties of the object with their current values.

1-15


1 Getting Started

Note Video source object properties are device specific. The list of propertiessupported by the device connected to your system might differ from the listshown in this example.

General Settings:Parent = [1x1 videoinput]Selected = onSourceName = input1Tag =Type = videosource

Device Specific Properties:FrameRate = 15Gain = 2048Shutter = 2715

Setting Object PropertiesTo set the value of a video input object property or a video source objectproperty, you can use the set function or you can reference the object propertyas you would a field in a structure, using dot notation.

Some properties are read only; you cannot set their values. These propertiestypically provide information about the state of the object. Other propertiesbecome read only when the object is running. To view a list of all theproperties you can set, use the set function, specifying the object as theonly argument.

To implement continuous image acquisition, the example sets theTriggerRepeat property to Inf. To set this property using the set function,enter this code at the MATLAB prompt.

set(vid,'TriggerRepeat',Inf);

To help the application keep up with the incoming video stream whileprocessing data, the example sets the FrameGrabInterval property to 5. Thisspecifies that the object acquire every fifth frame in the video stream. (Youmight need to experiment with the value of the FrameGrabInterval propertyto find a value that provides the best response with your image acquisition

1-16



setup.) This example shows how you can set the value of an object propertyby referencing the property as you would reference a field in a MATLABstructure.

vid.FrameGrabInterval = 5;

To set the value of a video source object property, you must first use thegetselectedsource function to retrieve the object. (You can also get theselected source by searching the video input object Source property for thevideo source object that has the Selected property set to 'on'.)

To illustrate, the example assigns a value to the Tag property.

vid_src = getselectedsource(vid);

set(vid_src,'Tag','motion detection setup');

Step 6: Acquire Image DataAfter you create the video input object and configure its properties, you canacquire data. This is typically the core of any image acquisition application,and it involves these steps:

Starting the video input object You start an object by calling thestart function. Starting an object prepares the object for data acquisition.For example, starting an object locks the values of certain object properties(they become read only). Starting an object does not initiate the acquiringof image frames, however. The initiation of data logging depends on theexecution of a trigger.The following example calls the start function to start the video inputobject. Objects stop when they have acquired the requested number offrames. Because the example specifies a continuous acquisition, you mustcall the stop function to stop the object.

Triggering the acquisition To acquire data, a video input object mustexecute a trigger. Triggers can occur in several ways, depending on howthe TriggerType property is configured. For example, if you specify animmediate trigger, the object executes a trigger automatically, immediatelyafter it starts. If you specify a manual trigger, the object waits for a callto the trigger function before it initiates data acquisition. For moreinformation, see Chapter 5, Acquiring Image Data.

1-17


1 Getting Started

In the example, because the TriggerType property is set to 'immediate'(the default) and the TriggerRepeat property is set to Inf, the objectautomatically begins executing triggers and acquiring frames of data,continuously.

Bringing data into the MATLAB workspace The toolbox storesacquired data in a memory buffer, a disk file, or both, depending on thevalue of the video input object LoggingMode property. To work with thisdata, you must bring it into the MATLAB workspace. To bring multipleframes into the workspace, use the getdata function. Once the data is inthe MATLAB workspace, you can manipulate it as you would any otherdata. For more information, see Chapter 6, Working with Acquired ImageData.

Note The toolbox provides a convenient way to acquire a single frame ofimage data that doesnt require starting or triggering the object. See Bringinga Single Frame into the Workspace on page 6-10 for more information.

Running the ExampleTo run the example, enter the following code at the MATLAB prompt. Theexample loops until a specified number of frames have been acquired. In eachloop iteration, the example calls getdata to bring the two most recent framesinto the MATLAB workspace. To detect motion, the example subtracts oneframe from the other, creating a difference image, and then displays it. Pixelsthat have changed values in the acquired frames will have nonzero values inthe difference image.

The getdata function removes frames from the memory buffer when it bringsthem into the MATLAB workspace. It is important to move frames from thememory buffer into the MATLAB workspace in a timely manner. If you donot move the acquired frames from memory, you can quickly exhaust all thememory available on your system.

Note The example uses functions in the Image Processing Toolbox software.

% Create video input object.

1-18



vid = videoinput('dcam',1,'Y8_1024x768')

% Set video input object properties for this application.% Note that example uses both SET method and dot notation method.set(vid,'TriggerRepeat',Inf);vid.FrameGrabInterval = 5;

% Set value of a video source object property.vid_src = getselectedsource(vid);set(vid_src,'Tag','motion detection setup');

% Create a figure window.figure;

% Start acquiring frames.start(vid)

% Calculate difference image and display it.while(vid.FramesAcquired

1 Getting Started

The following figure shows how the example displays detected motion. In thefigure, areas representing movement are displayed.

Figure Window Displayed by Example

Image Data in the MATLAB WorkspaceIn the example, the getdata function returns the image frames in the variabledata as a 480-by-640-by-1-by-10 array of 8-bit data (uint8).

whosName Size Bytes Class

data 4-D 3072000 uint8 arraydev_info 1x1 1601 struct arrayinfo 1x1 2467 struct arrayvid 1x1 1138 videoinput objectvid_src 1x1 726 videosource object

The height and width of the array are primarily determined by the videoresolution of the video format. However, you can use the ROIPositionproperty to specify values that supersede the video resolution. Devicestypically express video resolution as column-by-row; MATLAB expressesmatrix dimensions as row-by-column.

1-20



The third dimension represents the number of color bands in the image.Because the example data is a grayscale image, the third dimension is 1. ForRGB formats, image frames have three bands: red is the first, green is thesecond, and blue is the third. The fourth dimension represents the number offrames that have been acquired from the video stream.

Step 7: Clean UpWhen you finish using your image acquisition objects, you can remove themfrom memory and clear the MATLAB workspace of the variables associatedwith these objects.

delete(vid)clearclose(gcf)

For more information, see Deleting Image Acquisition Objects on page 4-27.

1-21


1 Getting Started

1-22


2Introduction

This chapter describes the Image Acquisition Toolbox software and itscomponents.

Overview on page 2-2 Setting Up Image Acquisition Hardware on page 2-6 Previewing Data on page 2-9


2 Introduction

Overview

In this section...

Introduction on page 2-2Toolbox Components on page 2-3The Image Processing Toolbox Software Required to Use the ImageAcquisition Toolbox Software on page 2-4The Image Acquisition Tool (GUI) on page 2-4Supported Devices on page 2-4

IntroductionThe Image Acquisition Toolbox software implements an object-orientedapproach to image acquisition. Using toolbox functions, you create anobject that represents the connection between MATLAB and specific imageacquisition devices. Using properties of the object you can control variousaspects of the acquisition process, such as the amount of video data you wantto capture. Chapter 4, Connecting to Hardware describes how to createobjects.

Once you establish a connection to a device, you can acquire image data byexecuting a trigger. In the toolbox, all image acquisition is initiated by atrigger. The toolbox supports several types of triggers that let you controlwhen an acquisition takes place. For example, using hardware triggers youcan synchronize an acquisition with an external device. Chapter 5, AcquiringImage Data describes how to trigger the acquisition of image data.

To work with the data you acquire, you must bring it into the MATLABworkspace. When the frames are acquired, the toolbox stores them in amemory buffer. The toolbox provides several ways to bring one or more framesof data into the workspace where you can manipulate it as you would anyother multidimensional numeric array. Chapter 6, Working with AcquiredImage Data describes this process.

Finally, you can enhance your image acquisition application by using eventcallbacks. The toolbox has defined certain occurrences, such as the triggeringof an acquisition, as events. You can associate the execution of a particular

2-2


Overview

function with a particular event. Chapter 7, Using Events and Callbacksdescribes this process.

Toolbox ComponentsThe toolbox uses components called hardware device adaptors to connect todevices through their drivers. The toolbox includes adaptors that supportdevices produced by several vendors of image acquisition equipment.In addition, the toolbox includes an adaptor for generic Windows videoacquisition devices.

The following figure shows these components and their relationship.

The Image Acquisition Toolbox Software Components

2-3


2 Introduction

The Image Processing Toolbox Software Required toUse the Image Acquisition Toolbox SoftwareThe Image Acquisition Toolbox product, including the Image AcquisitionTool, now requires you to have a license for the Image Processing Toolboxproduct starting in R2008b.

If you already have the Image Processing Toolbox product, you do not need todo anything.

If you do not have the Image Processing Toolbox product, the ImageAcquisition Toolbox software R2008a and earlier will continue to work. If youwant to use R2008b or future releases, and you have a current active licensefor the Image Acquisition Toolbox software, you can download the ImageProcessing Toolbox product for free. New customers will need to purchaseboth products to use the Image Acquisition Toolbox product.

If you have any questions, please contact MathWorks customer service.

The Image Acquisition Tool (GUI)In Version 3.0 of the toolbox, the functionality of the Image AcquisitionToolbox software is available in a desktop application. You connect directlyto your hardware in the tool and can then set acquisition parameters, andpreview and acquire image data. You can log the data to MATLAB in severalformats, and also generate an AVI file, right from the tool.

To open the tool, select Start > Toolboxes > Image Acquisition > ImageAcquisition Tool from MATLAB. The tool has extensive Help in the desktop.As you click in different panes of the user interface, the relevant Help appearsin the Image Acquisition Tool Help pane.

Most of the Users Guide describes performing tasks using the toolbox via theMATLAB command line. To learn how to use the desktop tool, see Chapter 3,Using the Image Acquisition Tool GUI.

Supported DevicesThe Image Acquisition Toolbox software includes adaptors that providesupport for several vendors of professional grade image acquisition

2-4


Overview

equipment, devices that support the IIDC 1394-based Digital CameraSpecification (DCAM), and devices that provide Windows Driver Model(WDM) or Video for Windows (VFW) drivers, such as USB and IEEE 1394(FireWire, i.LINK) Web cameras, Digital video (DV) camcorders, and TVtuner cards. For the latest information about supported hardware, visitthe Image Acquisition Toolbox product page at the MathWorks Web site(www.mathworks.com/products/imaq).

The DCAM specification, developed by the 1394 Trade Association, describesa generic interface for exchanging data with IEEE 1394 (FireWire) digitalcameras that is often used in scientific applications. The toolboxs DCAMadaptor supports Format 7, also known as partial scan mode. The toolboxuses the prefix F7_ to identify Format 7 video format names.

Note The toolbox supports only connections to IEEE 1394 (FireWire)DCAM-compliant devices using the Carnegie Mellon University DCAMdriver. The toolbox is not compatible with any other vendor-supplied driver,even if the driver is DCAM compliant.

You can add support for additional hardware by writing an adaptor. For moreinformation, see Chapter 9, Adding Support for Additional Hardware.

2-5


2 Introduction

Setting Up Image Acquisition Hardware

In this section...

Introduction on page 2-6Setting Up Frame Grabbers on page 2-6Setting Up Generic Windows Video Acquisition Devices on page 2-7Setting Up DCAM Devices on page 2-7Resetting Your Image Acquisition Hardware on page 2-7A Note About Frame Rates and Processing Speed on page 2-7

IntroductionTo acquire image data, you must perform the setup required by yourparticular image acquisition device. In a typical image acquisition setup,an image acquisition device, such as a camera, is connected to a computervia an image acquisition board, such as a frame grabber, or via a UniversalSerial Bus (USB) or IEEE 1394 (FireWire) port. The setup required varieswith the type of device.

After installing and configuring your image acquisition hardware, startMATLAB on your computer by double-clicking the icon on your desktop. Youdo not need to perform any special configuration of MATLAB to acquire data.

Setting Up Frame GrabbersFor frame grabbers, also known as imaging boards, setup typically involvesthe following tasks:

Installing the frame grabber in your computer Installing any software drivers required by the frame grabber. These aresupplied by the device vendor.

Connecting the camera, or other image acquisition device, to a connectoron the frame grabber

Verifying that the camera is working properly by running the applicationsoftware that came with the frame grabber and viewing a live video stream

2-6


Setting Up Image Acquisition Hardware

Setting Up Generic Windows Video AcquisitionDevicesIEEE 1394 (FireWire) and generic Windows video acquisition devices that useWindows Driver Model (WDM) or Video for Windows (VFW) device driverstypically require less setup. Plug the device into the USB or IEEE 1394(FireWire) port on your computer and install the device driver provided bythe vendor.

Setting Up DCAM DevicesIf you intend to access a DCAM-compliant IEEE 1394 (FireWire) camera, youmust install and configure the Carnegie Mellon University (CMU) DCAMdriver. The toolbox is not compatible with any other vendor-supplied driver,even if the driver is DCAM compliant. See Installing the CMU DCAMDriver on page 10-9 for more information.

Resetting Your Image Acquisition HardwareTo return MATLAB and your image acquisition hardware to a known state,where no image acquisition objects exist and the hardware is not configured,use the imaqreset function.

If you connect another image acquisition device to your system after MATLABis started, you can use imaqreset to make the toolbox aware of the newhardware.

A Note About Frame Rates and Processing SpeedThe frame rate describes how fast an image acquisition device provides data,typically measured as frames per second.

Devices that support industry-standard video formats must provide framesat the rate specified by the standard. For RS170 and NTSC, the standarddictates a frame rate of 30 frames per second (30 Hz). The CCIR andPAL standards define a frame rate of 25 Hz. Nonstandard devices can beconfigured to operate at higher rates. Generic Windows image acquisitiondevices, such as webcams, might support many different frame rates.Depending on the device being used, the frame rate might be configurableusing a device-specific property of the image acquisition object.

2-7


2 Introduction

The rate at which the Image Acquisition Toolbox software can process imagesdepends on the processor speed, the complexity of the processing algorithm,and the frame rate. Given a fast processor, a simple algorithm, and a framerate tuned to the acquisition setup, the Image Acquisition Toolbox softwarecan process data as it comes in.

2-8


Previewing Data

Previewing Data

In this section...

Introduction on page 2-9Opening a Video Preview Window on page 2-10Stopping the Preview Video Stream on page 2-11Closing a Video Preview Window on page 2-12Previewing Data in Custom GUIs on page 2-12Performing Custom Processing of Previewed Data on page 2-14

IntroductionAfter you connect MATLAB to the image acquisition device (see Chapter 4,Connecting to Hardware), you can view the live video stream using theVideo Preview window. Previewing the video data can help you make surethat the image being captured is satisfactory.

For example, by looking at a preview, you can verify that the lighting andfocus are correct. If you change characteristics of the image, by using videoinput object and video source object properties, the image displayed in theVideo Preview window changes to reflect the new property settings.

The following sections provide more information about using the VideoPreview window.

Opening a Video Preview Window on page 2-10 Stopping the Preview Video Stream on page 2-11 Closing a Video Preview Window on page 2-12

Instead of using the toolboxs Video Preview window, you can display the livevideo preview stream in any Handle Graphics image object you specify. Inthis way, you can include video previewing in a GUI of your own creation. Thefollowing sections describe this capability.

Previewing Data in Custom GUIs on page 2-12

2-9


2 Introduction

Performing Custom Processing of Previewed Data on page 2-14

Note The Image Acquisition Toolbox Preview window and the Previewwindow that is built into the Image Acquisition Tool support the display of upto 16-bit image data. The Preview window was designed to only show 8-bitdata, but many cameras return 10-, 12-, 14-, or 16-bit data. The Previewwindow display supports these higher bit-depth cameras. However, larger bitdata is scaled to 8-bit for the purpose of displaying previewed data. If you needthe full resolution of the data, use the getsnapshot or getdata functions.

Opening a Video Preview WindowTo open a Video Preview window, use the preview function. The VideoPreview window displays the live video stream from the device. You can onlyopen one preview window per device. If multiple devices are used, you canopen multiple preview windows at the same time.

The following example creates a video input object and then opens a VideoPreview window for the video input object.

vid = videoinput('winvideo');preview(vid);

The following figure shows the Video Preview window created by thisexample. The Video Preview window displays the live video stream. The sizeof the preview image is determined by the value of the video input objectsROIPosition property. The Video Preview window displays the video data at100% magnification (one screen pixel represents one image pixel).

In addition to the preview image, the Video Preview window includesinformation about the image, such as the timestamp of the video frame, thevideo resolution, and the current status of the video input object.

Note Because video formats typically express resolution as width-by-height,the Video Preview window expresses the size of the image frame ascolumn-by-row, rather than the standard MATLAB row-by-column format.

2-10


Previewing Data

Note The Image Acquisition Toolbox Preview window and the Previewwindow that is built into the Image Acquisition Tool support the display of upto 16-bit image data. The Preview window was designed to only show 8-bitdata, but many cameras return 10-, 12-, 14-, or 16-bit data. The Previewwindow display supports these higher bit-depth cameras. However, larger bitdata is scaled to 8-bit for the purpose of displaying previewed data. If you needthe full resolution of the data, use the getsnapshot or getdata functions.

Stopping the Preview Video StreamWhen you use the preview function to start previewing image data, the VideoPreview window displays a view of the live video stream coming from thedevice. To stop the updating of the live video stream, call the stoppreviewfunction.

2-11


2 Introduction

This example creates a video input object and opens a Video Preview window.The example then calls the stoppreview function on this video input object.The Video Preview window stops updating the image displayed and stopsupdating the timestamp. The status displayed in the Video Preview windowalso changes to indicate that previewing has been stopped.

vid = videoinput('winvideo');preview(vid)stoppreview(vid)

To restart the video stream in the Video Preview window, call preview againon the same video input object.

preview(vid)

Closing a Video Preview WindowTo close a particular Video Preview window, use the closepreview function,specifying the video input object as an argument. You do not need to stop thelive video stream displayed in the Video Preview window before closing it.

closepreview(vid)

To close all currently open Video Preview windows, use the closepreviewfunction without any arguments.

closepreview

Note When called without an argument, the closepreview function onlycloses Video Preview windows. The closepreview function does not close anyother figure windows in which you have directed the live preview video stream.For more information, see Previewing Data in Custom GUIs on page 2-12.

Previewing Data in Custom GUIsInstead of using the toolboxs Video Preview window, you can use the previewfunction to direct the live video stream to any Handle Graphics image object.In this way, you can incorporate the toolboxs previewing capability in a GUIof your own creation. (You can also perform custom processing as the livevideo is displayed. For information, see Performing Custom Processing ofPreviewed Data on page 2-14.)

2-12


Previewing Data

To use this capability, create an image object and then call the previewfunction, specifying a handle to the image object as an argument. The previewfunction outputs the live video stream to the image object you specify.

The following example creates a figure window and then creates an imageobject in the figure, the same size as the video frames. The example then callsthe preview function, specifying a handle to the image object.

% Create a video input object.vid = videoinput('winvideo');

% Create a figure window. This example turns off the default% toolbar, menubar, and figure numbering.

figure('Toolbar','none',...'Menubar', 'none',...'NumberTitle','Off',...'Name','My Preview Window');

% Create the image object in which you want to display% the video preview data. Make the size of the image% object match the dimensions of the video frames.

vidRes = get(vid, 'VideoResolution');nBands = get(vid, 'NumberOfBands');hImage = image( zeros(vidRes(2), vidRes(1), nBands) );

% Display the video data in your GUI.

preview(vid, hImage);

2-13


2 Introduction

When you run this example, it creates the GUI shown in the following figure.

Custom Preview

Performing Custom Processing of Previewed DataWhen you specify an image object to the preview function (see PreviewingData in Custom GUIs on page 2-12), you can optionally also specify a functionthat preview executes every time it receives an image frame.

To use this capability, follow these steps:

1 Create the function you want executed for each image frame, called theupdate preview window function. For information about this function, seeCreating the Update Preview Window Function on page 2-15.

2 Create an image object.

3 Configure the value of the image objects 'UpdatePreviewWindowFcn'application-defined data to be a function handle to your update previewwindow function. For more information, see Specifying the UpdatePreview Function on page 2-16.

4 Call the preview function, specifying the handle of the image object asan argument.

2-14


Previewing Data

Note If you specify an update preview window function, in addition towhatever processing your function performs, it must display the video datain the image object. You can do this by updating the CData of the imageobject with the incoming video frames. For some performance guidelinesabout updating the data displayed in an image object, see Technical Solution1-1B022.

Creating the Update Preview Window FunctionWhen preview calls the update preview window function you specify, it passesyour function the following arguments.

Argument Description

obj Handle to the video input object being previewedA data structure containing the following fields:Data Current image frame specified as an

H-by-W-by-B array, where H is the imageheight and W is the image width, asspecified in the ROIPosition property, andB is the number of color bands, as specifiedin the NumberOfBands property

Resolution Text string specifying the current imagewidth and height, as defined by theROIPosition property

Status String describing the status of the videoinput object

event

Timestamp String specifying the time associated withthe current image frame, in the formathh:mm:ss:ms

himage Handle to the image object in which the data is to bedisplayed

The following example creates an update preview window function thatdisplays the timestamp of each incoming video frame as a text label in the

2-15


2 Introduction

custom GUI. The update preview window function uses getappdata toretrieve a handle to the text label uicontrol object from application-defineddata in the image object. The custom GUI stores this handle to the text labeluicontrol object see Specifying the Update Preview Function on page2-16.

Note that the update preview window function also displays the video data byupdating the CData of the image object.

function mypreview_fcn(obj,event,himage)% Example update preview window function.

% Get timestamp for frame.tstampstr = event.Timestamp;

% Get handle to text label uicontrol.ht = getappdata(himage,'HandleToTimestampLabel');

% Set the value of the text label.set(ht,'String',tstampstr);

% Display image data.set(himage, 'CData', event.Data)

Specifying the Update Preview FunctionTo use an update preview window function, store a function handle to yourfunction in the 'UpdatePreviewWindowFcn' application-defined data ofthe image object. The following example uses the setappdata function toconfigure this application-defined data to a function handle to the updatepreview window function described in Creating the Update Preview WindowFunction on page 2-15.

This example extends the simple custom preview window created inPreviewing Data in Custom GUIs on page 2-12. This example adds threepush button uicontrol objects to the GUI: Start Preview, Stop Preview,and Close Preview.

In addition, to illustrate using an update preview window function, theexample GUI includes a text label uicontrol object to display the timestamp

2-16


Previewing Data

value. The update preview window function updates this text label eachtime a framed is received. The example uses setappdata to store a handleto the text label uicontrol object in application-defined data in the imageobject. The update preview window function retrieves this handle to updatethe timestamp display.

% Create a video input object.vid = videoinput('winvideo');

% Create a figure window. This example turns off the default% toolbar and menubar in the figure.hFig = figure('Toolbar','none',...

'Menubar', 'none',...'NumberTitle','Off',...'Name','My Custom Preview GUI');

% Set up the push buttonsuicontrol('String', 'Start Preview',...

'Callback', 'preview(vid)',...'Units','normalized',...'Position',[0 0 0.15 .07]);

uicontrol('String', 'Stop Preview',...'Callback', 'stoppreview(vid)',...'Units','normalized',...'Position',[.17 0 .15 .07]);

uicontrol('String', 'Close',...'Callback', 'close(gcf)',...'Units','normalized',...'Position',[0.34 0 .15 .07]);

% Create the text label for the timestamphTextLabel = uicontrol('style','text','String','Timestamp', ...

'Units','normalized',...'Position',[0.85 -.04 .15 .08]);

% Create the image object in which you want to% display the video preview data.vidRes = get(vid, 'VideoResolution');imWidth = vidRes(1);imHeight = vidRes(2);

2-17


2 Introduction

nBands = get(vid, 'NumberOfBands');hImage = image( zeros(imHeight, imWidth, nBands) );

% Specify the size of the axes that contains the image object% so that it displays the image at the right resolution and% centers it in the figure window.figSize = get(hFig,'Position');figWidth = figSize(3);figHeight = figSize(4);set(gca,'unit','pixels',...

'position',[ ((figWidth - imWidth)/2)...((figHeight - imHeight)/2)...

imWidth imHeight ]);

% Set up the update preview window function.setappdata(hImage,'UpdatePreviewWindowFcn',@mypreview_fcn);

% Make handle to text label available to update function.setappdata(hImage,'HandleToTimestampLabel',hTextLabel);

preview(vid, hImage);

2-18


Previewing Data

When you run this example, it creates the GUI shown in the following figure.Each time preview receives a video frame, it calls the update preview windowfunction that you specified, which updates the timestamp text label in theGUI.

Custom Preview GUI with Timestamp Text Label

2-19


2 Introduction

2-20


3Using the Image AcquisitionTool GUI

The Image Acquisition Tool Desktop on page 3-2 Selecting Your Device on page 3-5 Setting Acquisition Parameters on page 3-8 Previewing and Acquiring Data on page 3-25 Exporting Data on page 3-32 Saving Image Acquisition Tool Configurations on page 3-35 Exporting Hardware Configurations to MATLAB on page 3-37 Saving and Copying the Session Log on page 3-39 Registering a Third-Party Adaptor on page 3-42


3 Using the Image Acquisition Tool GUI

The Image Acquisition Tool Desktop

In this section...

Opening the Tool on page 3-2Parts of the Desktop on page 3-2

Opening the ToolImage Acquisition Toolbox functionality is now available in a desktopapplication. You connect directly to your hardware in the tool and can previewand acquire image data. You can log the data to MATLAB in several formats,and also generate an AVI file, right from the tool.

The Image Acquisition Tool provides a desktop environment that integrates apreview/acquisition area with Acquisition Parameters so that you can changesettings and see the changes dynamically applied to your image data.

To open the Image Acquisition Tool, do one of the following:

Type imaqtool at the MATLAB command line. Select Start > Toolboxes > Image Acquisition > Image AcquisitionTool (imaqtool) from MATLAB.

Note The right pane in the tool is the Help pane. As you work in the toolthe Help will provide information for the part of the interface that you areworking in. If the Help is closed, you can open it be selecting Desktop >Image Acquisition Tool Help.

Parts of the DesktopThe Image Acquisition Tool has the following panes.

3-2


The Image Acquisition Tool Desktop

Hardware Browser Shows the image acquisition devices currentlyconnected to your system. Each device is a separate node in the browser.All of the formats the device supports are listed under the device. Eachdevices default format is indicated in parentheses. Select the device formator camera file you want to use for the acquisition. When the format isselected, you can then set acquisition parameters and preview your data.

3-3



See Selecting Your Device on page 3-5 for more information about usingthe Hardware Browser.

Preview window Use to preview and acquire image data from theselected device format, and to export data that has been acquired inmemory to a MAT-file, the MATLAB Workspace, or to tools provided by theImage Processing Toolbox software. See Previewing and Acquiring Dataon page 3-25 for more information about using the Preview window.

Acquisition Parameters Use these tabs to set up general acquisitionparameters, such as frames per trigger and color space, device-specificproperties, logging options, triggering options, and region of interest.Settings you make on any tab will apply to the currently selecteddevice format in the Hardware Browser. See Setting AcquisitionParameters on page 3-8 for more information about using the AcquisitionParameters. Also see the Help for each tab while using the tool for moredetails. When you click any tab, the help for that tab will appear in theImage Acquisition Tool Help pane.

Information pane Displays a summary of information about theselected node in the Hardware Browser.

Session Log Displays a dynamically generated log of the commands thatcorrespond to actions taken in the tool. You can save the log to a MATLABcode file or copy it.

Image Acquisition Tool Help Displays Help for the pane of the desktopthat has focus. Click inside a pane for help on that area of the tool. Forthe Acquisition Parameters pane, click each tab to display informationabout the settings for that tab.If the Help is closed, you can open it by selecting Desktop > ImageAcquisition Tool Help.

3-4


Selecting Your Device


In this section...

Selecting a Device and Format on page 3-5Adding New Hardware on page 3-6Using a Camera File on page 3-7

Selecting a Device and FormatThe Hardware Browser pane shows the image acquisition devices currentlyconnected to your system. Each device is a separate node in the browser. Allof the formats the device supports are listed under the device. Each devicesdefault format is indicated in parentheses. The format information displayedunder a device comes from the devices adaptor.

3-5



Select the device format or camera file you want to use for the acquisition byclicking its name in the tree. When the format is selected, you can then setacquisition parameters and preview your data.

Adding New HardwareWhen you open the Image Acquisition Tool, the Hardware Browserautomatically shows the image acquisition devices supported by the toolboxthat are currently connected to your system. If you plug a new device inwhile the Image Acquisition Tool is open, select Tools > Refresh Image

3-6



Acquisition Hardware to display the new device in the HardwareBrowser.

Using a Camera FileIf your device supports the use of a camera file, also known as a deviceconfiguration file, you can select it under the device name in the HardwareBrowser. For example, some frame grabbers support them.

Under the device name in theHardware Browser, you would see a node thatsays Click to add camera file... if the device supports the use of camera files.

To use a camera file:

1 In the Hardware Browser, single-click the node under your device namethat says Click to add camera file....

2 In the Specify camera file dialog box, type the path and name of the file, orclick the Browse button to locate it, and then click OK.

The camera file will then become a new node under the device, similarto any of the formats listed under a device. You can then set acquisitionparameters, preview, and acquire data using it.

Note The tool ignores hardware trigger configurations included in acamera file. To configure hardware triggering, use the Trigger tab in theAcquisition Parameters pane.

3-7



Setting Acquisition Parameters

In this section...

Using the Acquisition Parameters Pane on page 3-8Setting Frames Per Trigger on page 3-9Setting the Color Space on page 3-10Setting Device-Specific Parameters on page 3-10Logging Your Data on page 3-13Setting Up Triggering on page 3-15Setting a Region of Interest on page 3-18Restoring Default Parameters on page 3-24

Using the Acquisition Parameters PaneThe tool allows you to set acquisition parameters directly in the desktop usingthe Acquisition Parameters pane. Settings you make will apply to thecurrently selected device format in the Hardware Browser.

The Acquisition Parameters pane contains the following tabs:

General Use to set up general acquisition parameters, such as framesper trigger and color space.

Device Properties Use to view or change device-specific properties. Logging Use to set up logging options, such as logging mode, whichdetermines whether your acquired data is logged to memory, disk, or both.If you want to generate an AVI file of your data, use the Disk Loggingoption on this tab.

Triggering Use to set up triggering options, such as number of triggersand trigger type. If you want to do manual triggering using the Triggerbutton, use the Trigger Type option on this tab.

Region of Interest Use to set a Region of Interest (ROI) if you onlywant to use part of an image.

3-8



For more detailed information about the settings on each tab, see the Helptopic for the tab while using the tool. When you click a tab, the correspondingtopic will appear in the Image Acquisition Tool Help pane.

Note Once you have changed parameters of a device, you can restore thedevices default parameters by selecting the device format in the HardwareBrowser and right-clicking Clear Selected Hardware Configuration.

Setting Frames Per TriggerThe Frames Per Trigger field on the General tab is used to set the numberof frames per trigger you want to acquire.

If you want your acquisition to be a specific number of frames per trigger,use the default of 1 frame, or use the arrows to select the number of framesor type in the number.

If you want to acquire frames continuously, set the Frames Per Triggerto infinite and then use the Stop Acquisition button to stop theacquisition, or do manual triggering using the Triggering tab.

3-9



The number of frames that will be acquired when you start an acquisitiondepends on what is set in the Frames Per Trigger field on the General taband the Number of Triggers field on the Triggering tab. For example, ifyou set Frames Per Trigger to 4 and Number of Triggers to 2, the totalnumber of frames acquired will be 8.

Note that if you set Frames Per Trigger to infinite, you cannot setNumber of Triggers on the Triggering tab.

Note Some devices need a few frames to warm up, or may always skip thefirst frame. If your device does that, change the number of frames accordinglyto adjust for that. You can also adjust for camera warm-up by using manualtriggering on the Triggering tab.

Setting the Color SpaceUse Color Space on the General tab to set the color space for the selecteddevice format. The Returned Color Space field has three options: rgb,YCbCr, and grayscale. The setting that is your device formats default colorspace is shown as the default. You can use the arrow to select another setting.

Additionally, if the default color space is grayscale, a value of bayer willbe available in the Returned Color Space field for some devices, and theBayer Sensor Alignment field will also be displayed. Use the drop-downlist to select one of the four possible sensor alignments. This feature allowsthe tool to demosaic Bayer patterns returned by the hardware and interpolatethem into standard RGB color images. For more information about thisfeature, see the BayerSensorAlignment property reference page.

Setting Device-Specific ParametersView or change device-specific properties using the Device Properties tab.The selected devices properties appear in the Properties area. The specificproperties that appear depend on your device.

3-10



The Selected source field specifies the name of the selected source forthe current device. Many device adaptors only have one input source, sofor example, this might show something like input1, port1, or input0 bydefault. If your device supports multiple source names, they will appear inthe drop-down list.

Use the Properties area to view or edit properties:

If a property has an edit box or slider, that value is editable. If a property has an arrow indicating a drop-down list, then you can selecta value from the list.

If a property has a value listed that is grayed out, then that value is notcurrently editable.

Changes you make in the Properties area are applied to your acquisitionor preview dynamically. For example, to change the exposure for the camerayou are using, edit the value in the Exposure property text field or use theslider to change it. You will immediately see the change in the Previewwindow if you are previewing at the time, or in the next acquisition whenyou click the Start Acquisition button.

3-11



Click the Reset to defaults button to undo any modifications you made andrestore the default settings of the device.

Property Help

To get help on any of the properties in the Device Properties tab, right-clicka property and select Whats This?. A Help window opens and displays thehelp for the selected property, as well as the rest of the properties, whichare available by scrolling. This is the same information as the device helpyou access using the imaqhelp command. For more detailed information ondevice-specific properties, see your devices documentati

image acquisition toolbox 3

Documents

release 14sp2march

release 14sp3march

release 13sp1june

release 14sp1march

faxthe mathworks

federal acquisition

license agreement

mathworks web site