Mathworks IMAGE ACQUISITION TOOLBOX 3 user guide

Download

Image Acquisition

User’s Guide

Toolbox™ 3

How to Contact The MathWorks

www.mathworks. comp.soft-sys.matlab Newsgroup www.mathworks.com/contact_TS.html Technical Support

suggest@mathworks.com Product enhancement suggestions

bugs@mathwo doc@mathworks.com Documentation error reports service@mathworks.com Order status, license renewals, passcodes

info@mathwo

com

rks.com

Web

Bug reports

Sales, prici

ng, and general information

508-647-7000 (Phone)

508-647-7001 (Fax)

The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098

For contact information about worldwide offices, see the MathWorks Web site.

Image Acquisition Toolbox™ User’s Guide

The software described in this document is furnished under a license agreement. The software may be used or copied only under the terms of the license agreement. No part of this manual may be photocopied or reproduced in any form without prior written consent from The MathW orks, Inc.

FEDERAL ACQUISITION: This provision applies to all acquisitions of the Program and Documentation by, for, or through the federal government of the United States. By accepting delivery of the Program or Documentation, the government hereby agrees that this software or documentation qualifies as commercial computer software or commercial computer software documentation as such terms are used or defined in FAR 12.212, DFARS Part 227.72, and DFARS 252.227-7014. Accordingly, the terms and conditions of this Agreement and only those rights specified in this Agreement, shall pertain to and govern theuse,modification,reproduction,release,performance,display,anddisclosureoftheProgramand Documentation 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 the government’s needs or is inconsistent in any respect with federal procurement law, the government agrees to return the Program and Docu mentation, unused, to The MathWorks, Inc.

Trademarks

MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See

www.mathworks.com/trademarks for a list of additional trademarks. Other product or brand

names may be trademarks or registered trademarks of their respective holders.

Patents

The MathWorks products are protected by one or more U.S. patents. Please see

www.mathworks.com/patents for more information.

Revision History

March 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.8 August 2005 Third printing Minor Revision for V ersion 1.8 September 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)

Getting Started

Product Overview ................................. 1-2

Introduction Installation and Configuration Notes The Image Processing Toolbox Software Required to Use

the Image Acquisition Toolbox Software Related P roducts Supported Hardware

...................................... 1-2

................. 1-3

............. 1-3

.................................. 1-4

............................... 1-4

Contents

Image A cquisition Tool (GUI)

Basic Image Acquisition Procedure

Overview Step 1: Install Your Image Acquisition Device Step 2: Retrieve Hardw are Information Step 3: Create a Video Input Object Step 4: Preview the Video S tream (Optional) Step 5: Configure Object Properties (Optional) Step 6: Acquire Image Da ta Step 7: Clean Up

........................................ 1-6

.................................. 1-21

....................... 1-5

................. 1-6

.......... 1-7

............... 1-8

.................. 1-10

........... 1-12

.......... 1-14

......................... 1-17

Introduction

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

Introduction Toolbox Compone nts The Image Processing Toolbox Software Required to Use

the Image Acquisition Toolbox Software The Im age Acquisi t io n Tool (G UI) Supported Devices

...................................... 2-2

............................... 2-3

............. 2-4

.................... 2-4

................................. 2-4

Setting Up Image Acquisition Hardware ............. 2-6

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

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

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

.. 2-7

.......................... 2-7

........... 2-7

....... 2-7

Previewing Data

Introduction Opening a Video Preview Window Stopping the Preview Video Stream Closing a Video Preview Window Previewing Data in Custom GUIs Performing Custom Processing of Previewed Data

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

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

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

.................. 2-11

..................... 2-12

.................... 2-12

....... 2-14

Using the Image Acquisition Tool GUI

The Image Acquisition Tool Desktop ................ 3-2

Opening the Tool Parts of the Desktop

Selecting Your Device

Selecting a Device and Format Adding New Hardware Using a Camera File

.................................. 3-2

............................... 3-2

.............................. 3-5

....................... 3-5

............................. 3-6

............................... 3-7

vi Contents

Setting Acquisition Parameters

Using the Acquisition Parameters Pane Setting Frames Per Trigger Setting the Color Space Setting Device-Specific Parameters Logging Your Data Setting Up Triggering Setting a Region of Interest Restoring Default Parameters

Previewing and Acquiring Data

................................ 3-13

......................... 3-9

............................. 3-10

.............................. 3-15

......................... 3-18

....................... 3-24

..................... 3-8

............... 3-8

................... 3-10

..................... 3-25

The Preview Window .............................. 3-25

Previewing Data Acquiring Data

.................................. 3-27

................................... 3-28

Exporting Data

Saving Image Acquisition Tool Configurations

Exporting Hardware Configurations to MATLAB

Saving and Copying the Session Log

About the Session Log Saving the Session Log Copying the Session Log

Registering a Third-Party Adaptor

.................................... 3-32

....... 3-35

................ 3-39

.............................. 3-39

............................. 3-39

............................ 3-40

.................. 3-42

Connecting to Hardware

Getting Hardware Information ..................... 4-2

Getting Hardware Information Determining the Device Adaptor Name Determining the Device ID Determining Supported Video Formats

...................... 4-2

................ 4-2

.......................... 4-3

................ 4-5

..... 3-37

Creating Image Acquisition Objects

Types of Objects Video Input Objects Video Source Objects Creating a Video Input Object Specifying the Video Format Specifying the Selected Video Source Object Getting Information About a Video Input Object

Configuring Image Acquisition Object Properties

About Image Acquisition Object Properties

................................... 4-8

................................ 4-8

............................... 4-8

....................... 4-9

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

................. 4-8

............ 4-14

........ 4-15

............. 4-16

.... 4-16

vii

Viewing the Values of Object Properties ............... 4-17

Viewing t h e Value of a Particular Property Getting Information About Obje ct Properties Setting the Value of an Object Property

............ 4-19

........... 4-20

............... 4-20

Starting and Stopping a Video Input Object

Deleting Image Acquisitio n Objects

Saving Image Acquisition Objects

Using the save Command Using the obj2mfile Command

........................... 4-29

....................... 4-29

................. 4-27

................... 4-29

.......... 4-23

Acquiring Image Data

Data Logging ...................................... 5-2

Overview Trigger Properties

Setting the Values of Trigger Properties

About Trigger Properties Specifying Trigger Type, Source, and Condition

........................................ 5-2

................................. 5-3

............. 5-5

........................... 5-5

......... 5-5

viii Contents

Specifying the Trigger Type

Comparison of Trigger Types Example: Using an Immediate Trigger Example: Using a Manual Trigger Example: Using a Hardware Trigger Setting DCAM-Specific Trigger Modes

Controlling Logging Parameters

Data Logging Specifying Logging Mode Specifying the Number of Frames to Log Determining How Much Data Has Been Logged Determining How Many Frames Are Available Delaying Data Logging After a Trigger

..................................... 5-25

........................ 5-8

................ 5-9

................... 5-12

.................. 5-14

................ 5-18

.................... 5-25

........................... 5-25

................ 5-33

.............. 5-26

........ 5-28

......... 5-30

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

Waiting for an Acquisition to Finish

Using the wait Function Example: Blocking the Command Line Until an Acquisition

Completes

Managing M emory Usage

Memory Usage Monitoring Memory Usage ModifyingtheFrameMemoryLimit Freeing Memory

Logging Image Data to Disk

Logging Data to Disk Creating an AVI File Object for Logging Example: Logging Data to Disk

..................................... 5-37

.................................... 5-40

.................................. 5-42

............................ 5-36

........................... 5-40

.......................... 5-40

........................ 5-45

.............................. 5-45

................. 5-36

.................. 5-41

............... 5-46

...................... 5-48

Working with Acquired Image Data

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

Bringing Image Data into the MATLAB Workspace

Overview Moving Multiple Frames into the Workspace Viewing Frames in the Memory Buffer Bringing a Single Frame into the Workspace

Working with Image Data in the MATLAB

Workspace

Understanding Image Data Determining the Dimensions of Image Data Determining the Data Type of Image Frames Specifying the Color Space Viewing Acquired Data

Retrieving Timing Information

........................................ 6-3

........... 6-4

................ 6-6

........... 6-10

...................................... 6-12

......................... 6-12

............ 6-13

........... 6-16

.......................... 6-17

............................. 6-19

..................... 6-20

... 6-3

Introduction ...................................... 6-20

Determining When a Trigger Executed Determining When a Frame Was Acquired Example: Determining the Frame Delay Duration

................ 6-20

............. 6-21

...... 6-22

Using E vents and Callbacks

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

Event Types

Retrieving Event Information

Introduction Event Structures Example: Accessing Data in the Event Log

Creating an d Executing Callback Functions

Introduction Creating Callback Functions Specifying Callback Functions Example: Viewing a Sample Frame Example: Monitoring Memory Usage

....................................... 7-4

...................... 7-7

...................................... 7-7

.................................. 7-7

............. 7-9

......... 7-12

...................................... 7-12

........................ 7-12

....................... 7-14

................... 7-16

................. 7-17

Using the From Video Device Block in Simulink

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

x Contents

Opening the Block Library

Using the imaqlib Command Using the Simulink Library Browser

Example: Saving Video Data to a File

......................... 8-3

........................ 8-3

.................. 8-3

................ 8-5

Introduction ...................................... 8-5

Step 1: Open the Image Acquisition Toolbox Library Step 2: Open a Model or Create a New M odel Step 3: Drag the From Video Device Block into the

Model Step 4: Drag Other Blocks to Complete the Model Step 5: Connect the Blocks Step 6: Specify From Video Device Block Parameter

Values Step 7: Run the Simulation

......................................... 8-7

.......................... 8-9

........................................ 8-10

......................... 8-12

........... 8-6

....... 8-8

Adding Support for Additional Hardware

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

..... 8-5

For More Information

.............................. 9-3

Troubleshooting

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

Troubleshooting DALSA Coreco IFC Hardware

Troubleshooting D ALSA Coreco IFC Devices Determining the Driver Version for DALSA Coreco IFC

Devices

Troubleshooting DALSA Coreco Sapera Hardware

Troubleshooting DALSA Coreco Sapera Devices Determining the Driver Version for DALSA Coreco Sapera

Devices

Troubleshooting Data Translation Hardware

........................................ 10-4

........................................ 10-6

...... 10-3

........... 10-3

... 10-5

........ 10-5

........ 10-7

Troubleshooting DCAM IEEE 1394 (FireWire)

Hardware

Troubleshooting D CAM IEEE 1394 Hardware Installing the CMU DCAM Driver Running the CMU Camera Demo Application

....................................... 10-8

.................... 10-9

.......... 10-8

.......... 10-10

Troubleshooting Hamamatsu Hardware

Troubleshooting Matrox Hardware

Troubleshooting M atrox Devices Determining the Driver Version for Matrox Devices

Troubleshooting QImaging Hardware

Troubleshooting QImaging Devices Determining the Driver Version for QImaging Devices

Troubleshooting National Instruments Hardware

Troubleshooting National Instruments Devices Determining the Driv er Version for Natio na l Instruments

Devices

Troubleshooting Windows Video Hardware

Troubleshooting Windows Video Devices Determining the Microsoft DirectX Version

Troubleshooting a Video Preview Window

Contacting The MathWorks and Using the imaqsupport

Function

........................................ 10-21

........................................ 10-26

..................... 10-16

................... 10-18

............. 10-15

.................. 10-16

..... 10-17

............... 10-18

... 10-19

.... 10-20

......... 10-20

.......... 10-22

.............. 10-22

............ 10-23

........... 10-25

xii Contents

Function Reference

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

Triggering

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

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

Tools

Getting Command-Line Function Help

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

.............. 11-5

Functions — Alphabetical List

Property Reference

Video Input Objects ................................ 13-2

General Callback Triggering Acquisition Source

Video Source Objects

......................................... 13-2

......................................... 13-3

....................................... 13-4

................................. 13-5

.............................. 13-6

xiii

Properties — Alphabetical List

Block Reference

Examples

Fundamentals ..................................... A-2

Previewing

Image A cquisition Tool (GUI)

Acquiring Image Data

Working with Acquired Data

Events and Callbacks

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

.............................. A-3

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

....................... A-3

Index

xiv Contents

Getting Started

The best way to learn about Image Acquisition Toolbox™ capabilities is to look at a simple example. This chapter introduces the toolbox and illustrates the basic steps to create an image acquisition application by implementing a simple motion detection application. The example cross-references other sections 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

Introduction

The Image Acquisition Toolbox software is a collection of functions that extend the capability of the MATLAB toolbox supports a wide range of ima ge acquisition operations, incl ud ing:

In this section...

“Introduction” on page 1-2

“Installation and Configuration Notes” on page 1-3

“The Image Processing Toolbox Software Required to Use the Image Acquisition Toolbox Software” on page 1-3

“Related Products” on page 1-4

“Supported Hardware” on page 1-4

numeric computing environment. The

1-2

• Acquiring images through many types of image acquisition devices, from

professional 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 MATLAB code for these functions using this statement:

type function_name

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

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 into a model.

Installation and Configuration Notes

To determine if the Image Acquisition Toolbox software is installed on your system, type this command at the MATLAB prompt:

ver

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

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

For the most up-to-date information about system requirements, see the system requirements page, available in the products area at the MathWorks Web site (

www.mathworks.com).

The Image Processing Toolbox Sof tware Required to Use the Image Acquisition Toolbox Software

The Image Acquisition Toolbox product, including the Image Acquisition Tool, now requires you to have a license for the Image Processing Toolbox product starting in R2008b.

If you already hav e the Image Processing Toolbo x product, yo u do no t need to do anything.

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

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

1-3

1 Getting Started

and click the Supported Hardware

1-4

Image Acquisition Tool (GUI)

In Version 3.0 of the toolbox, the functionality of the Image Acquisition Toolbox software is available in a desktop application. You connect directly to your hardware in the tool and can set acquisition parameters, and preview and 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 > Image Acquisition Tool from MATLAB. The tool has extensive Help in the desktop. As you click in different panes of the user interface, the relevant Help appears in the Image Acquisition Tool Help pane.

Most of the User’s Guide describes performing tasks using the toolbox via the MATLAB command line. To learn how to use the desktop tool, see Chapter 3, “Using the Image Acquisition Tool GUI”.

Image Acquisition Tool (GUI)

1-5

1 Getting Started

Basic Image Acquisition Procedure

In this section...

“Overview” on page 1-6

“Step 1: Install Your Image Acquisition D evice” on page 1-7

“Step 2: Retrieve Hardware Information” on page 1-8

“Step3: CreateaVideoInputObject”onpage1-10

“Step 4: Preview the Video Stream (Optional)” on page 1-12

“Step 5: Configure Object Properties (Optional)” on page 1-14

“Step 6: Acquire Image Data” on page 1-17

“Step 7: Clean Up” on page 1-21

Overview

This section illustrates the basic steps required to create an image acquisition application by implementing a simple motion detection application. The application detects movement in a scene by performing a pixel-to-pixel comparison in pairs of incoming image frames. If nothing moves in the sce n e, pixel values remain the same in each frame. When something m oves in the image, the application displays the pixels that have changed values.

1-6

The example highlights how you can use the Image Acquisition Toolbox software to create a working image acquisition application with only a few lines of code.

Note To run the sample code in this example, you must have an image acquisition dev ice connected to your s ystem. The device can be a professional grade image acquisition device, such as a frame grabber, or a generic Microsoft canbeusedwithvarioustypesofdevices with only minor changes.

Windows®image a cquisition device, such as a webcam. The code

Basic Image Acquisition Procedure

To use the Image Acquisition Toolbox software to acquire image data, you must perform the fo ll owing basic steps.

Step Description

Step 1: Install and configure your image acquisition device

Step 2: Retrieve information that uniquely identifies your image

acquisition device to the Image Acquisition Toolbox software

Step 3: Create a video input object

Step 4: Preview the video stream (Optional)

Step 5: Configure image acquisit ion object properties (Optional)

Step 6: Acquire image data

Step 7: Clean up

Step 1: Install Your Image Acquisition Device

Follow 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 supplied

bythedevicevendor.

• Connecting a camera to a connector on the frame grabber board.

• Verifying that the camera is working properlybyrunningtheapplication

software that came with the camera and viewing a live video stream.

Generic Windows image acquisition devices, such as webcams and digital video camcorders, typically do not require the installation of a frame grabber board. You connect these devices directly to your computer via a USB or FireWire port.

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

1-7

1 Getting Started

Step 2: Retrieve Hardware Information

In this step, you get several pieces of information that the toolbox needs to uniquely identify the image acquisition device you want to access. You use this information when you create an image acquisition object, described in “Step 3: Create a Video Input Object” on page 1-10.

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

Device Information Description

Adaptor name An adaptor is the software that th e toolbox uses to

communicate with an image acquisition device via its device driver. The toolbox includes adaptors for certain vendors of image acquisition equipment and for particular classes o f image acquisition devices. See “Determining the Adaptor N ame” on page 1-9 for more information.

Device ID The device ID is a number that the adaptor assigns to

uniquely identify each image acquisition device with which it can communicate. See “Determining the Device ID” on page 1-9 for more information.

Note SpecifyingthedeviceIDisoptional;thetoolbox uses the first available device ID as the default.

Video format The video format specifies the ima ge resolution (width

and height) and other aspects of the video stream. Image acquisition devices typically support multi pl e v id eo formats. See “Determining the Supported Video Formats” on page 1-10 for more information.

imaqhwinfo function

1-8

Note Specifying the video format is optional; the toolbox uses on e of the supported formats as the default.

Basic Image Acquisition Procedure

Determining the Adaptor Name

To determine the name of the adaptor, enter the imaqhwinfo function at the MATLAB prompt without any arguments.

imaqhwinfo ans =

InstalledAdaptors: {'dcam' 'winvideo'}

MATLABVersion: '7.4 (R2007a)'

ToolboxName: 'Image Acquisition Toolbox'

ToolboxVersion: '2.1 (R2007a)'

In the data returned by imaqhwinfo,theInstalledAdaptors field lists the adaptors that are available on your computer. In this example, found two adaptors a vailable on the computer: 'dc am' and 'winvideo'.The listing on your computer might contain only one adaptor name. Select the adaptor name that provides access to your image acquisition device. For more information, see “Determining the Device Adaptor Name” on page 4-2.

imaqhwinfo

Determining the Device ID

To find the device ID of a particular image acquisition device, enter the

imaqhwinfo function at the MATLAB prompt, specifying the name of the

adaptor as the only argument. (You found the adaptor name in the first call to

imaqhwinfo, described in “Determining the Adaptor Name” on page 1-9.) In

the data returned, the IDs of all the devices accessible through the specified adaptor.

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

info = imaqhwinfo('dcam') info =

AdaptorDllName: [1x77 char]

AdaptorDllVersion: '2.1 (R2007a)'

AdaptorName: 'dcam'

DeviceIDs field is a cell array containing the device

DeviceIDs: {[1]}

1-9

1 Getting Started

DeviceInfo: [1x1 struct]

Determining the Suppor ted Video F ormats

To determine which video formats an image a cquisition device supports, look in the

DeviceInfo field of the data returned by imaqhwinfo.TheDeviceInfo

field i s a structure array where each structure provides information about a particular device. To view the device information for a particular device, you can use the device ID as a reference into the s tructure array. Alternatively, you can view the information for a particular device by calling the function, specifying the adaptor name and device ID as arguments.

To get the list of the video formats suppo rted by a device, look at

SupportedFormats field in the device information structure. The SupportedFormats field is a cell array of strings where each string is the

name of a video format supported by the device. For more information, see “Determining Supported Video Formats” on page 4-5.

dev_info = imaqhwinfo('dcam',1)

imaqhwinfo

1-10

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 Object

In this step yo u create the video input object that the toolbox uses to represent the conne ction between MATLAB and an image acquisition device. Using the properties of a video input object, you can control many a spects of the image acquisition process. For more information about image acquisition objects, see Chapter 4, “Connecting to Hardware”.

To create a video input object, use the prompt. The contains the default

DeviceInfo structure returned by the i maqhwinfo function

videoinput function syntax for a device in the

videoinput function at the MATLAB

Basic Image Acquisition Procedure

ObjectConstructor field. For more information the device information

structure, 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 n am e of the image acquisition device avail able on your 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. The adaptor name is the only required argument; the

videoinput function can

usedefaultsforthedeviceIDandvideoformat. Todeterminethedefault video format, look at the

DefaultFormat field in the d evice information

structure. See “Determining the Supported Video Formats” on page 1-10 for more information.

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

Viewing the Video Input Object Summary

To view a summary of the video input object you just created, enter the variable name ( information displayed shows many of the characteristics of the object, such asthenumberofframesthatwillbecapturedwitheachtrigger,thetrigger type, and the current state of the object. You can use video input object properties to control many of these characteristics. See “Step 5: Configure Object Properties (Option a l) ” on page 1-14 for m ore information.

vid

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

Acquisition Source(s): inp ut1 is available.

Acquisition Parameters: 'inp ut1' is the current selected source.

vid) at the MATLAB command prompt. The summary

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 image acquisition 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 the image is satisfactory. For example, you might want to change the position of the camera, change the lighting, correct the focus, or make some other change to your image acquisition setup.

1-12

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

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

preview(vid)

The previ ew function opens a Video Preview figure window on your screen containingthelivevideostream. Tostopthestreamoflivevideo,youcan call the

stoppreview function. To restart the preview stream, call preview

again on the same video input object.

While a preview window is open, the video input object sets the value of the

Previewing property to 'on'. If you change characteristics of the image

by setting image acquisition object properties, the image displayed in the preview window reflects the change.

Basic Image Acquisition Procedure

The follow ing figure show s the Vide o Preview window for the example.

Video Preview Window

To close the Video Preview window, click the Close button in the title bar or use the argument.

Calling closeprev iew without any arguments closes all open Video Preview windows.

closepreview function, specifying the video input object as an

closepreview(vid)

1-13

1 Getting Started

Step 5: Configure Object Properties ( Optional)

After creating the video input object and previewing the video stream, you might want to modify characteristics of the image or other aspects of the acquisition process. You accomplish this by setting the values of image acquisition object properties. This section

• Describesthetypesofimageacquisition objects used by the toolbox

• Describes how to view all the properties supported by these objects, with

their current values

• Describes how to set the values of object properties

Types of Image Acquisition Objects

The toolbox uses two types of objects to represent the connection with an image acquisition device:

• Video input objects

• Video source objects

1-14

A video input object represents the connection between MATLAB and a video acquisition device at a high level. The propertie s supported b y the video input object are the same for every type of device. Y ou created a video input object using the

When you create a video input object, the toolbox automatically creates one or more video source objects associated with the video input object. Each video source object represents a collection of one or more physical data sources that are treated as a single entity. The number of video source objects the toolbox creates depends on the device and the video format you specify. At any one time, only one of the video source objects, called the selected source, can be active. This is the source used for acquisition. For more information about these image acquisition objects, see “Creating Image Acquisition Objects” on page 4-8.

videoinput function in step 3.

Viewing Object Properties

To vie w a complete list of all the properties supported by a video input object or a video source object, use the video input object created in step 3, enter this code at the MAT LAB prompt.

get function. To list the properties of the

Basic Image Acquisition Procedure

get(vid)

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

General Settings:

DeviceID = 1 DiskLogger = [] DiskLoggerFrameCount = 0 EventLog = [1x0 struct] FrameGrabInterval = 1 FramesAcquired = 0 FramesAvailable = 0 FramesPerTrigger = 10 Logging = off LoggingMode = memory Name = Y8_1024x768-dcam-1 NumberOfBands = 1 Previewing = on ReturnedColorSpace = grayscale ROIPosition = [0 0 1024 768] Running = off Tag = Timeout = 10 Type = videoinput UserData = [] VideoFormat = Y8_1024x768 VideoResolution = [1024 7 68] . . .

To view the properties of the currently selected video source object associated with this video input object, use the conjunction with the

get function. The getselectedsource function returns

getselectedsource function in

the currently active video source. To list the properties of the currently selected video source object associated with the video input object created in step 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 properties

supported by the device connected to your system might differ from the list showninthisexample.

General Settings:

Parent = [1x1 videoinput] Selected = on SourceName = input1 Tag = Type = videosource

Device Specific Properties:

FrameRate = 15 Gain = 2048 Shutter = 2715

Setting Object Properties

To set the value of a video input object property or a video source object property, you can use the as you would a field in a structure, using dot notation.

set function or you can reference the object property

1-16

Some properties are read only; you cannot set their values. These properties typically p rovide information about the state of the object. Other properties become read only when the object is running. To view a list of all the properties you can set, use the

set function, specifying the object as the

only argument.

To implement continuous image acquisition, the example sets the

TriggerRepeat 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 while processing data, the example sets the

FrameGrabInterval property to 5.This

specifies that the object acquire every fifth frame in the video stream. (You might need to experiment with the value of the

FrameGrabInterval property

to find a value that provides the best response with your image acquisition

Basic Image Acquisition Procedure

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

vid.FrameGrabInterval = 5;

To set the value of a video source object property, you must first use the

getselectedsource function to retrieve the object. (Y ou can also get the

selected source by searching the video input object video source object that has the

Selected property set to 'on'.)

Source property for the

To illustrate, the example assigns a value to the

vid_src = getselectedsource(vid);

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

Tag property.

Step 6: Acquire Image Data

After you create the video input object and configure its properties, you can acquire 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 the

start function. Starting an object prepares the object for data acquisition.

For example, starting an object locks the values of certain object properties

(they beco me read only). Starting an object does not initiate the acquiring

of image frames, however. The initiation of data logging depends on the

execution of a trigger.

The following example calls the

object. Objects stop when they have acquired the requested number of

frames. Because the example specifies a continuous acquisition, you m ust

call the

stop function to stop the object.

• Triggering the acquisition — To acquire data, a video input object must

execute a trigger. Triggers can occur in several ways, depending on how

the

TriggerType property is configured. F or example, if you specify an

immediate trigger, the object executes a trigger automatically, immediately

after it starts. If you specify a manual trigger, the object waits for a call

to the

trigger function before it initiates data acquisition. For more

information, see Chapter 5, “Acquiring Image Data”.

start function to start the video input

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,theobject

automatically begins exe cuting triggers and acquiring frames of data,

continuously.

• Bringing data into the MATLAB workspace — The toolbox stores

acquired data in a m emory buffer, a disk file, or bo th, depending on the

value of the video input object

data, you must bring it into the MATLAB workspace. To bring multiple

frames into the workspace, use the

the MATLAB workspace, you can manipulate it as you would any other

data. For more information, see Chapter 6, “Working with Acquired Image

Data”.

Note The toolbox provides a convenient way to acquire a single frame of image data that doesn’t require starting or triggering the object. See “Bringing a Single Frame into the Workspace” on page 6-10 for more information.

LoggingMode property. To work with this

getdata function. Once the data is in

1-18

Running the Example

To run the example, enter the following code at the MATLAB prompt. The example loops until a specified number of frames have been acquired. In each loop iteration, the example calls into the MATLAB workspace. To detect motion, the example subtracts one frame from the other, creating a difference image, and then displays it. Pixels that have changed values in the acquired frames will have nonzero values in thedifferenceimage.

The

getdata function removes frames from the memory buffer when it brings

them into the MATLAB workspace. It is important to move frames from the memory buffer into the M ATL AB workspace in a timely manner. If you do not move the acquired frames from memory, you can quickly exhaust all the memory available on your system.

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

% Create video input object.

getdata to bring the two most recent frames

Basic Image Acquisition Procedure

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 disp lay it. while(vid.FramesAcquired<=100) % Stop after 100 f rame s

data = getdata(vid,2); diff_im = imabsdiff(data(:,:,:,1),data(:,:,:,2)); imshow(diff_im);

end

stop(vid)

1-19

1 Getting Started

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

Figure Window Displayed by Example

1-20

Image Data in the MATLAB Workspace

In the example, the getdata function returns the image frames in the variable

data as a 480-by-640-by-1-by-10 array of 8-bit data (uint8).

whos

Name Size Bytes Class

data 4-D 3072000 uint8 array dev_info 1x1 1601 struct a rray info 1x1 2467 stru ct array vid 1x1 1138 videoinput object vid_src 1x1 726 videosource object

Theheightandwidthofthearrayareprimarilydeterminedbythevideo resolution of the video format. H owever, you can use the property to specify values that supersede the video resolution. Devices typically express video resolution as column-by-row; MATLAB expresses matrix dimensions as row-by-column.

ROIPosition

Basic Image Acquisition Procedure

The third dimension represents the number of color bands in the image. Because the example data is a g r ayscale im age, the third dimension is 1. For RGB formats, image frames have three bands: red is the first, green is the second, and blue is the third. The fourth dimension represents the number of frames that have been acquired from the video stream.

Step 7: Clean Up

When you finish using your image acquisition objects, you can remove them from memory and clear the MATLAB workspace of the variables associated with these objects.

delete(vid) clear close(gcf)

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

1-21

1 Getting Started

1-22

Introduction

This chapter describes the Image Acquisition Toolbox software and its components.

• “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-2

“Toolbox Components” on page 2-3

“The Image Processing Toolbox Software Required to Use the Image Acquisition Toolbox Software” on page 2-4

“The Image Acquisition Tool (GUI)” on page 2-4

“Supported Devices” on page 2-4

Introduction

The Image Acquisition Toolbox software implements an object-oriented approach to image acquisition. Using toolbox functions, you create an object that represents the connection between MATLAB and specific image acquisition devices. Using properties of the object you can control various aspects of the acquisition process, such as the amount of video data you want to capture. Chapter 4, “Connecting to Hardware” describes how to create objects.

2-2

Once you establish a connection to a device, you can acquire image data by executing a trigger. In the toolbox, all image acquisition is initiated by a trigger. The toolbox supports sever al types of triggers that let you control when an acquisition takes place. For e xample, using hardware triggers you can synchro ni ze an acquisitio n with an external device. Chapter 5 , “Acquiring Image Data” describes how to trigger the acquisition of image data.

To work with the data you acquire, you must bring it into the MATLAB workspace. When the frames are acquired, the toolbox stores them in a memory buffer. The toolbox provides several ways to bring one or more frames of data into the workspace where you can manipulate it as you would any other multidimensional numeric array. Chapter 6, “Working with Acquired Image Data” describes this process.

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

function with a particular event. Chapter 7, “Using Events and Callbacks” describes this process.

Toolbox Components

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

The follo wing figure shows these components and their relationship.

Overview

The Image Acquisition Toolbox™ Software Components

2-3

2 Introduction

The Image Processing Toolbox Sof tware Required to Use the Image Acquisition Toolbox Software

The Image Acquisition Toolbox product, including the Image Acquisition Tool, now requires you to have a license for the Image Processing Toolbox product starting in R2008b.

If you already hav e the Image Processing Toolbo x product, yo u do no t need to do anything.

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

2-4

The Image Acquisition Tool (GUI)

In Version 3.0 of the toolbox, the functionality of the Image Acquisition Toolbox software is available in a desktop application. You connect directly to your hardware in the tool and can then set acquisition parameters, and preview and acquire imag e data. You can log the data to MATLAB in sev eral formats, and also generate an AVI file, right from the tool.

Most of the User’s Guide describes performing tasks using the toolbox via the MATLAB command line. To learn how to use the desktop tool, see Chapter 3, “Using the Image Acquisition Tool GUI”.

Supported Devices

The Image Acquisition Toolbox software includes adaptors that provi de support for several vendors of professional grade image acquisition

equipment, devices that support the IIDC 1394-based Digital Cam era Specification (DCAM), and devices that provide Windows Driver Model (WDM) or Video for Windows (VFW) drivers, such as USB and IEEE (FireWire, i.LINK

) Web cameras, Digital video (DV) camcorders, and TV

1394

tuner cards. For the latest information about supported hardware, visit the Image Acquisition Toolbox product page at the MathWorks Web site (

www.mathworks.com/products/imaq).

The DCAM specification, developed by the 1394 Trade Association, describes a generic interf ace for exchanging data with IEEE 1394 (FireWire) digital cameras that is often used in scientific applications. The toolbox’s DCAM adaptor supports Format 7, also known as partial s can mode. The toolbox uses 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 DCAM driver. T he toolbox is not compatible with any other vendor-supplied driver, even if the driver is DCAM compliant.

Overview

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

2-5

2 Introduction

Setting Up Image Acquisition Hardware

In this section...

“Introduction” on page 2-6

“Setting Up Frame Grabbers” on page 2-6

“Setting Up Generic Windows Video Acquisition Devices” on page 2-7

“Setting Up DCAM Devices” on page 2-7

“Resetting Your Image Acquisition Hardware” on page 2-7

“A Note About Frame Rates and Processing Speed” on page 2-7

Introduction

To acquire image data, you must perform the setup required by your particular image acquisition device. In a typical imag e acquisition setup, an image acquisition device, such as a camera, is connected to a computer via an image acquisition board, such as a frame grabber, or via a Universal Serial Bus (USB) or IEEE 1394 (FireWire) port. The setup required varies with the type of device.

2-6

Setting Up Frame Grabbers

For frame grabbers, also known as imaging boards, setup typically involves the following tasks:

• Installing the frame grabber in your computer

• Installing any software drivers required by the frame grabber. These are

supplied by the device vendor.

• Connecting the camera, or other image acquisition device, to a connector

on the frame grabber

• Verifying that the camera is working properlybyrunningtheapplication

software that came with the frame grabber and viewing a live video stream

Setting Up Image Acquisition Hardware

Setting Up Gener Devices

IEEE 1394 (FireW Windows Driver typically req (FireWire) po the vendor.

Setting Up DC

If you intend must instal driver. The even if the d Driver” on

Resettin

To return wherenoi use the

If you co is start hardwa

l and configure the Carnegie Mellon University (CMU) DCAM

page 10-9 for more information.

g Your Image Acquisition Hardware

MATLAB and your image acquisition hardware to a known state,

mage acquisition objects exist and the hardware is not configured,

maqreset

nnect another image acquisition device to your system after MATLAB

ed, you can use

re.

ire) and generic Win d ows video acquisition d evices that use

Model (WDM) or Video for Windows (VFW) device drivers

uire less setup. Plug the device into the USB or IEEE 1394

rt on your computer and install the device driver provided by

AM Devices

to access a DCAM-compliant IEEE 1394 (FireWire) camera, you

toolbox is not compatible with any other vendor-supplied driver,

river is DCAM compliant. See “Installing the CMU DCAM

function.

imaqreset to make the toolbox aware of the new

ic Windows Video Acquisition

ANote

The fr typic

ces that support industry-standard video formats must provide frames

Devi at th

ates a frame rate of 30 frames per second (30 Hz). The CCIR and

dict PAL

figured to operate at higher rates. Generic Windows image acquisition

con

ices,suchaswebcams,mightsupport many different frame rates.

dev

ending on the device being used, the frame rate might be configurable

Dep

ing a device-specific property of the image acquisition object.

About Frame Rates and Processing Speed

ame rate describes how fast an image acquisition device provides data,

ally measured as frames per second.

e rate specified by the standard. For RS170 and NTSC, the standard

standards define a frame rate of 25 Hz. Nonstandard devices can be

2-7

2 Introduction

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

2-8

Previewing Data

In this section...

“Introduction” on page 2-9

“Opening a Vid eo Preview Window” on page 2-10

“Stopping the Preview Video Stream” on page 2-11

“Closing a Video Preview Window” on page 2-12

“Previewing Data in Custom GUIs” on page 2-12

“Performing Custom Processing of Previewed Data” on page 2-14

Introduction

After you connect MATLAB to the image acquisition device(seeChapter4, “Connecting to Hardware”), you can view the live video stream using the Video Preview window. Previewing the video data can help you make sure that the image being captured is satisfactory.

Previewing Data

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

The following sections provide more information about using the Video Preview 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 toolbox’s Vide o Preview window, you can display the live video preview stream in any Handle Graphics this way, you can include video previewing in a GUI of your own creation. The following sections describe this capability.

• “Previewing Data in Custom GUIs” on page 2-12

image object you specify. In

2-9

2 Introduction

• “Performing Custom Processing of Preview ed Data” on page 2-14

Note The Image Acquisition Toolbox Preview window and the Preview

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

getsnapshot or getdata functions.

Opening a Video Preview Window

To open a Video Preview window, use the preview function. T he Video Preview window display s the live video stream from the device. You can on l y open one preview window per device. If multiple devices are used, you can open multiple preview windo ws at the same time.

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

2-10

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

The following figure shows the Video Preview window created by this example. The Video Preview window displays the live video stream. The size of the preview image is determined by the value of the video input object’s

ROIPosition property. The Video Preview windo w displays the video data at

100% magnification (one screen pixel represents one image pixel).

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

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

Previewing Data

Note The window to 16-b data, b window data i the fu

Stop

When

iew window displays a view of the live video stream coming from the

ice. To stop the updating of the live video stream, call the

dev

ction.

fun

Image Acquisition Toolbox P review window and the Preview

that is built into the Image Acquisition Tool support the display of up it image data. The Preview window was designed to only show 8-bit ut many cameras return 10-, 12-, 14-, or 16-bit data. The Preview

display supports these higher bit-depth cam eras. However, larger bit

s scaled to 8-bit for the purpose of displaying previewed data. If you need ll resolution of the data, use the

getsnapshot or getdata functions.

ping the Preview Video S tream

you use the

preview function to start previewing image data, the V ideo

stoppreview

2-11

2 Introduction

This example creates a video input object and opens a Video Preview window. The example then calls the The Video Preview window stops updating the image displayed and stops updating the timestamp. The status displayed in the Video Preview window also 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 again on the same video input object.

preview(vid)

stoppreview function on this video input object.

Closing a Video Preview Window

To close a particular VideoPreviewwindow,usetheclosepreview function, specifying the video input o bj ect as an argument. You do n ot need to stop the live video stream displayed in the Video Preview window before closing it.

2-12

closepreview(vid)

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

closepreview

Note When called without an argument, the closepreview function only closes Video Preview windows. The otherfigurewindowsinwhichyouhavedirectedthelivepreviewvideostream. For m ore information, see “Previewing Data in Custo m GUIs” o n page 2-12.

closepreview function does not close any

Previewing Data in Custom GUIs

Instead of using the toolbox’s Video Preview window, you can use the preview function to direct the live video stream to any Handle Graphics image object. In this way, you can incorporate the toolbox’s previewing capability in a GUI of your own creation. (You can also perform custom processing as the live video is displayed. For information, see “Perform ing Custom Processing of Previewed Data” on page 2-14.)

Previewing Data

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

The following example creates a figure window and then creates an image objectinthefigure,thesamesizeasthevideoframes.Theexamplethencalls the

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 fi gur e 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 Pre

Performi

When you Data in C that

pre

To use t

1 Create

updat “Crea

2 Create an image object.

3 Configure the value of the image object’s 'UpdatePreviewWindowFcn'

view

ng Custom Processing of Previewed Data

specify an image object to the

ustom GUIs” on page 2-12), you can optionally also specify a function

view

executes every time it receives an image frame.

his capability, follow thes e steps:

the function you want executed for each image frame, called the

e preview window function. For information about this function, see

ting the Update Preview Window Function” on page 2-15.

preview function (see “Previewing

application-defined data to be a function handle to your update preview window function. For more information, see “Specifying the Update Preview Function” on page 2-16.

lthe

4 Cal

an a

preview function, specifying the handle of the image object as

rgument.

2-14

Previewing Data

Note If you specify an update preview window function, in addition to whatever processing your function performs, it must display the video data in the image object. You can do this by updating the

CData of the image

object with the incoming video frames. For some performance guidelines about updating the data displayed in an image object, see Technical Solution 1-1B022.

Creating the Update Preview Window Function

When preview calls the update preview window function you specify, it passes your function the following arguments.

Argument Description

obj

event

himage

Handle to the video input object being previewed

A data structure containing the following fields:

Data

Current image frame specified as an H-by-W-by-B array, where H is the image height and W is the image width, as specified in the

ROIPosition property, and

B is the number of color bands, as specified

Resolution

in the

Text string specifying the current image

NumberOfBands property

width and height, a s defined by the

ROIPosition property

Status

String describing the status of the video input object

Timestamp

String specifying the time associated with the current image frame, in the format

hh:mm:ss:ms

Handle to the image object in which the data is to be displayed

The following example creates an update preview window function that displays 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 to retrieve a handle to the text label

uicontrol object from application-defined

data in the im age object. The custom G U Istoresthishandletothetextlabel

uicontrol object — see “Specifying the Update Preview Function” on page

2-16.

Note that the update preview window function also displays the video data by updating the

function mypreview_fcn(obj,event,himage) % Example update preview w ind ow 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);

CData of the image object.

2-16

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

Specifying the Update Preview Function

To use an update preview window function, store a function handle to your function in the the image object. The following example uses th e configure this application-defined data to a function handle to the update preview window function described in “Creating the Update Preview Window Function” on page 2-15.

This example extends the simple custom preview window created in “Previewing Data in Custom GUIs” on page 2-12. This example adds three push button and Close Preview.

In addition, to illustrate using an update preview window function, the example GU I includes a text label

'UpdatePreviewWindowFcn' application-defined data of

setappdata function to

uicontrol objects to the GUI: Start Preview, Stop Preview,

uicontrol object to display the timestamp

Previewing Data

value. The update p review window function updates this text label each time a framed is received. The example uses to the text label

uicontrol object in application-defined data in the image

setappdata to store a handle

object. The update preview window function retrieves this handle to update the 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 buttons uicontrol('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 .0 7]);

% Create the text label for the timestamp hTextLabel = 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);

2-18

preview(vid, hImage);

Previewing Data

When you run this example, it creates th e GUI shown in the following figure. Each time

preview receives a video frame, it calls the update preview window

function that you specified, which updates the timestamp text label in the GUI.

Custom Preview GUI with Timestamp Text Label

2-19

2 Introduction

2-20

Using the Image Acquisition Tool 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 T hird-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-2

“Parts of the Desktop” on page 3-2

Opening the Tool

Image Acquisition Toolbox functionality is now available in a desktop application. You connect directly to your hardware in the tool and can preview and 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 a preview/acquisition area with Acquisition Parameters so that you can change settings and see the changes dynamically applied to your image data.

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

3-2

• Type

• Select Start > Toolboxes > Image Acquisition > Image Acquisition

Note The right pane in the tool is the Help pane. As you work in the tool

the Help will provide information for the part of the interface that you are working in. If the Help is closed, you can open it be selecting Desktop > Image Acquisition Tool Help.

imaqtool at the MATLAB command line.

Tool (imaqtool) from MATLAB.

Parts of the Desktop

The Image Acquisi tion Tool has the following panes.

The Image Acquisition Tool Deskto p

• Hardware Browser – Shows the image acquisition devices currently

connected to your system. Each device is a separate node in the browser. All of the formats the device supports are listed under the device. Each device’s default format is indicated in parentheses. Select the device format or camera file you want to use for the acquisition. When the format is selected, you can then set acquisition parameters and preview your data.

3-3

3 Using the Image Acquisition Tool GUI

See “Se lecting Your Device” on page 3-5 for more information about using the Hardware Browser.

• Preview window – Use to preview and acquire image data from the

selected device format, and to export data that has been acquired in memory to a MAT-file, the MATLAB Workspace, or to tools provided by the Image Processing Toolbox softw are. See “Previewing and Acquiring Data” on page 3-25 for more information about using the Preview window.

• Acquisition Parameters – Use these tabs to set up general acquisition

parameters, such as frames per trigger and color space, device-specific properties, logging options, triggering options, and region of interest. Settings you make on any tab will apply to the currently selected device format in the Hardware Browser. See “Setting Acquisition Parameters” on page 3-8 for more information about using the Acquisition Parameters. Also see the Help for each tab while using the tool for more details. When you click any tab, the help for that tab will appear in the Image Acquisition Tool Help pane.

• Information pane – Displays a summary o f information about the

selected node in the Hardware Browser.

3-4

• Session Log – Displays a dynamically generated log of the commands that

correspond to actions taken in the tool. You can save the log to a MATLAB code file or copy it.

• Image Acquisition Tool Help – Displays Help for the pane of the desktop

that has focus. Click inside a pane for help on that area of the tool. For the Acquisition Parameters pane, click each tab to display information about the settings for that tab.

If the Help is closed, you can open it by selecting Desktop > Image Acquisition Tool Help.

Selecting Your Device

In this section...

“Selecting a Device and Format” on page 3-5

“Adding New Hardware” on page 3-6

“UsingaCameraFile”onpage3-7

Selecting a Device and Format

The Hardware Browser pane shows the image acquisition devices currently connected to your system. Each device is a separate node in the browser. All of the formats the device supports are listed under the device. Each device’s defaultformatisindicatedinparentheses. The format information displayed under a device comes from the device’s adaptor.

Selecting Your Device

3-5

3 Using the Image Acquisition Tool GUI

3-6

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

Adding New Hardware

When you open the Image Acquisition Tool, the Hardware Browser automatically shows the image acquisition devices supported by the toolbox that are currently connected to your system. If you plug a new device in while the Image Acquisition Tool is open, select Tools > Refresh Image

Selecting Your Device

Acquisition Hardware to display the new device in the Hardware Browser.

Using a Camera File

If your device supports the use of a camera file, also known as a device configuration file, you can select it under the device name in the Hardware Browser. For example, some frame grabbers support them.

Under the device name in the Hardware Browser, you would see a node that says 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 name

that says Click to add cam era file....

2 In the Specify camera file dialog box, type the path and name of the file, or

click the Browse button to locate it, and then click OK.

Thecamerafilewillthenbecomeanewnodeunderthedevice,similar to any of the formats listed under a device. You can then set acquisition parameters, preview, and acquire data using it.

Note The tool ignores hardware triggerconfigurationsincludedina camera file. To configure hardware triggering, use the Trigger tab in the

Acquisition Parameters pane.

3-7

3 Using the Image Acquisition Tool GUI

Setting Acquisition Parameters

In this section...

“Using the Acquisition Parameters Pane” on page 3-8

“Setting Frames Per Trigger” on page 3-9

“Setting the Color Space” on page 3-10

“Setting Device-Specific Parameters” on page 3-10

“Logging Your Data” on page 3-13

“Setting Up Triggering” on page 3-15

“Setting a Region of Interest” on page 3-18

“Restoring Default P a r am e t ers” on page 3-24

Using the Acquisition Parameters Pane

The tool allows you to set acquisition parameters directly in the desktop using the Acquisition Param eters pane. Settings you make will apply to the currently selected device format in the Hardware Browser.

3-8

The Acquisition Parameters pane contains the following tabs:

• General – Use to set up general acquisition parameters, such as frames

per 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, which

determines 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 Logging option on this tab.

• Triggering – Use to set up triggering options, such as number of triggers

and trigger type. If you want to do manual triggering using the Trigger button, use the Trigger Type option on this tab.

• Region of Interest – Use to set a Region of Interest (R OI) if you only

want to use part of an image.

Setting Acquisition Parameters

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

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

Setting Frames Per Trigger

The Frames Per Trigger fi eld on the General tabisusedtosetthenumber of frames per trigger you want to acquire.

• If you want your acquisition to be a specific num ber of frames per trigger,

use the default of or type in the number.

• If you want to acquire frames continuously, set the Frames Per Trigger

infinite and then use the Stop Acquisition button to stop the

acquisition, or do manual triggering using the Triggering tab.

1 frame, or use the arrows to select the number of frames

3-9

3 Using the Image Acquisition Tool GUI

The number of frames that will be acquired when you start an acquisition depends on what is set in the Frames Per Trigger field on the General tab and the Number of Triggers field on the Triggering tab. For example, if you set Frames Per Trigger to number of frames acquired will b e 8.

4 and Number of Triggers to 2, the total

Note that if you set Frames Per Trigger to Number of Triggers on the Triggering tab.

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

infinite,youcannotset

Setting the Color Space

Use Color Space on the General tab to set the color space for the selected device format. The Returned Color Space field has three options:

YCbCr,andgrayscale. The setting that is your device format’s default color

space is shown as the default. You can use the arrow to select another setting.

Additionally, if the default color space is be available in the Returned Color Space field for some devices, and the Bayer Sensor Alignment field will also be displayed. Use the drop-down list to select one of the four possible sensor alignments. This feature allows the tool to demosaic Bayer patterns returned by the hardware and interpolate them into standard RGB color images. For more information about this feature, see the

BayerSensorAlignment property reference page.

grayscale,avalueofbayer will

rgb,

3-10

Setting Device-Specific Parameters

View or change device-specific properties using the Device Properties tab. The selected device’s properties appear in the Properties area. The specific properties that appear depend on your device.

Setting Acquisition Parameters

The Selected source field specifies the n ame of the selected source for the current device. Many device adaptors only have one input source, so for example, this might show some thing like

input1, port1,orinput0 by

default. If your device supports multiple source names, they will appear in the 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 select

a value from the list.

• If a property has a value listed that is grayed out, then that value is not

currently editable.

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

3-11

3 Using the Image Acquisition Tool GUI

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

Property Help

To get help on any of the properties in the Devic e Properties tab, right-click a p roperty and select What’s This?.AHelp window opens and displays the help for the selected property, as well as the rest of the properties, which are available by scrolling. This is th e same information as the device help you access using the device-specific properties, see your device’s documentation.

Note About Frame Rate

FrameRate appears in the Properties area, that means your device has a

FrameRate property. The information in the table comes from your device.

The value set there will be the fram e rate that your device uses, in frames per second.

imaqhelp command. For more detailed information on

3-12

FrameRate does not appear in the list, your device does not support that

property.

Setting Acquisition Parameters

Logging Your Data

Set logging options using the Logging tab. This determines where your data is logged to when you do an acquisition.

Use the Log to options to select where your acquisition will be logged. Select one of the following:

• Memory — Acquisiti on will be logged to memory. This means that the

acquired data that you do not otherwise save (using Export Data)willbe logged to your system’s memory, and will be available to you only during the acquisition session. The data will be lost if you do another acquisition, or you close the tool without exporting the data. This is the default setting.

• Disk — Acquisition will be logged to disk as an AVI file, in the location you

specify in the Disk logging area. This means that the acquired data will be logged to disk and will be available to you there after the acquisition session. When you select Disk,theDisk logging area becomes editable and yo u can enter or browse to the location and name the file.

• Disk and memory — Acquisition will be logged to both disk, in the

location you specify in the Disk logging area, and memory.

3-13

3 Using the Image Acquisition Tool GUI

Memory Logging

If you select Memory or Disk and memory in the Log to options, the Memory limit field will display how much memory is available on your

system.

This equals the total number of bytes that image acquisition frames can occupy in memory. By default, the tool sets this limit to equal all available physical memory when you first use the tool, or 1 GB, whichever is less.

Disk Logging

If you select Disk or Disk and memory in the Log to options, the Disk logging area will become editable so you can designate a file and location to

save to.

Note AVI files are limited to a bit-depth of 8 bits p er pixel for each band. If you have higher bit data, you should not log it to an AVI file since the AVI format is restricted to 8-bit data. If you do log higher bit data to an AVI file, it will be scaled and then logged as 8-bit data.

3-14

To use disk logging:

1 Click the Browse button to select a location for the file, or type the location.

2 IntheOpendialogbox,enteranameintheFile name field, and click

Open.

The

.avi extension is appended to the name on the Logging tab, and

the other fields will become editable.

3 Optionally select Automatically increm ent filename if you want

the tool to name subsequent acquisitions using the same root name, plus an incremented number. For example, if you enter the file name

experiment.avi and then check this option, it will be replaced by experiment_0001.avi,followedbyexperiment_000 2.av i,etc.

This o ption is useful if you want to acquire multiple videos of one or more subjects. For example, a lab technician may want to acquire 10 seconds of video on a group of five different cultures and save them for later analysis.

Setting Acquisition Parameters

The technician may want resulting file names such as sample_0001.avi,

sample_0002.avi,etc.

4 Leave Compression set to the default of None, or select a compression

codec f rom the drop-down list to enable file compression. The compre ssion choices are devices also support

Indeo3, Indeo5,andCinepak for most devices. Grayscale

MSVC and RLE.

If you select a compression codec, set the Quality and Key frames per second fields or leave the default settings. For the Quality setting,

lowering the number results in smaller log files, but a lower quality. The MATLAB default is

75%. The Key frames per second field determines

the ratio of frames that get co m pressed versus frames that just calculate thedeltafromthelastframe. Thevalueof

2.14 is the MATLAB default.

Larger numbers would result in a higher image quality, but a larger log file. The trade-off is quality of the image versus size of the log file.

5 Set your Frame Rate, which is the rate in frames per second that the

logged AVI file is displayed when you play it back. Keep the default of or enter a new rate.

Setting Up Triggering

Use the Triggering tab to set up triggering options.

3-15

3 Using the Image Acquisition Tool GUI

The total number of frames that will be acquired when you start an acquisition depends on what is set in the Frames Per Trigger field on the General tab and the Number of Triggers field on the Triggering tab. For example, if you set Frames Per Trigger to number of frames in the acquisition will be 8.

Selecting the Number of Triggers

If you want to do an acquisition that is comprised of a finite number of frames, set the Number of Triggers to any number, or use the default of

If you want to control the start and stop of the acquisition, regardless of the number of frames acquired, select triggers, you stop the acquisition manually by clicking the Stop Acquisition buttoninthePreview window.

Selecting the Trigger Type

The default of Immediate means that when you start an acquisition using the Start Acquisition button, the acquisition begins immediately.

4 and Number of Triggers to 2, the total

1 trigger.

infinite. With an infinite number of

3-16

If you change the setting to

Manual,theTrigger button is activated in the

Preview window, and you use it to start the acquisition.

To perform manual triggering:

1 Select your dev ice format and optionally click Start Preview to preview

the device.

2 Optionally set any acquisition parameters and stop the preview.

3 Select Manual in the Trigger Type field on the Triggering tab.

4 Click the Start Acquisition button to get live feed from the d evice.

The Trigger button is activated in the Preview window once the acquisition starts.

5 Click the Trigger button when you want to start logging data.

Setting Acquisition Parameters

If you have a defined number of triggers (not infinite), then the acquisition will stop when you have acquired that number of frames, based on the Frames Per Trigger field on the General tab.

If Number of Triggers is set to

infinite,usetheStop Acquisition

button to stop the acquisition.

If your device supports hardware triggering, that option will also appear in the Trigger Type field.

To perform hardware triggering:

1 Select your dev ice format and optionally click Start Preview to preview

the device.

2 Optionally set any acquisition parameters and stop the preview.

3 Select Hardware in the Trigger Type field on the Triggering tab.

4 Select your Trigger Source. This indicates the hardware source that is

monitored f or trigger conditions. When the condition specified in Trigger Condition is met, the trigger is executed and the acquisition starts.

3-17

3 Using the Image Acquisition Tool GUI

Trigger Source is device-specific. The drop-down list will show the mechanisms your particular device uses to generate triggers. F or example, it might be something like

5 Select your Trigger Condition. This specifies the condition that must

be met, via the Trigger Source, before a trigger event occurs. Trigger Condition is device-specific. The drop-down list will show the conditions

your particular device uses to generate triggers. For example, it m ight be something like

6 Click the Start Acquisition button to get live feed from the d evice.

7 When the Trigger Condition is met, the acquisition begins.

If you have a defined number of triggers (not infinite), then the acquisition will stop when you have acquired that number of frames, based on the Frames Per Trigger field on the General tab.

Port0 and Port1,orOptoTrig and TTL.

risingEdge and fallingEdge.

If Number of Triggers is set to button to stop the acquisition.

infinite,usetheStop Acquisition

Setting a Region of Interest

By default your acquisition will consist of the entire frame that the device acquires, which is equal to the sele cted format’s resolution. If you want to acquire a portion of the frame, use the Region of Interest ta b to set the desired r eg ion. The ROI window defines the actual size of the frame logged by the tool, measured with respect to the top-left corner of an image fram e.

You can set a Region of Interest (ROI) manually by using the Manual Configuration settings on the Region of Interest tab, or interactively in the Preview Window.

Setting Region of Interest Manually

To set up an ROI manually using the Manual Configuration field on the Region of Interest tab:

1 Start your preview by clicking the Start Preview button in the Preview

Window.

3-18

Setting Acquisition Parameters

2 AdjustoneormoreoftheX-Offset, Y-Offset, Width,orHeight settings

until you reach the desired region.

Use the arrows in each field to adjust the numbers. The preview resizes as you make changes.

3 When the

Start A

Note: Y

region is the desired size, start your acquisition by clicking the

cquisition button.

ou cannot adjust the ROI after starting the acquisition.

Setting Region of Interest Interactively

n also set a region of interest interactively while previewing you r image.

You ca

t a region of interest interactively:

To se

t your preview by clicking the Start Preview button in the Preview

1 Star

dow.

Win

2 Click the Select Region of Interest button in the top-left corner of the

Preview Window to activate the interactive RO I feature.

3-19

3 Using the Image Acquisition Tool GUI

3-20

Your cursor becomes a selection tool.

Note that the Select Region of Interest button is enabled only during preview mode.

Setting Acquisition Parameters

3 Position the cursor at one of the edges of the region you want to capture and

click the left mouse button. Hold the button while dragging the selection tool over the image to outline the region you want to capture.

4 Releasethemousebuttontofreezetheregion.

The region is not se t until you take action t o commit it.

3-21

3 Using the Image Acquisition Tool GUI

3-22

5 If the selected area is the region you want to use, start your acquisition by

clicking the Start Acquisition button.

his case, the region appears as follows.

In t

Setting Acquisition Parameters

Before starting the acquisition, if you want to adjust the region further, you can drag the selected region around while still in selection mode. You can also drag any of the handles on the region outline to change the dimensions of the region. You can then commit the region by pressing Enter or using the right-click menu Commit Region of Interest inside the region. You

3-23

3 Using the Image Acquisition Tool GUI

can also commit a region by pressing the space bar or double-clicking inside the selection, or starting the acquisition.

You can clear the drawn region before you commit it by single-clicking anywhere in the Preview Window outside of the selected area. You will still be in ROI selection mode. If you want to clear the selected region and exit ROI selection mode, press the Delete key, press the Escape key, or use the right-click menu Exit Region of Interest Mode inside the region.

Note: If you start another acquisition w ith the same device, the ROI that you setwillremainthedefaultthatisusedinsubsequentacquisitions.Toresetto the original image size, click the Reset Region of Interest to Maximum buttoninthePreview Window or the Reset buttonontheRegion of Interest tab.

Restoring Default Parameters

Once you have changed parameters of a device, you can restore the device’s default parameters by selecting the device format in the Hardware Browser and right-clicking Clear Selected Hardware Configuration.Thatclears any changes you have made and resets the default parameters of that device format.

3-24

If you want to save a configuration before clearing it, first select Export Selected Hardware Configuration from the right-click menu.

Previewing and Acquiring Data

In this section...

“The Preview Windo w” on page 3-25

“Previewing Data” on page 3-27

“Acquiring Data” on page 3-28

The Preview Window

The Preview window displays the image data when you preview or acqu ire data.

Previewing and Acquiring Data

3-25

3 Using the Image Acquisition Tool GUI

3-26

Use the buttons in the Preview window to:

• Preview your image. See “Previewing Data” on page 3-27 for more

information.

Previewing and Acquiring Data

• Acquire data. See “Acquiring Dat a” on p ag e 3-28 for more information.

• Export data. See “Exporting Data” on page 3-32 for more information.

• Set Region of Interest. See “Setting a Region of Interest” on page 3-18

for more information.

Below the area that displays the fram es you will see tex t messages with information relative to the current state of the window. For example in the figure above, that text indicates that all the frames that were acquired are being displayed. After you start and stop a preview, the text will indicate that the tool is ready to acquire data.

During an acquisition, a running timer appears under the display area that indicates the actual time of the frame acquisition.

Note The Image Acquisition Toolbox Preview window and the Preview window that is built into the Image Acquisition Tool now support the display of up to 16-bit image data. The Preview window was designed to only show 8-bit data, but many cameras return 10-, 12-, 14-, or 16-bit data. The Preview window display now supports these higher bit-depth cameras.

Previewing Data

To preview data:

1 SelectthedeviceandformatintheHardware Browser.

2 Click the Start Preview button to test your device.

3 If necessary, adjust the device to achieve the desired image.

4 Set the Frames Per Trigger on the General tab and the Number of

Triggers on the Triggering tab, to set the total number of frames for the acquisition.

5 Set any other acquisition parameters to adjust the quality of the image

or other acquisition factors.

You are now ready to start the acquisition.

3-27

3 Using the Image Acquisition Tool GUI

Acquiring Data

To acquire data:

1 Select the device and format in the Hardware Browser.TheHardware

Browser shows the image acquisition devices currently connected to your

system. If the device you want to use is not connected to your system, plug it in and then select Tools > Refresh Image Acquisition Hardware to display the new device in the Hardware Browser.

The nodes listed under the d ev ice name are the formats the device supports. They may correspond to the different resolutions and color spaces that your device s upports, or to different video standards or camera configurations. This information comes from your device adaptor. Select the format you want to use.

See “Selec and format

2 Use the Preview feature to test and set up your device by clicking the Start

Preview button. If necessary, physically adjust the device to achieve the desired image area, or use the Region of Interest tab of the Acquisition Parameters pane to constrain the image.

See “Previewing Data” on page 3-27 for more information on previewing.

3 Set the

Trigge

acquis

For example, if you set Frames Per Trigger to Triggers to

If you just want a snapshot of one frame, leave the default settings of both fields. If you want a specific number o f frames, use the fields to set it.

Alte the b

uisition.

acq

ting Your Device” on page 3-5 for more information about devices

Frames Per Trigger on the General tab and the Number of

rs on the Triggering tab, to set the total number of frames for the

ition, if you did not do so while previewing.

4 and Number of

2, the total number of frames acquired will be 8.

1 in

rnatively, you can set the tool to acquire continuously and use

uttons in the Preview window to manually start and stop the

3-28

Previewing and Acquiring Data

4 Set any necessary acquisition parameters if you did not do so while

previewing. See “Setting Acquisition Parameters ” on page 3-8 for more information.

5 Choose your log mode, which determines where the acquisition data is

stored.

On the Logging tab, use the Log To field to choose to log to memory, disk, or both. Disk logging results in a saved AVI file. If you choose memory logging, you can export your data after the acquisition using the Export Data button on the Preview window.

For more information about logging, see “Logging Your Data” on page 3-13.

6 Start the acquisition by clicking the Start Acquisition button.

• If you set Trigger Type (on the Triggering tab) to

Immediate, the tool

will immediately start logging data.

• If you set Trigger Type to

Manual,clicktheTrigger button when

you want to start logging data. For more information about manual triggering, see “Setting Up Triggering” on page 3-15.

7 Stop the acquisition:

• If you set Frames Per Trigger (on the General tab) to

1 or any

other number, your acquisition will stop when that number of frames is reached.

• If you set Frames Per T rigger to

infinite,clicktheStop Acquisition

button to stop the acquisition.

Note that you can also click Stop Acquisition to abort an acquisition if the number of frames was specified.

When the acquisition stops, if you logged to memory or disk and memory, the Preview window will display all or some of the frames of the acquisition. The window can show up to nine frames. If you acquire more than nine frames, it will display frames at an even interval based on the total number of frames. The montage of nine frames are indexed linearly from the acquired images. The text under the images will list which frames are shown. You can also hover your cursor over each frame to see which frame number it is, as shown in the following figure.

3-29

3 Using the Image Acquisition Tool GUI

3-30

Previewing and Acquiring Data

If Images Are Blurry or Dark

If the first one or more frames of your acquisition are blurry, black, or of low quality, your camera may need to warm up before you capture frames.

You can allow for device warm-up by using manual triggering. This allows you to start the acquisition after the device has warmed up and is acquiring image data that meets your needs.

To use manual triggering, go to the Triggering tab of the Acquisition Parameters pane and select

For more detailed instructions about manual triggering, see “Selecting the Trigger Type” on page 3-16.

For more information about troubleshooting specific devices, see “Overview” on page 10-2 in the Troubleshooting chapter.

Manual in the Trigger Type field.

3-31

3 Using the Image Acquisition Tool GUI

Exporting Data

You can export the data that has been acquired in memory to a MAT-file, the MATLAB Workspace, or other options.

To export the acquisition data:

1 Click the Export Data button in the Preview window to export the last

acquisition that was lo gg ed to memory.

2 In the Data Exporter dialog box, select MAT-File, MATLAB Workspace,or

AVI-File in the Data Destination field. In addition, you can choose Image Tool or Image File for single-frame acquisitions o r Movie Player

for multiple-frame acquisitions. These three options are provided by the Image Processing T oolbox software.

If you sele box appear enabled. logged to informat Logging

AVI-File and then click OK, the AVI File Parameters dialog

s. Once you select a Filename, the other AVI options are

ThesearethesameasyoucansetontheLogging tab if you

an .

avi file instead of exporting to it after the acquisition. For

ionontheCompression and Frame rate options, see “Disk

” on page 3-14.

3-32

3 If you selected MAT-File or MATLAB Workspace as the Data Destination,

in the Variable Name field, enter a name for the new variable, and click OK.

Exporting Data

3-33

3 Using the Image Acquisition Tool GUI

4 If you exported to the MATLAB Workspace, the dialog box closes and the

data will be saved to the MATLAB Workspace.

If you are exporting to a MAT-file, the Export to MAT-File dialog box opens. Selectthesavelocationandtypeafilename,andthenclickSave.

IfyouexportedtoanAVI-File,thefileiscreatedandputinthelocation you selected in the AVI File Parameters dialog box.

If you exported to acquired immediately open in that tool.

Image Tool, Image File,orMovi e Player,theframe(s)

3-34

Saving Image Acquisition Tool Configurations

You can save the configuration information about any of your device formats. This includes any parameters you set on any of the tabs in the Acquisition Parameters pane. Then when you return to the tool, you can load the configuration so that you do not have to reset those parameters.

To save a configuration:

1 Select File > Save Configuration.

The Save Configuration dialog box opens.

2 Decide what configuration(s) to save.

The Save Configuration dialog box lists the currently selected device format, as well as any others you selected in the Hardware Browser during the tool session. All formats are selected by default, meaning their configurations will be saved. If you do not want to save a configuration, clear it from the list.

3 Click Save.

eSaveFiledialogboxopens.

4 Enter a file name and click Save.

3-35

3 Using the Image Acquisition Tool GUI

The configuration is saved to an Image Acquisition Tool (IAT) file in the location you specified.

You can then open the saved configuration file in a future tool session by selecting File > Open Configuration. In the Open Configuration dialog box, browse to an IAT file and click Open.

Note You can also export hardware configuration information to other formats such as an M-file or a MAT-file that can be accessed from MATLAB. See“ExportingHardwareConfigurationstoMATLAB”onpage3-37.

3-36

Exporting Hardware Configurations to MATLAB

You can export the video input objects and their configured parameters from the tool to a choice of multiple formats. You can then access the video object in MATLAB.

To export a hardware configuration:

1 Select File > Export Hardware Configuration.

The Object Exporter dialog box opens.

2 Selec

•

MATLA

Work it be

•

M-Fi

gen par cod

•

t the file format from the Object destination list.

B Workspace

saves the video input object to the MATLAB

space for the duration of the MATLAB session. (You can then save

fore exiting MATLAB if you want to retain it.)

isthesameastheFile > Generate M-File command. It

erates an M-file containing the video input o bj ect and its configured

ameters. You could then incorporate the M-file into other MATLAB

e or projects.

T-File

saves the video input object and its parameters to a MAT-file.

3-37

3 Using the Image Acquisition Tool GUI

3 Decide what object configuration(s) to export.

The Object Exporter dialog box lists the currently selected device format, as well as any others you selected in the Hardware Browser during the tool session. All formats are selected by default, meaning their configurations will be saved. If you do not want to save a configuration, clear it from the list.

4 Click Save.

If you exported to the MATLAB Workspace, the dialog box closes and the data is saved to the MATLAB Workspace.

5 If you export to a MAT-file or M-file, an Export dialog box opens. Select the

save location and type a file name, and then click Save.

Note You can also save configuration information to an Image Acquisition Tool (IAT) file that can then be loaded in the tool in a future session. See “Saving Image Acquisition Tool Configurations” on page 3-35.

3-38

Saving and Copying the Session Log

In this section...

“About the Session Log” on page 3-39

“Saving the S ession Log” on page 3-39

“Copying the Session Log” on page 3-40

About the Session Log

The session log dynamically records every action you perform in the Image Acquisition Tool. The corresponding command-line functionality for actions on a videoinput object or videosource object is reflected in the log. The title displaysthenameofthedevice,asshownintheHardware Browser.

YoucannotdirectlyeditintheSession Log pane. You can save the contents to a MATLAB code file or copy it to another destination, and then edit the contents.

Saving and Copying the Session Log

Each device format has its own session log, independent of any other formats. If you switch to a different device or format, the contents of the session log will reflect the currently selected device. If you switch back to a previous node in the Hardware Browser, the session log for that device will remain in the same state it was in before you switched nodes.

Saving the Session Log

To save the contents to a MATLAB code file:

1 Click the Save the current session log to a file buttonintheSession

Log toolbar. You can also right-click in the log pane and select Save.

3-39

3 Using the Image Acquisition Tool GUI

3-40

2 In the Sa

to save

3 Use the default name, imaqtoolSessionLog.m,orrenameit.

4 When you click the Save button, the file will open in the MATLAB Editor.

You can then either edit it or close it.

Note that the entire contents of the session log is saved. If you just want to save a portion of the log, use the Copy command instead.

ve Session Log dialog box, browse to the location where you want

the file.

Copying the Session Log

To copy all or part of the contents to the clipboard:

1 Select the portion of the log that you want to copy.

Saving and Copying the Session Log

The Copy command is then enabled.

2 Click the Copy button in the Session Log toolbar. You can also right-click

in the log pane and select Copy.

This copies the selected contents to the system clipboard.

3 Go to the application or file that you wish to copy it into, and right-click

Paste.

You can then edit or save it as your application allows.

3-41

3 Using the Image Acquisition Tool GUI

Registering a Third-Party Adaptor

If you are using a third-party adaptor that requires the use of the

imaqregister function, you can use this menu as an easier way to add the

adaptor. Note that this function is not documented in the Image Acquisition Toolbox User’s Guide, but is documented in the Image Acquisition Toolbox Adaptor Kit User’s Guide.

To register an adaptor:

1 Click Tools > Register a Third-Party Adaptor on the Image Acquisitio n

Tool menu.

2 In the Register a 3rd Party Adaptor dialog box, browse to the .dll file

that represents your adaptor.

3 Select the

file and click OK to regist er the adaptor.

3-42

Connecting to Hardware

To connect to an image acquisition device from within MATLAB, you must create a video input object. This object represents the connection between MATLAB and the device. Yo u can use object properties to control various aspects of the acquisition. Before you can create the object, you need several pieces of information about the device that you want to connect to.

This chapter describes tasks related to establishing a connection between MATLAB and an image acquisition device. For information about connecting to an image acquisition device from a Simulink model, see Chapter 8, “Using the From Video Device Block in Simulink”.

• “Getting Hardware Information” on page 4-2

• “Creating Image Acquisition Objects” on page 4-8

• “Configuring Image Acquisition Object Properties” on page 4-16

• “Starting and Stopping a Video Input Object” on page 4-23

• “Deleting Image Acquisition Objects” on page 4-27

• “Saving Image Acquisition Objects” on page 4-29

4 Connecting to Hardware

Getting Hardware Information

In this section...

“Getting Hardware Information” on page 4-2

“DeterminingtheDeviceAdaptorName”onpage4-2

“Determining the Device ID” on page 4-3

“Determining Supported Video Formats” on page 4-5

Getting Hardware Information

To access an image acquisition device, the toolbox needs several pieces of information:

• The name of the adaptor the toolbox uses to connect to the image

acquisition device

• ThedeviceIDofthedeviceyouwanttoaccess

4-2

• The video format of the video stream or, optionally, a device configuration

file (camera file)

You use the in the following subsections.

Note When using imaqhwinfo to get information about a device, especially devices that use a Video for Windows (VFW) driver, you might encounter dialog boxes reporting an assertion error. Make sure that the software drivers are installed correctly and that the acquisition device is connected to the computer.

imaqhwinfo function to retrieve this information, as described

Determining the Device Adaptor Name

An adaptor is the software the toolbox uses to communicate with an image acquisition device via its device driver. T he toolbox includes adaptors for some vendors of image acquisition equipment and for particular classes of image acquisition devices. For the latest information about supported hardware,

Mathworks IMAGE ACQUISITION TOOLBOX 3 user guide

Specifications and Main Features

Frequently Asked Questions

User Manual

Getting Started

Product Overview

Introduction

Installation and Configuration Notes

and click the Supported Hardware

Image Acquisition Tool (GUI)

Basic Image Acquisition Procedure

Overview

Step 1: Install Your Image Acquisition Device

Step 2: Retrieve Hardware Information

Determining the Adaptor Name

Determining the Device ID

Determining the Suppor ted Video F ormats

Step 3: Create a Video Input Object

Viewing the Video Input Object Summary

Step 4: Preview the Video Stream (Optional)

Step 5: Configure Object Properties ( Optional)

Types of Image Acquisition Objects

Viewing Object Properties

Setting Object Properties

Step 6: Acquire Image Data

Running the Example

Image Data in the MATLAB Workspace

Step 7: Clean Up

Introduction

Overview

Introduction

Toolbox Components

The Image Acquisition Tool (GUI)

Supported Devices

Setting Up Image Acquisition Hardware

Introduction

Setting Up Frame Grabbers

Previewing Data

Introduction

Opening a Video Preview Window

Closing a Video Preview Window

Previewing Data in Custom GUIs

Creating the Update Preview Window Function

Specifying the Update Preview Function

Using the Image Acquisition Tool GUI

The Image Acquisition Tool Desktop

Opening the Tool

Parts of the Desktop

Selecting Your Device

Selecting a Device and Format

Adding New Hardware

Using a Camera File

Setting Acquisition Parameters

Using the Acquisition Parameters Pane

Setting Frames Per Trigger

Setting the Color Space

Setting Device-Specific Parameters

Logging Your Data

Memory Logging

Disk Logging

Setting Up Triggering

Selecting the Number of Triggers

Selecting the Trigger Type

Setting a Region of Interest

Setting Region of Interest Manually

Setting Region of Interest Interactively

Restoring Default Parameters

Previewing and Acquiring Data

The Preview Window

Previewing Data

Acquiring Data

If Images Are Blurry or Dark

Exporting Data

Saving Image Acquisition Tool Configurations

Exporting Hardware Configurations to MATLAB

Saving and Copying the Session Log

About the Session Log

Saving the Session Log

Copying the Session Log

Registering a Third-Party Adaptor