Sign in today to find solutions:

Don't have an account? Sign up

 
Image Acquisition Toolbox™ 3
User's Guide

Summary of Contents

  • Page 1

    Image Acquisition Toolbox™ 3 User’s Guide...

  • Page 2

    Program and Documentation, unused, to The MathWorks, Inc. Trademarks MATLAB and Simulink are registered trademarks of The MathWorks, Inc. See for a list of additional trademarks. Other product or brand www.mathworks.com/trademarks names may be trademarks or registered trademarks of their respective holders.

  • Page 3

    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)

  • Page 5: Table Of Contents

    Contents Getting Started ....... . . Product Overview ........Introduction .

  • Page 6: Table Of Contents

    ... . . Setting Up Image Acquisition Hardware ........Introduction .

  • Page 7: Table Of Contents

    ..Saving Image Acquisition Tool Configurations 3-35 ..Exporting Hardware Configurations to MATLAB 3-37 ....Saving and Copying the Session Log 3-39 .

  • Page 8: Table Of Contents

    ....Viewing the Values of Object Properties 4-17 ... . Viewing the Value of a Particular Property 4-19 .

  • Page 9: Table Of Contents

    . . . Bringing Image Data into the MATLAB Workspace ........

  • Page 10: Table Of Contents

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

  • Page 11: Table Of Contents

    ........Introduction ..Step 1: Open the Image Acquisition Toolbox Library .

  • Page 12: Table Of Contents

    Troubleshooting DCAM IEEE 1394 (FireWire) ........Hardware 10-8 .

  • Page 13: Table Of Contents

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

  • Page 14: Table Of Contents

    Properties — Alphabetical List Block Reference Examples ........Fundamentals .

  • Page 15: Overview

    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.

  • Page 16: Product Overview, Introduction

    • 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...

  • Page 17: Installation And Configuration Notes

    MATLAB prompt: 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.

  • Page 18: Related Products, Supported Hardware

    Related Products The MathWorks™ provides several products that are relevant to the kinds of tasks you can perform with the Image Acquisition Toolbox software and that extend the capabilities of MATLAB. For information about these related products, see www.mathworks.com/products/imaq/related.html Supported Hardware The list of hardware that the Image Acquisition Toolbox software supports can change in each release, since hardware support is frequently added.

  • Page 19: Image Acquisition Tool (gui)

    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.

  • Page 20: Basic Image Acquisition Procedure, Overview

    Getting Started Basic Image Acquisition Procedure In this section... “Overview” on page 1-6 “Step 1: Install Your Image Acquisition Device” on page 1-7 “Step 2: Retrieve Hardware Information” on page 1-8 “Step 3: Create a Video Input Object” on page 1-10 “Step 4: Preview the Video Stream (Optional)”...

  • Page 21: Step 1: Install Your Image Acquisition Device

    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.

  • Page 22: Step 2: Retrieve Hardware Information, For More Information

    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”...

  • Page 23

    Determining the Device ID To find the device ID of a particular image acquisition device, enter the function at the MATLAB prompt, specifying the name of the imaqhwinfo adaptor as the only argument. (You found the adaptor name in the first call to , described in “Determining the Adaptor Name”...

  • Page 24: Step 3: Create A Video Input Object

    In this step you create the video input object that the toolbox uses to represent the connection between MATLAB and an image acquisition device. Using the properties of a video input object, you can control many aspects of the image acquisition process.

  • Page 25

    Viewing the Video Input Object Summary To view a summary of the video input object you just created, enter the variable name ( at the MATLAB command prompt. The summary vid) information displayed shows many of the characteristics of the object, such as the number of frames that will be captured with each trigger, the trigger type, and the current state of the object.

  • Page 26: Step 4: Preview The Video Stream (optional)

    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.

  • Page 27

    Basic Image Acquisition Procedure The following figure shows the Video Preview window for the example. Video Preview Window To close the Video Preview window, click the Close button in the title bar or use the function, specifying the video input object as an closepreview argument.

  • Page 28: Step 5: Configure Object Properties (optional)

    To view a complete list of all the properties supported by a video input object or a video source object, use the function. To list the properties of the video input object created in step 3, enter this code at the MATLAB prompt. 1-14...

  • Page 29

    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)) function lists all the properties of the object with their current values.

  • Page 30

    To implement continuous image acquisition, the example sets the property to . To set this property using the function, TriggerRepeat 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 property to .

  • Page 31: Step 6: Acquire Image Data

    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 function to retrieve the object.

  • Page 32

    Single Frame into the Workspace” on page 6-10 for more information. 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...

  • Page 33

    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);...

  • Page 34

    The height and width of the array are primarily determined by the video resolution of the video format. However, you can use the ROIPosition 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. 1-20...

  • Page 35: Step 7: Clean Up

    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)

  • Page 36

    Getting Started 1-22...

  • Page 37

    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...

  • Page 38: Introduction, Overview

    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.

  • Page 39: Toolbox Components

    Overview 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 video acquisition devices.

  • Page 40: The Image Processing Toolbox Software Required To Use The Image Acquisition Toolbox Software

    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 image data. You can log the data to MATLAB in several formats, and also generate an AVI file, right from the tool.

  • Page 41

    Overview equipment, devices that support the IIDC 1394-based Digital Camera Specification (DCAM), and devices that provide Windows Driver Model (WDM) or Video for Windows (VFW) drivers, such as USB and IEEE ® 1394 (FireWire, i.LINK ® ) Web cameras, Digital video (DV) camcorders, and TV tuner cards.

  • Page 42: Setting Up Image Acquisition Hardware, Introduction, Setting Up Frame Grabbers

    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 acquire data. Setting Up Frame Grabbers For frame grabbers, also known as imaging boards, setup typically involves the following tasks: •...

  • Page 43: Setting Up Generic Windows Video Acquisition Devices, Setting Up Dcam Devices

    DCAM compliant. See “Installing the CMU DCAM Driver” on page 10-9 for more information. Resetting Your Image Acquisition Hardware To return MATLAB and your image acquisition hardware to a known state, where no image acquisition objects exist and the hardware is not configured, function.

  • Page 44

    Introduction The rate at which the Image Acquisition Toolbox software can process images 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.

  • Page 45: Previewing Data, Introduction

    “Performing Custom Processing of Previewed Data” on page 2-14 Introduction After you connect MATLAB to the image acquisition device (see Chapter 4, “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.

  • Page 46: Opening A Video Preview Window

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

  • Page 47: Stopping The Preview Video Stream

    Previewing Data 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.

  • Page 48: Closing A Video Preview Window, Previewing Data In Custom Guis

    Introduction This example creates a video input object and opens a Video Preview window. The example then calls the function on this video input object. stoppreview 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.

  • Page 49

    Previewing Data To use this capability, create an 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 object in the figure, the same size as the video frames.

  • Page 50: Performing Custom Processing Of Previewed Data

    Introduction When you run this example, it creates the GUI shown in the following figure. Custom Preview Performing Custom Processing of Previewed Data When you specify an image object to the function (see “Previewing preview Data in Custom GUIs” on page 2-12), you can optionally also specify a function that executes every time it receives an image frame.

  • Page 51

    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 of the image CData object with the incoming video frames.

  • Page 52

    Introduction custom GUI. The update preview window function uses getappdata retrieve a handle to the text label object from application-defined uicontrol data in the image object. The custom GUI stores this handle to the text label object — see “Specifying the Update Preview Function” on page uicontrol 2-16.

  • Page 53

    Previewing Data value. The update preview window function updates this text label each time a framed is received. The example uses to store a handle setappdata to the text label object in application-defined data in the image uicontrol object. The update preview window function retrieves this handle to update the timestamp display.

  • Page 54

    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');...

  • Page 55

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

  • Page 56

    Introduction 2-20...

  • Page 57

    • “Exporting Data” on page 3-32 • “Saving Image Acquisition Tool Configurations” on page 3-35 • “Exporting Hardware Configurations to MATLAB” on page 3-37 • “Saving and Copying the Session Log” on page 3-39 • “Registering a Third-Party Adaptor” on page 3-42...

  • Page 58: The Image Acquisition Tool Desktop, Opening The Tool, Parts Of The Desktop

    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.

  • Page 59

    The Image Acquisition Tool Desktop • 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.

  • Page 60

    Hardware Browser. • 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.

  • Page 61: Selecting Your Device, Selecting A Device And Format

    Selecting Your Device Selecting Your Device In this section... “Selecting a Device and Format” on page 3-5 “Adding New Hardware” on page 3-6 “Using a Camera File” on page 3-7 Selecting a Device and Format The Hardware Browser pane shows the image acquisition devices currently connected to your system.

  • Page 62: Adding New Hardware

    Using the Image Acquisition Tool GUI 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...

  • Page 63: Using A Camera File

    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.

  • Page 64: Setting Acquisition Parameters, Using The Acquisition Parameters Pane

    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”...

  • Page 65: Setting Frames Per Trigger

    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.

  • Page 66: Setting The Color Space, Setting Device-specific Parameters

    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 and Number of Triggers to , the total...

  • Page 67

    Setting Acquisition Parameters The Selected source field specifies the name of the selected source for the current device. Many device adaptors only have one input source, so for example, this might show something like , or input1 port1 input0 default. If your device supports multiple source names, they will appear in the drop-down list.

  • Page 68

    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 Device Properties tab, right-click a property and select What’s This?.

  • Page 69: Logging Your Data

    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: •...

  • Page 70

    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.

  • Page 71: Setting Up Triggering

    %. The Key frames per second field determines the ratio of frames that get compressed versus frames that just calculate the delta from the last frame. The value of is the MATLAB default. 2.14 Larger numbers would result in a higher image quality, but a larger log file.

  • Page 72

    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 and Number of Triggers to , the total...

  • Page 73

    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 , use the Stop Acquisition infinite button to stop the acquisition.

  • Page 74: Setting A Region Of Interest

    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. For example, it might be something like , or Port0 Port1 OptoTrig Select your Trigger Condition. This specifies the condition that must be met, via the Trigger Source, before a trigger event occurs.

  • Page 75

    Setting Acquisition Parameters Adjust one or more of the X-Offset, Y-Offset, Width, or Height settings until you reach the desired region. Use the arrows in each field to adjust the numbers. The preview resizes as you make changes. When the region is the desired size, start your acquisition by clicking the Start Acquisition button.

  • Page 76

    Using the Image Acquisition Tool GUI Your cursor becomes a selection tool. Note that the Select Region of Interest button is enabled only during preview mode. 3-20...

  • Page 77

    Setting Acquisition Parameters 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. Release the mouse button to freeze the region.

  • Page 78

    Using the Image Acquisition Tool GUI If the selected area is the region you want to use, start your acquisition by clicking the Start Acquisition button. In this case, the region appears as follows. 3-22...

  • Page 79

    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.

  • Page 80: Restoring Default Parameters

    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.

  • Page 81: Previewing And Acquiring Data, The Preview Window

    Previewing and Acquiring Data Previewing and Acquiring Data In this section... “The Preview Window” 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 acquire data.

  • Page 82

    Using the Image Acquisition Tool GUI Use the buttons in the Preview window to: • Preview your image. See “Previewing Data” on page 3-27 for more information. 3-26...

  • Page 83

    Previewing and Acquiring Data • Acquire data. See “Acquiring Data” on page 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.

  • Page 84: Acquiring Data

    Using the Image Acquisition Tool GUI Acquiring Data To acquire data: Select the device and format in the Hardware Browser. The Hardware 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 >...

  • Page 85

    Previewing and Acquiring Data Set any necessary acquisition parameters if you did not do so while previewing. See “Setting Acquisition Parameters” on page 3-8 for more information. 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.

  • Page 86

    Using the Image Acquisition Tool GUI 3-30...

  • Page 87

    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.

  • Page 88: Exporting Data

    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: Click the Export Data button in the Preview window to export the last acquisition that was logged to memory.

  • Page 89

    Exporting Data 3-33...

  • Page 90

    Using the Image Acquisition Tool GUI 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.

  • Page 91: Saving Image Acquisition Tool Configurations

    Saving Image Acquisition Tool Configurations 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.

  • Page 92

    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 “Exporting Hardware Configurations to MATLAB” on page 3-37.

  • Page 93: Exporting Hardware Configurations To Matlab

    MATLAB • MATLAB Workspace Workspace for the duration of the MATLAB session. (You can then save it before exiting MATLAB if you want to retain it.) is the same as the File > Generate M-File command. It •...

  • Page 94

    If you do not want to save a configuration, clear it from the list. Click Save. If you exported to the MATLAB Workspace, the dialog box closes and the data is saved to the MATLAB Workspace. 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.

  • Page 95: Saving And Copying The Session Log, About The Session Log, Saving The Session Log

    Hardware Browser. You cannot directly edit in the Session Log pane. You can save the contents to a MATLAB code file or copy it to another destination, and then edit the contents.

  • Page 96: Copying The Session Log

    , or rename it. imaqtoolSessionLog.m 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.

  • Page 97

    Saving and Copying the Session Log The Copy command is then enabled. 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. Go to the application or file that you wish to copy it into, and right-click Paste.

  • Page 98: Registering A Third-party Adaptor

    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 function, you can use this menu as an easier way to add the imaqregister 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.

  • Page 99

    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. You 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.

  • Page 100: Getting Hardware Information, Getting Hardware Information, Determining The Device Adaptor Name

    Connecting to Hardware Getting Hardware Information In this section... “Getting Hardware Information” on page 4-2 “Determining the Device Adaptor Name” on page 4-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: •...

  • Page 101: Determining The Device Id

    Getting Hardware Information visit the Image Acquisition Toolbox product page at the MathWorks Web site www.mathworks.com/products/imaq To determine which adaptors are available on your system, call the function. The function returns information about imaqhwinfo imaqhwinfo the toolbox software and lists the adaptors available on the system in the field.

  • Page 102

    Connecting to Hardware info = imaqhwinfo('matrox'); info = AdaptorDllName: [1x73 char] AdaptorDllVersion: '2.1 (R2007a)' AdaptorName: 'matrox' DeviceIDs: {[1]} DeviceInfo: [1x1 struct] The fields in the structure returned by provide the following imaqhwinfo information. Field Description Text string that identifies the name of the adaptor AdaptorDllName dynamic link library (DLL) Information about the version of the adaptor DLL...

  • Page 103: Determining Supported Video Formats

    Getting Hardware Information DefaultFormat: 'M_RS170' DeviceFileSupported: 1 DeviceName: 'Orion' DeviceID: 1 ObjectConstructor: 'videoinput('matrox', 1)' SupportedFormats: {1x10 cell} The fields in the device information structure provide the following information about a device. Field Description Text string that identifies the video format used by DefaultFormat the device if none is specified at object creation time If set to 1, the device supports device configuration...

  • Page 104

    Connecting to Hardware Image acquisition devices typically support multiple video formats. You can specify the video format when you create the video input object to represent the connection to the device. See “Creating Image Acquisition Objects” on page 4-8 for more information. Note Specifying the video format is optional;...

  • Page 105

    Getting Hardware Information M_RS170_VIA_RGB ans{3} = M_CCIR ans{4} = M_CCIR_VIA_RGB ans{5} = M_NTSC ans{6} = M_NTSC_RGB ans{7} = M_NTSC_YC ans{8} = M_PAL ans{9} = M_PAL_RGB ans{10} = M_PAL_YC...

  • Page 106: Creating Image Acquisition Objects, Types Of Objects, Video Input Objects, Video Source Objects

    • Video input object • Video source object Video Input Objects A video input object represents the connection between MATLAB and a video acquisition device at a high level. You must create the video input object using the function. See “Creating a Video Input Object” on page videoinput 4-9 for more information.

  • Page 107: Creating A Video Input Object

    Creating Image Acquisition Objects 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. The toolbox selects one of the video source objects by default, but you can change this selection.

  • Page 108

    Connecting to Hardware default syntax in the field of the device videoinput ObjectConstructor information structure. vid = videoinput('matrox'); This syntax uses the default video format listed in the field of DefaultFormat the data returned by . You can optionally specify the video format. imaqhwinfo See “Specifying the Video Format”...

  • Page 109: Specifying The Video Format

    Creating Image Acquisition Objects device supports eight physical input channels and, with the default video format, the toolbox creates a video source object for each connection. For an example showing the video source objects created with another video format, see “Specifying the Video Format” on page 4-11. The Acquisition Parameters section lists the values of key video input object properties.

  • Page 110

    Connecting to Hardware • A name of a device configuration file, also known as a camera file The following sections describe these options. If you do not specify a video format, the function uses one of the video formats supported by videoinput the device.

  • Page 111

    Creating Image Acquisition Objects Note For Matrox devices, the format string represents a M_NTSC_RGB component video format. This example creates a video input object, specifying a color video format. vid2 = videoinput('matrox', 1,'M_NTSC_RGB'); Using Device Configuration Files (Camera Files) For some devices, you can use a device configuration file, also known as a camera file, to specify the video format as well as other configuration settings.

  • Page 112: Specifying The Selected Video Source Object

    Connecting to Hardware This example creates a video input object specifying a Matrox device configuration file as an argument. Specifying the Selected Video Source Object When you create a video input object, the toolbox creates one or more video source objects associated with the video input object. The number of video source objects created depends on the device and the video format.

  • Page 113: Getting Information About A Video Input Object

    Creating Image Acquisition Objects By default, the video input object makes the first video source object in the array the selected source. To use another video source, change the value of property. SelectedSourceName This example changes the currently selected video source object from by setting the value of the property.

  • Page 114: Configuring Image Acquisition Object Properties, About Image Acquisition Object Properties

    Connecting to Hardware Configuring Image Acquisition Object Properties In this section... “About Image Acquisition Object Properties” on page 4-16 “Viewing the Values of Object Properties” on page 4-17 “Viewing the Value of a Particular Property” on page 4-19 “Getting Information About Object Properties” on page 4-20 “Setting the Value of an Object Property”...

  • Page 115: Viewing The Values Of Object Properties

    Configuring Image Acquisition Object Properties Note Three video input object trigger properties require the use of a special configuration function. For more information, see “Setting Trigger Properties” on page 4-22. Viewing the Values of Object Properties To view all the properties of an image acquisition object, with their current values, use the function.

  • Page 116

    Connecting to Hardware Type = videoinput UserData = [] VideoFormat = M_RS170 VideoResolution = [640 480] Callback Function Settings: ErrorFcn = @imaqcallback FramesAcquiredFcn = [] FramesAcquiredFcnCount = 0 StartFcn = [] StopFcn = [] TimerFcn = [] TimerPeriod = 1 TriggerFcn = [] Trigger Settings: InitialTriggerTime = [0 0 0 0 0 0]...

  • Page 117: Viewing The Value Of A Particular Property

    To view the value of a particular property of an image acquisition object, use function, specifying the name of the property as an argument. You can also access the value of the property as you would a field in a MATLAB structure.

  • Page 118: Getting Information About Object Properties, Setting The Value Of An Object Property

    To set the value of a particular property of an image acquisition object, use function, specifying the name of the property as an argument. You can also assign the value to the property as you would a field in a MATLAB structure.

  • Page 119

    = disk&memory This example sets the value of a property by assigning the value to the object as if it were a MATLAB structure. vid.LoggingMode = 'disk'; vid.LoggingMode ans = disk Viewing a List of All Settable Object Properties...

  • Page 120

    Connecting to Hardware Setting Trigger Properties The values of certain trigger properties, TriggerType TriggerCondition , are interrelated. For example, some TriggerSource TriggerCondition values are only valid with specific values of the property. TriggerType To ensure that you specify only valid combinations for the values of these properties, you must use two functions: •...

  • Page 121: Starting And Stopping A Video Input Object

    Starting and Stopping a Video Input Object When you create a video input object, you establish a connection between MATLAB and an image acquisition device. However, before you can acquire data from the device, you must start the object, using the function.

  • Page 122

    Connecting to Hardware The following figure illustrates how an object moves from a running to a stopped state. Transitions from Running to Stopped States The following example illustrates starting and stopping an object: Create an image acquisition object — This example creates a video input object for a webcam image acquisition device.

  • Page 123

    Starting and Stopping a Video Input Object Configure an acquisition that takes several seconds so that you can see the video input in logging state. vid.FramesPerTrigger = 100; Start the image acquisition object — Call the function to start start the image acquisition object.

  • Page 124

    Connecting to Hardware After it acquires the specified number of frames, the video input object stops running. isrunning(vid) ans = Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them. delete(vid) clear vid 4-26...

  • Page 125: Deleting Image Acquisition Objects

    When you finish using your image acquisition objects, use the function delete to remove them from memory. After deleting them, clear the variables that reference the objects from the MATLAB workspace by using the clear function. Note When you delete a video input object, all the video source objects associated with the video input object are also deleted.

  • Page 126

    Connecting to Hardware You can also delete all the video input objects that currently exist in memory in one call to by using the function. The delete imaqfind function returns an array of all the video input objects in memory. imaqfind imaqfind Video Input Object Array:...

  • Page 127: Saving Image Acquisition Objects, Using The Save Command, Using The Obj2mfile Command

    Note The values of read-only properties are not saved. When you load an image acquisition object into the MATLAB workspace, read-only properties revert to their default values. To determine if a property is read only, use the function or read the property reference page.

  • Page 128

    Connecting to Hardware 4-30...

  • Page 129

    Acquiring Image Data The core of any image acquisition application is the data acquired from the input device. A trigger is the event that initiates the acquisition of image frames, a process called logging. A trigger event occurs when a certain condition is met.

  • Page 130: Data Logging, Overview

    Acquiring Image Data Data Logging In this section... “Overview” on page 5-2 “Trigger Properties” on page 5-3 Overview When a trigger occurs, the toolbox sets the object’s property to Logging 'on' and starts storing the acquired frames in a buffer in memory, a disk file, or both.

  • Page 131: Trigger Properties

    Data Logging The following figure illustrates a group of frames being acquired from the video stream and being logged to memory and disk. Overview of Data Logging Trigger Properties The video input object supports several properties that you can use to configure aspects of trigger execution.

  • Page 132

    Acquiring Image Data Property Description Reports the absolute time when the first trigger InitialTriggerTime executed. Specifies the condition that must be met for TriggerCondition a trigger to be executed. This property is always set to for immediate and manual 'none' triggers.

  • Page 133: Setting The Values Of Trigger Properties, About Trigger Properties, Specifying Trigger Type, Source, And Condition

    Setting the Values of Trigger Properties Setting the Values of Trigger Properties In this section... “About Trigger Properties” on page 5-5 “Specifying Trigger Type, Source, and Condition” on page 5-5 About Trigger Properties Most trigger properties can be set using the same methods you use to set any other image acquisition object property: using the function or referencing the property as you would a field in a structure.

  • Page 134

    Acquiring Image Data Determining Valid Configurations To find all the valid configurations of the , and TriggerType TriggerSource properties, use the function, specifying a TriggerCondition triggerinfo video input object as an argument. config = triggerinfo(vid); This function returns an array of structures, one structure for each valid combination of property values.

  • Page 135

    Setting the Values of Trigger Properties If you are specifying a manual trigger, you only need to specify the trigger type value as an argument. triggerconfig(vid,'manual') You can also pass one of the structures returned by the function triggerinfo to the function and set all three properties at once.

  • Page 136: Specifying The Trigger Type, Comparison Of Trigger Types

    Acquiring Image Data Specifying the Trigger Type In this section... “Comparison of Trigger Types” on page 5-8 “Example: Using an Immediate Trigger” on page 5-9 “Example: Using a Manual Trigger” on page 5-12 “Example: Using a Hardware Trigger” on page 5-14 “Setting DCAM-Specific Trigger Modes”...

  • Page 137: Example: Using An Immediate Trigger

    Specifying the Trigger Type Comparison of Trigger Types (Continued) TriggerSource TriggerType TriggerCondition Value Values Description trigger when you observe a particular condition in the scene. For more information, see “Example: Using a Manual Trigger” on page 5-12. Hardware triggers are external Device-specific 'hardware' signals that are processed directly by...

  • Page 138

    Acquiring Image Data Immediate Trigger The following example illustrates how to use an immediate trigger: Create an image acquisition object — This example creates a video input object for a Matrox image acquisition device. To run this example on your system, use the function to get the object constructor for imaqhwinfo your image acquisition device and substitute that syntax for the following...

  • Page 139

    Specifying the Trigger Type triggerconfig(vid) ans = TriggerType: 'immediate' TriggerCondition: 'none' TriggerSource: 'none' This example sets the value of the property to . (The FramesPerTrigger default is 10 frames per trigger.) set(vid,'FramesPerTrigger',5) Start the image acquisition object — Call the function to start start the image acquisition object.

  • Page 140: Example: Using A Manual Trigger

    Acquiring Image Data Example: Using a Manual Trigger To use a manual trigger, create a video input object and set the value of the property to . A video input object executes a manual TriggerType 'manual' trigger after you issue the function.

  • Page 141

    Specifying the Trigger Type including the property, you must use the TriggerType triggerconfig function. See “Setting the Values of Trigger Properties” on page 5-5 for more information. triggerconfig(vid, 'Manual') This example also sets the value of the property to FramesPerTrigger (The default is 10 frames per trigger.) set(vid,'FramesPerTrigger',5) Start the image acquisition object —...

  • Page 142: Example: Using A Hardware Trigger

    Acquiring Image Data The object initiates the acquisition of five frames. Check the property again to verify that five frames have been FramesAcquired acquired. get(vid,'FramesAcquired') ans = After it acquires the specified number of frames, the video input object stops running. isrunning(vid) ans = To execute another manual trigger, you must first restart the video input...

  • Page 143

    Specifying the Trigger Type Note Trigger sources and the conditions that control hardware triggers are device specific. Use the function to determine whether your triggerinfo image acquisition device supports hardware triggers and, if it does, which conditions you can configure. Refer to the documentation that came with your device for more detailed information about its hardware triggering capabilities.

  • Page 144

    Acquiring Image Data properties. See “Determining TriggerSource TriggerCondition Valid Configurations” on page 5-6 for more information. In this example, returns the following valid trigger triggerinfo configurations. triggerinfo(vid) Valid Trigger Configurations: TriggerType: TriggerCondition: TriggerSource: 'immediate' 'none' 'none' 'manual' 'none' 'none' 'hardware' 'risingEdge' 'TTL' 'hardware'...

  • Page 145

    Specifying the Trigger Type ans = islogging(vid) ans = The hardware begins monitoring the trigger source for the specified condition. When the condition is met, the hardware executes a trigger and begins providing image frames to the object. The object acquires the number of frames specified by the property.

  • Page 146: Setting Dcam-specific Trigger Modes

    Acquiring Image Data Setting DCAM-Specific Trigger Modes You can now use all trigger modes and all trigger inputs that DCAM cameras support. Previous toolbox releases supported only trigger mode . Support for additional trigger modes and inputs do not affect any existing code you use. Control trigger functionality using the triggerinfo triggerconfig...

  • Page 147

    Specifying the Trigger Type Note Toolbox versions before R2010a supported DCAM trigger mode 0 with the first available . The existing triggersource externalTrigger property will be maintained so to prevent backward externalTrigger compatibility issues. In addition, in order to preserve symmetry with the new functionality, , which is triggersource externalTrigger0-mode0...

  • Page 148

    Acquiring Image Data Trigger Mode 0 This is the only trigger mode supported before R2010a. When a trigger is received, a frame is acquired. You can acquire multiple frames per trigger by switching the camera for hardware triggered mode to free running mode when a triggered frame is acquired.

  • Page 149

    Specifying the Trigger Type Trigger Mode 1 In this mode, the duration of the trigger signal is used to control the integration time of the incoming light. This mode is used to synchronize the exposure time of the camera to an external event. No parameter is required.

  • Page 150

    Acquiring Image Data The camera starts the integration of the incoming light from the first external trigger input falling edge. At the th external trigger input falling edge, integration stops. Parameter is required and must be or greater. (N >= 2). Trigger Mode 3 Use this internal trigger mode to achieve a lower frame rate.

  • Page 151

    Specifying the Trigger Type time of incoming light is described in the shutter register. Parameter required and must be or greater (N >= 1). Trigger Mode 4 This mode is the “multiple shutter preset mode.” It is similar to mode 1, but the exposure time is governed by the shutter property.

  • Page 152

    Acquiring Image Data The camera starts integration of incoming light from first the external trigger input falling edge and exposes incoming light until the trigger is inactive. Repeat this sequence until the Nth external trigger input falling edge, then finish integration. Parameter is required and must be or greater (N >= 1).

  • Page 153: Controlling Logging Parameters, Data Logging, Specifying Logging Mode

    If you want to bring image data into the MATLAB workspace, you must log frames to memory. The functions provided by the toolbox to move data into the workspace all work with the...

  • Page 154: Specifying The Number Of Frames To Log

    Acquiring Image Data memory buffer. For more information, see “Bringing Image Data into the MATLAB Workspace” on page 6-3. You can also log data to a disk file by setting the property to LoggingMode or to . By logging frames to a disk file, you create a 'disk' 'disk&memory'...

  • Page 155

    Controlling Logging Parameters Specifying the Amount of Data to Log Note While you can specify any size acquisition, the number of frames you can acquire is limited by the amount of memory you have available on your system for image storage. A large acquisition can potentially fill all available system memory.

  • Page 156: Determining How Much Data Has Been Logged

    Acquiring Image Data The following figure illustrates how the property affects FrameGrabInterval an acquisition. Impact of FrameGrabInterval on Data Logging Determining How Much Data Has Been Logged To determine how many frames have been acquired by a video input object, check the value of the property.

  • Page 157

    Controlling Logging Parameters Configure properties — Specify the amount of data you want to acquire as the number of frames per trigger. By default, a video input object acquires 10 frames per trigger. For this example, set the value of this property to set(vid,'FramesPerTrigger',100) Start the image acquisition object -—...

  • Page 158: Determining How Many Frames Are Available

    “Determining How Much Data Has Been Logged” on page 5-28. Once you move frames from the memory buffer into the MATLAB workspace, the number of frames stored in the memory buffer will differ from the value.

  • Page 159

    Controlling Logging Parameters The object executes an immediate trigger and begins acquiring frames of data. The function returns control to the command line immediately start but the object continues logging the data to the memory buffer. After logging the specified number of frames, the object stops running. Check how many frames have been acquired —...

  • Page 160

    To remove frames from the memory buffer, call the function, getdata specifying the number of frames to retrieve. For more information about using , see “Bringing Image Data into the MATLAB Workspace” getdata on page 6-3. data = getdata(vid,5); After you execute the...

  • Page 161: Delaying Data Logging After A Trigger

    Controlling Logging Parameters Contents of Memory Buffer Before and After Removing Frames Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them. delete(vid) clear vid Delaying Data Logging After a Trigger In some image acquisition setups, you might not want to log the first few frames returned from your camera or other imaging device.

  • Page 162: Specifying Multiple Triggers

    Acquiring Image Data Specifying a Delay Before Data Logging Begins Specifying Multiple Triggers When a trigger occurs, a video input object acquires the number of frames specified by the property and logs the data to a memory FramesPerTrigger buffer, a disk file, or both. When it acquires the specified number of frames, the video input object stops running.

  • Page 163

    Controlling Logging Parameters Executing Multiple Triggers 5-35...

  • Page 164: Waiting For An Acquisition To Finish, Using The Wait Function

    The following figure illustrates the flow of control at the MATLAB command line for a single execution of an immediate trigger and a manual trigger, with and without the function.

  • Page 165: Example: Blocking The Command Line Until An Acquisition Completes

    Waiting for an Acquisition to Finish Using wait to Block the MATLAB ® Command Line Example: Blocking the Command Line Until an Acquisition Completes The following example illustrates how to use the function to put a 60 wait second time limit on the execution of a hardware trigger. If the hardware...

  • Page 166

    Acquiring Image Data Create an image acquisition object — This example creates a video input object for a Matrox image acquisition device. To run this example on your system, use the function to get the object constructor for imaqhwinfo your image acquisition device and substitute that syntax for the following code.

  • Page 167

    Waiting for an Acquisition to Finish Start the image acquisition object — Call the function to start start the image acquisition object. start(vid) function sets the object running and returns control to the start command line. Block the command line until the acquisition finishes — After the function returns, call the function.

  • Page 168: Managing Memory Usage, Memory Usage, Monitoring Memory Usage

    Acquiring Image Data Managing Memory Usage In this section... “Memory Usage” on page 5-40 “Monitoring Memory Usage” on page 5-40 “Modifying the Frame Memory Limit” on page 5-41 “Freeing Memory” on page 5-42 Memory Usage The first time it needs to allocate memory to store an image frame, the toolbox determines the total amount of memory it has available to store acquired image frames.

  • Page 169: Modifying The Frame Memory Limit

    Managing Memory Usage out = imaqmem; mem_left = out.FrameMemoryLimit - out.FrameMemoryUsed; To see an example of using a callback function to monitor memory usage, see “Example: Monitoring Memory Usage” on page 7-17. Modifying the Frame Memory Limit To enable your image acquisition application to work with more image frames, you might want to increase the frame memory limit.

  • Page 170: Freeing Memory

    Acquiring Image Data Freeing Memory At times, while acquiring image data, you might want to delete some or all of the frames that are stored in memory. Using the function, you flushdata can delete all the frames currently stored in memory or only those frames associated with the execution of a trigger.

  • Page 171

    Managing Memory Usage To verify that the object acquired data, view the value of the property. This property reports how many frames are FramesAvailable currently stored in the memory buffer. vid.FramesAvailable ans = Delete a trigger’s worth of image data — Call the function, flushdata specifying the mode...

  • Page 172

    Acquiring Image Data Empty the entire memory buffer — Calling without flushdata specifying the mode deletes all the frames stored in memory. flushdata(vid); To verify that the object deleted the frames, view the value of the property. FramesAvailable vid.FramesAvailable ans = Clean up —...

  • Page 173: Logging Image Data To Disk, Logging Data To Disk

    Create a disk file to store the data. The toolbox logs the data to disk in Audio Video Interleave (AVI) format because this format provides data compression capabilities that allow for efficient storage. You must use the MATLAB function to create this log file. For more information, avifile see “Creating an AVI File Object for Logging”...

  • Page 174: Creating An Avi File Object For Logging

    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. Creating an AVI File Object for Logging To create an AVI file in the MATLAB environment, use the function. avifile You specify the name of the AVI file to the function.

  • Page 175

    Logging Image Data to Disk For more information about AVI file objects, see the MATLAB avifile documentation. For more information about using AVI files to log image data, see the following topics. • “Logging Grayscale Images” on page 5-47 • “Guidelines for Using an AVI File Object to Log Image Data” on page 5-47 •...

  • Page 176: Example: Logging Data To Disk

    This example illustrates how to configure a video input object to log data to a disk file: Create a MATLAB AVI file object — Create the MATLAB AVI file that you want to use for data logging, using the function. You specify avifile the name of the AVI file when you create it.

  • Page 177

    Logging Image Data to Disk Adjustable parameters: Fps: 15.0000 Compression: 'Indeo3' Quality: 75 KeyFramePerSec: 2.1429 VideoName: 'my_datalog.avi' Automatically updated parameters: Filename: 'my_datalog.avi' TotalFrames: 0 Width: 0 Height: 0 Length: 0 ImageType: 'Unknown' CurrentState: 'Open' Configure properties of the AVI file object — You can optionally configure the properties of the AVI file object.

  • Page 178

    Acquiring Image Data Configure video input object properties — Set up disk logging by setting the value of the property to be , the AVI file DiskLogger aviobj object created in step 1. Then, set the property to LoggingMode 'disk' ).

  • Page 179

    Close the AVI file object — Close the AVI file to make it available outside the MATLAB environment. Closing the AVI file object ensures that the logged data is written to the disk file. Be sure to use the value of the...

  • Page 180

    Acquiring Image Data 5-52...

  • Page 181

    MATLAB workspace. • “Overview” on page 6-2 • “Bringing Image Data into the MATLAB Workspace” on page 6-3 • “Working with Image Data in the MATLAB Workspace” on page 6-12 • “Retrieving Timing Information” on page 6-20...

  • Page 182

    MATLAB workspace. The following figure illustrates a group of frames being acquired from the video stream, logged to memory and disk, and brought into the MATLAB workspace as a multidimensional numeric array. Note that when frames are brought into the MATLAB workspace, they are removed from the memory buffer.

  • Page 183: Bringing Image Data Into The Matlab Workspace, Overview

    The function blocks the MATLAB command line until all the requested frames are available, or until a timeout value expires. For more information, see “Moving Multiple Frames into the Workspace” on page 6-4.

  • Page 184: Moving Multiple Frames Into The Workspace

    Toolbox demo Acquiring a Single Image in a Loop, or open the file demoimaq_GetSnapshot.m in the MATLAB Editor. Moving Multiple Frames into the Workspace To move multiple frames of data from the memory buffer into the MATLAB workspace, use the function. By default,...

  • Page 185

    ® Bringing Image Data into the MATLAB Workspace getdata Blocks Until Frames Become Available Example: Acquiring 10 Seconds of Image Data This example shows how you can configure an approximate time-based acquisition using the property: FramesPerTrigger Create an image acquisition object — This example creates a video input object for a Windows image acquisition device.

  • Page 186: Viewing Frames In The Memory Buffer

    Working with Acquired Image Data set(vid,'FramesPerTrigger',300) Start the image acquisition object — Call the function to start start the image acquisition object. start(vid) The object executes an immediate trigger and begins acquiring frames of data. The function returns control to the command line immediately start but the object continues logging the data to the memory buffer.

  • Page 187

    ® Bringing Image Data into the MATLAB Workspace the frames returned by at each call. ( returns frames peekdata peekdata without removing them from the memory buffer.) Note in the figure that, at T , only two frames have become available since the last call to .

  • Page 188

    Working with Acquired Image Data triggerconfig(vid,'manual') In addition, configure a large enough acquisition to allow several calls to before it finishes. peekdata set(vid,'FramesPerTrigger',300); Start the image acquisition object — Call the function to start start the image acquisition object. start(vid) The video object is now running but not logging.

  • Page 189

    ® Bringing Image Data into the MATLAB Workspace Name Size Bytes Class pdata 96x128x3 36864 uint8 array 1060 videoinput object Verify that the object has not acquired any frames. get(vid,'FramesAcquired') ans = Trigger the acquisition — Call the function to trigger an trigger acquisition.

  • Page 190: Bringing A Single Frame Into The Workspace

    Bringing a Single Frame into the Workspace To bring a single frame of image data into the MATLAB workspace, use the function. You can call the function at any time getsnapshot getsnapshot after object creation.

  • Page 191

    ® Bringing Image Data into the MATLAB Workspace Note that the frame returned by is not removed from the getsnapshot memory buffer, if frames are stored there, and does not affect the value of the property. FramesAvailable Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.

  • Page 192: Working With Image Data In The Matlab Workspace, Understanding Image Data

    Working with Acquired Image Data Working with Image Data in the MATLAB Workspace In this section... “Understanding Image Data” on page 6-12 “Determining the Dimensions of Image Data” on page 6-13 “Determining the Data Type of Image Frames” on page 6-16 “Specifying the Color Space”...

  • Page 193: Determining The Dimensions Of Image Data

    Note Because devices typically express video resolution as width-by-height, the toolbox uses this convention for the property. However, VideoResolution when data is brought into the MATLAB workspace, the image frame dimensions are listed in reverse order, height-by-width, because MATLAB expresses matrix dimensions as row-by-column. ROIs and Image Dimensions...

  • Page 194

    Working with Acquired Image Data image data being provided by the device; the property specifies ROIPosition the dimensions of the image frames being logged. See the ROIPosition property reference page for more information. Example: Video Format and Image Dimensions The following example illustrates how video format affects the size of the image frames returned.

  • Page 195

    ® Working with Image Data in the MATLAB Workspace View the video format and video resolution properties — The toolbox creates the object with the default video format. This format defines the video resolution. get(vid,'VideoFormat') ans = M_RS170 get(vid,'VideoResolution') ans = [640 480] Bring a single frame into the workspace —...

  • Page 196: Determining The Data Type Of Image Frames

    Determining the Data Type of Image Frames By default, the toolbox returns image frames in the data type used by the image acquisition device. If there is no MATLAB data type that matches the object’s native data type, chooses a MATLAB data type that getdata preserves numerical accuracy.

  • Page 197: Specifying The Color Space

    ® Working with Image Data in the MATLAB Workspace vid = videoinput('matrox',1); Bring a single frame into the workspace — Call the getsnapshot function to bring a frame into the workspace. frame = getsnapshot(vid); View the class of the returned data — Use the...

  • Page 198

    Working with Acquired Image Data MathWorks™ product, the Image Processing Toolbox software, includes functions that convert YCbCr data to RGB data, and vice versa. Note Some devices that claim to support the YUV color space actually support the YCbCr color space. YUV is similar to YCbCr but not identical. The difference between YUV and YCbCr is the scaling factor applied to the result.

  • Page 199: Viewing Acquired Data

    Viewing Acquired Data Once you bring the data into the MATLAB workspace, you can view it as you would any other image in MATLAB. The Image Acquisition Toolbox software includes a function, imaqmontage that you can use to view all the frames of a multiframe image array in a single MATLAB image object.

  • Page 200: Retrieving Timing Information, Introduction, Determining When A Trigger Executed

    Working with Acquired Image Data Retrieving Timing Information In this section... “Introduction” on page 6-20 “Determining When a Trigger Executed” on page 6-20 “Determining When a Frame Was Acquired” on page 6-21 “Example: Determining the Frame Delay Duration” on page 6-22 Introduction The following sections describe how the toolbox provides acquisition timing information, particularly,...

  • Page 201: Determining When A Frame Was Acquired

    Retrieving Timing Information InitialTriggerTime Records First Trigger Execution The trigger timing information is stored in MATLAB clock vector format. The following example displays the time of the first trigger for the video input object . The example uses the MATLAB...

  • Page 202: Example: Determining The Frame Delay Duration

    7-7 for more information. Frame Metadata Field Name Description Absolute time the frame was acquired, returned in AbsTime MATLAB format clock [year month day hour minute seconds] Frame number relative to when the object was started FrameNumber Frame number relative to trigger execution RelativeFrame Trigger the event is associated with.

  • Page 203

    Retrieving Timing Information function to get the object constructor for your image acquisition imaqhwinfo device and substitute that syntax for the following code. vid = videoinput('dt',1); Configure properties — For this example, configure a trigger frame delay large enough to produce a noticeable duration. set(vid,'TriggerFrameDelay',50) Start the image acquisition object —...

  • Page 204

    Working with Acquired Image Data 6.0544 6.2143 6.3424 Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them. delete(vid) clear vid 6-24...

  • Page 205

    Using Events and Callbacks You can enhance the power and flexibility of your image acquisition application by using event callbacks. An event is a specific occurrence that can happen while an image acquisition object is running. The toolbox defines a set of events that include starting, stopping, or acquiring frames of data. When a particular event occurs, the toolbox can execute a function that you specify.

  • Page 206: Example: Using The Default Callback Function

    Using Events and Callbacks Example: Using the Default Callback Function To illustrate how to use callbacks, this section presents a simple example that creates an image acquisition object and associates a callback function with the start event, trigger event, and stop event. For information about all the event callbacks supported by the toolbox, see “Event Types”...

  • Page 207

    Example: Using the Default Callback Function Trigger event occurred at 14:38:46 for video input object: M_RS170-matrox-1. Stop event occurred at 14:38:49 for video input object: M_RS170-matrox-1. Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them. delete(vid) clear vid...

  • Page 208: Event Types

    ErrorFcn By default, the toolbox executes the default callback function for this event, imaqcallback which displays the error message at the MATLAB command line. Frames The toolbox generates a frames acquired event when FramesAcquiredFcn Acquired a specified number of frames have been acquired.

  • Page 209

    Event Types Events and Callback Function Properties (Continued) Event Callback Property Description Start The toolbox generates a start event when an object StartFcn is started. You use the function to start an start object. When a start event occurs, the toolbox executes the function specified by the property.

  • Page 210

    Using Events and Callbacks Events and Callback Function Properties (Continued) Event Callback Property Description Timer The toolbox generates a timer event when a specified TimerFcn amount of time expires. Time is measured relative to when the object starts running. You use the property to specify the amount of time.

  • Page 211: Retrieving Event Information, Introduction, Event Structures

    Retrieving Event Information Retrieving Event Information In this section... “Introduction” on page 7-7 “Event Structures” on page 7-7 “Example: Accessing Data in the Event Log” on page 7-9 Introduction Each event has associated with it a set of information, generated by the toolbox and stored in an event structure.

  • Page 212

    Using Events and Callbacks occurred. For information about the information associated with specific events, see the following sections: • “Data Fields for Start, Stop, Frames Acquired, and Trigger Events” on page 7-8 • “Data Fields for Error Events” on page 7-8 •...

  • Page 213: Example: Accessing Data In The Event Log

    Data Fields for Timer Events For timer events, the structure contains these fields. Data Field Name Description Absolute time the event occurred, returned in MATLAB AbsTime format clock [year month day hour minute seconds] Amount of memory allotted for frame storage. You can...

  • Page 214

    Using Events and Callbacks The toolbox adds event structures to the array in the order in which EventLog the events occur. The first event structure reflects the first event recorded, the second event structure reflects the second event recorded, and so on. Note Only start, stop, error, and trigger events are recorded in the EventLog property.

  • Page 215

    Retrieving Event Information To list the events that are recorded in the property, examine the EventLog contents of the field. Type {events.Type} ans = 'Start' 'Trigger' 'Stop' To get information about a particular event, access the field in that Data event structure.

  • Page 216: Creating And Executing Callback Functions, Introduction, Creating Callback Functions

    Using Events and Callbacks Creating and Executing Callback Functions In this section... “Introduction” on page 7-12 “Creating Callback Functions” on page 7-12 “Specifying Callback Functions” on page 7-14 “Example: Viewing a Sample Frame” on page 7-16 “Example: Monitoring Memory Usage” on page 7-17 Introduction The power of using event callbacks is the processing that you can perform in response to events.

  • Page 217

    To implement this function, the callback function acquires a single frame of data and displays the acquired frame in a MATLAB figure window. The function also accesses the event structure passed as an argument to display the timestamp of the frame being displayed.

  • Page 218: Specifying Callback Functions

    Using Events and Callbacks function display_frame(obj,event) sample_frame = peekdata(obj,1); imagesc(sample_frame); drawnow; % force an update of the figure window abstime = event.Data.AbsTime; t = fix(abstime); sprintf('%s %d:%d:%d','timestamp', t(4),t(5),t(6)) To see how this function can be used as a callback, see “Example: Viewing a Sample Frame”...

  • Page 219

    StartFcn vid.StartFcn = 'mycallback'; In this case, the callback is evaluated in the MATLAB workspace. Using a Cell Array to Specify Callback Functions You can specify the callback function as a text string inside a cell array.

  • Page 220: Example: Viewing A Sample Frame

    Using Events and Callbacks If you are executing a local callback function from within a MATLAB file, you must specify the callback as a function handle. Specifying a Toolbox Function as a Callback In addition to specifying callback functions of your own creation, you can...

  • Page 221: Example: Monitoring Memory Usage

    Creating and Executing Callback Functions vid = videoinput('matrox', 1); Configure property values — This example sets the FramesPerTrigger value to 30 and the property to 4. The example also TriggerRepeat specifies as the value of the callback the event FramesAcquiredFcn callback function , created in “Example: Writing a Callback display_frame...

  • Page 222

    Using Events and Callbacks function mem_mon(obj,event) out = imaqmem; mem_left = out.FrameMemoryLimit - out.FrameMemoryUsed; msg = 'Memory left for frames'; msg2 = 'Memory load'; low_limit = 2000000; if(mem_left > low_limit) sprintf('%s: %d \n%s: %d',msg, mem_left,msg2, out.MemoryLoad) else disp('Memory available for frames getting low.'); disp('Stopping acquisition.') stop(obj);...

  • Page 223

    Creating and Executing Callback Functions Acquire data — Start the video input object. Every 5 seconds, the object executes the callback function associated with the timer event. This function outputs the current memory available for frame storage and the memory load statistic. When the amount of memory reaches the specified lower limit, the callback function stops the acquisition.

  • Page 224

    Using Events and Callbacks 7-20...

  • Page 225

    Using the From Video Device Block in Simulink The Image Acquisition Toolbox software includes a block that can be used in Simulink to bring live video data into models. • “Overview” on page 8-2 • “Opening the Block Library” on page 8-3 •...

  • Page 226

    ® Using the From Video Device Block in Simulink Overview This chapter describes how to use the Image Acquisition Toolbox block library. The toolbox block library contains one block called the From Video Device block. You can use this block to acquire live video data in a Simulink model.

  • Page 227: Opening The Block Library, Using The Imaqlib Command, Using The Simulink Library Browser

    “Using the Simulink Library Browser” on page 8-3 Using the imaqlib Command To open the Image Acquisition Toolbox block library, enter imaqlib at the MATLAB prompt. MATLAB displays the contents of the library in a separate window. Image Acquisition Toolbox™ Block Library Using the Simulink Library Browser To open the Image Acquisition Toolbox block library, start the Simulink Library Browser and select the library from the list of available block libraries.

  • Page 228

    To start the Simulink Library Browser, enter simulink at the MATLAB prompt. MATLAB opens the browser window. The left pane contains a list of available block libraries in alphabetical order. To open the Image Acquisition Toolbox block library, click its icon.

  • Page 229: Example: Saving Video Data To A File, Introduction

    Toolbox block library. To open the library, start the Simulink Library Browser and select the Image Acquisition Toolbox entry from the list. To start the Simulink Library Browser, enter simulink at the MATLAB prompt. (For more information about opening the library, see “Opening the Block Library” on page 8-3.)

  • Page 230: Step 2: Open A Model Or Create A New Model

    ® Using the From Video Device Block in Simulink Step 2: Open a Model or Create a New Model To use a block, you must add it to an existing model or create a new model. To create a new model, select File > New > Model from the Simulink Library Browser.

  • Page 231: Model

    Example: Saving Video Data to a File Step 3: Drag the From Video Device Block into the Model To use the From Video Device block in a model, click the block in the library and, holding the mouse button down, drag it into the model window. Note how the name on the block changes to reflect the device connected to your system that is associated with the block.

  • Page 232: Step 4: Drag Other Blocks To Complete The Model

    ® Using the From Video Device Block in Simulink Step 4: Drag Other Blocks to Complete the Model To illustrate using the block, this example creates a simple model that acquires data and then outputs the data to a file in Audio Video Interleave (AVI) format.

  • Page 233: Step 5: Connect The Blocks

    Example: Saving Video Data to a File Drag Output Block to Model Window Step 5: Connect the Blocks Connect the three outputs from the From Video Device block to the three corresponding inputs on the To Multimedia File block. (You can leave the Audio input on the To Multimedia File block unconnected.) One quick way to...

  • Page 234: Values

    ® Using the From Video Device Block in Simulink make all three connections at once is to select the From Video Device block, press and hold the Ctrl key, and then click the To Multimedia File block. Notice that the output ports on this particular camera device are Y, Cb, and the input ports on the To Multimedia File block are .

  • Page 235

    Example: Saving Video Data to a File For example, using this dialog box, you can specify the device you want to use, select the video format you want to use with the device, or specify the block sample time. For more details, see the From Video Device block reference page.

  • Page 236: Step 7: Run The Simulation

    ® Using the From Video Device Block in Simulink Step 7: Run the Simulation To run the simulation, click the Start simulation button on the model window toolbar. You can use toolbar options to specify how long to run the simulation and to stop a running simulation.

  • Page 237

    Adding Support for Additional Hardware The Image Acquisition Toolbox software supports connections with hardware from many common vendors, but it might not support the hardware you use. To add support for your hardware, you can create an adaptor using the Image Acquisition Toolbox Adaptor Kit.

  • Page 238

    Adding Support for Additional Hardware Overview The Image Acquisition Toolbox Adaptor Kit is a C++ framework that you can use to implement an adaptor. An adaptor is a dynamic link library (DLL) that implements the connection between the Image Acquisition Toolbox engine and a device driver via the vendor’s SDK API.

  • Page 239

    To learn more about creating an adaptor, read the Image Acquisition Toolbox Adaptor Kit User’s Guide. For detailed information about the adaptor kit framework classes, see the Image Acquisition Toolbox Adaptor Kit Class Reference, which is available in matlabroot\toolbox\imaq\imaqadaptors\kit\doc\adaptorkit.chm where represents your MATLAB installation directory. matlabroot...

  • Page 240

    Adding Support for Additional Hardware...

  • Page 241

    Troubleshooting This chapter provides information about solving common problems you might encounter with the Image Acquisition Toolbox software and the video acquisition hardware it supports. • “Overview” on page 10-2 • “Troubleshooting DALSA Coreco IFC Hardware” on page 10-3 • “Troubleshooting DALSA Coreco Sapera Hardware” on page 10-5 •...

  • Page 242

    Troubleshooting Overview If, after installing the Image Acquisition Toolbox software and using it to establish a connection to your image acquisition device, you are unable to acquire data or encounter other problems, try these troubleshooting steps first. They might help fix the problem. Verify that your image acquisition hardware is functioning properly.

  • Page 243: Troubleshooting Dalsa Coreco Ifc Hardware, Troubleshooting Dalsa Coreco Ifc Devices

    ® Troubleshooting DALSA Coreco IFC Hardware Troubleshooting DALSA Coreco IFC Hardware In this section... “Troubleshooting DALSA Coreco IFC Devices” on page 10-3 “Determining the Driver Version for DALSA Coreco IFC Devices” on page 10-4 Troubleshooting DALSA Coreco IFC Devices The Image Acquisition Toolbox software supports the use of both DALSA ®...

  • Page 244: Determining The Driver Version For Dalsa Coreco Ifc Devices

    Troubleshooting supported drivers on the Image Acquisition Toolbox product page at the MathWorks Web site ( www.mathworks.com/products/imaq If you discover that you are using an unsupported driver version, visit the DALSA Coreco Web site ( ) to download the correct driver. www.imaging.com Determining the Driver Version for DALSA Coreco IFC Devices...

  • Page 245: Troubleshooting Dalsa Coreco Sapera Hardware, Troubleshooting Dalsa Coreco Sapera Devices

    ® Troubleshooting DALSA Coreco Sapera Hardware Troubleshooting DALSA Coreco Sapera Hardware In this section... “Troubleshooting DALSA Coreco Sapera Devices” on page 10-5 “Determining the Driver Version for DALSA Coreco Sapera Devices” on page 10-6 Troubleshooting DALSA Coreco Sapera Devices The Image Acquisition Toolbox software supports the use of both DALSA Coreco IFC hardware and DALSA Coreco Sapera hardware.

  • Page 246: Determining The Driver Version For Dalsa Coreco Sapera Devices

    Troubleshooting • Find out the driver version you are using on your system. To learn how to get this information, see “Determining the Driver Version for DALSA Coreco Sapera Devices” on page 10-6. • Verify that the version is compatible with the Image Acquisition Toolbox software.

  • Page 247: Troubleshooting Data Translation Hardware

    ® Troubleshooting Data Translation Hardware Troubleshooting Data Translation Hardware If you are having trouble using the Image Acquisition Toolbox software with a supported Data Translation frame grabber, follow these troubleshooting steps: Verify that your image acquisition hardware is functioning properly. For Data Translation devices, run the application that came with your hardware and verify that you can receive live video.

  • Page 248: Troubleshooting Dcam Ieee 1394 Hardware

    Troubleshooting Troubleshooting DCAM IEEE 1394 (FireWire) Hardware In this section... “Troubleshooting DCAM IEEE 1394 Hardware” on page 10-8 “Installing the CMU DCAM Driver” on page 10-9 “Running the CMU Camera Demo Application” on page 10-10 Troubleshooting DCAM IEEE 1394 Hardware If you are having trouble using the Image Acquisition Toolbox software with an IEEE 1394 (FireWire) camera, using the toolbox’s adaptor, follow...

  • Page 249: Installing The Cmu Dcam Driver

    ® Troubleshooting DCAM IEEE 1394 (FireWire) Hardware Verify that your IEEE 1394 (FireWire) camera is using the Carnegie Mellon University (CMU) DCAM driver version 6.4.4. Note The toolbox only supports connections to IEEE 1394 (FireWire) DCAM-compliant devices using the CMU DCAM driver. The toolbox is not compatible with any other vendor-supplied driver, even if the driver is DCAM compliant.

  • Page 250: Running The Cmu Camera Demo Application

    CMU DCAM installation file, 1394camera644.exe in the directory matlabroot\toolbox\imaq\imaqextern\drivers\win32\dcam where represents the name of your MATLAB installation matlabroot directory. You can also download the DCAM driver directly from CMU. Go to the Web site and click the download link.

  • Page 251

    ® Troubleshooting DCAM IEEE 1394 (FireWire) Hardware From the Camera Demo application, select Camera > Check Link. This option causes the demo application to look for DCAM-compatible cameras that are available through the IEEE 1394 (FireWire) connection. The demo application displays the results of this search in a pop-up message box.

  • Page 252

    Troubleshooting Note If you are using 1394b, select Camera > 1394b Support, and then check the Maximum Speed option after choosing 1394b support. If you do not see 400 MB per second or higher, refer to the customer technical solution on that topic, http://www.mathworks.com/support/solutions/data/1-3LNN8U.html.

  • Page 253

    ® Troubleshooting DCAM IEEE 1394 (FireWire) Hardware 10-13...

  • Page 254

    Troubleshooting The demo application starts displaying live video in the window. To exit, select Stop Camera from the Camera menu and then click Exit. 10-14...

  • Page 255: Troubleshooting Hamamatsu Hardware

    Troubleshooting Hamamatsu Hardware Troubleshooting Hamamatsu Hardware If you are having trouble using the Image Acquisition Toolbox software with a x Hamamatsu digital camera, follow these troubleshooting steps: Verify that your image acquisition hardware is functioning properly. • Make sure that your camera is plugged into the IEEE 1394 (FireWire) port on your computer and is powered up.

  • Page 256: Troubleshooting Matrox Hardware, Troubleshooting Matrox Devices

    If you discover that you are using an unsupported driver version, visit the Matrox Web site ( ) to download the correct drivers. www.matrox.com Note There is no difference between MIL and MIL-Lite software inside of MATLAB. They both work with Matrox Imaging devices. 10-16...

  • Page 257: Determining The Driver Version For Matrox Devices

    ® Troubleshooting Matrox Hardware Determining the Driver Version for Matrox Devices To determine the Matrox Imaging Library version you are using, run the Matrox MIL Configuration utility. You can access this software through the Windows Start button. Select Start > Programs > Matrox Imaging Products > MIL Configuration.

  • Page 258: Troubleshooting Qimaging Hardware, Troubleshooting Qimaging Devices

    Troubleshooting Troubleshooting QImaging Hardware In this section... “Troubleshooting QImaging Devices” on page 10-18 “Determining the Driver Version for QImaging Devices” on page 10-19 Troubleshooting QImaging Devices If you are having trouble using the Image Acquisition Toolbox software with a supported x QImaging frame grabber, follow these troubleshooting steps: Verify that your image acquisition hardware is functioning properly.

  • Page 259: Determining The Driver Version For Qimaging Devices

    Troubleshooting QImaging Hardware If you discover that you are using an unsupported driver version, visit the QImaging Web site ( ) to download the correct drivers. www.qimaging.com Determining the Driver Version for QImaging Devices To determine the QImaging driver version you are using, run the QImaging QCapture utility.

  • Page 260: Troubleshooting National Instruments Hardware, Troubleshooting National Instruments Devices

    Troubleshooting Troubleshooting National Instruments Hardware In this section... “Troubleshooting National Instruments Devices” on page 10-20 “Determining the Driver Version for National Instruments Devices” on page 10-21 Troubleshooting National Instruments Devices If you are having trouble using the Image Acquisition Toolbox software with a supported National Instruments ®...

  • Page 261: Determining The Driver Version For National Instruments Devices

    ® Troubleshooting National Instruments Hardware Note The Image Acquisition Toolbox software is compatible only with specific driver versions provided with the National Instruments software and is not guaranteed to work with any other versions. • Find out the driver version you are using on your system. To learn how to get this information, see Determining the Driver Version.

  • Page 262: Troubleshooting Windows Video Hardware, Troubleshooting Windows Video Devices

    Troubleshooting Troubleshooting Windows Video Hardware In this section... “Troubleshooting Windows Video Devices” on page 10-22 “Determining the Microsoft DirectX Version” on page 10-23 Troubleshooting Windows Video Devices If you are having trouble using the Image Acquisition Toolbox software with a supported Windows video acquisition device, follow these recommended troubleshooting steps: Verify that your image acquisition hardware is functioning properly.

  • Page 263: Determining The Microsoft Directx Version

    ® Troubleshooting Windows Video Hardware If you discover that you are using an unsupported driver version, visit the hardware manufacturer’s Web site for the correct drivers. Note The Windows Video driver is a generic interface and should only be used if you do not have a more specific driver to use with your device. For example, use the device-specific driver if your device has one.

  • Page 264

    Troubleshooting In the DirectX Diagnostic Tool, the Microsoft DirectX version is listed on the System tab under the System Information section. DirectX ® Diagnostic Tool 10-24...

  • Page 265: Troubleshooting A Video Preview Window

    Video Preview window stops • Close the preview window and reopen it. running. • Verify that your image acquisition device is working properly. Close MATLAB and run the application that came with your device. • Make sure no other application is using the device.

  • Page 266

    • The characteristics of your hardware • Information about your adaptors The output from is automatically saved to a text file, imaqsupport , which you can use to help troubleshoot your problem. imaqsupport.txt To have MATLAB generate this file for you, type imaqsupport 10-26...

  • Page 267: General-purpose Objects, Triggering

    Function Reference General-Purpose Objects (p. 11-2) Functions related to objects Triggering (p. 11-3) Functions related to triggering Data (p. 11-3) Functions related to data Tools (p. 11-4) Functions related to image acquisition tools Getting Command-Line Function Command-line function help Help (p. 11-5)

  • Page 268: Data

    In this table, functions that work on both types of objects use the phrase “image acquisition object” to refer to both types of objects. Clear image acquisition object from clear MATLAB workspace Remove image acquisition object delete from memory...

  • Page 269: Tools

    Provide information about available triggerinfo trigger configurations Data Remove data from memory buffer flushdata used to store acquired image frames Acquired image frames to MATLAB getdata workspace Immediately return single image getsnapshot frame Most recently acquired image data peekdata...

  • Page 270

    Function Reference Tools Close Video Preview window closepreview Image acquisition object function imaqhelp and property help Information about available image imaqhwinfo acquisition hardware Limit memory or display memory imaqmem usage for Image Acquisition Toolbox software Sequence of image frames as imaqmontage montage Disconnect and delete all image...

  • Page 271: Getting Command-line Function Help

    Getting Command-Line Function Help Getting Command-Line Function Help To get command-line function help, you can use the MATLAB function. help For example, to get help for the function, type the following: getsnapshot help getsnapshot However, the Image Acquisition Toolbox software provides “overloaded”...

  • Page 272

    Function Reference You can also use this function to get help on image acquisition object properties. For more information on overloaded functions and class directories, refer to MATLAB Classes and Objects in the Help browser. 11-6...

  • Page 273

    Functions — Alphabetical List...

  • Page 274

    (the property is set to , the object continues Running 'on') executing. You can restore cleared objects to the MATLAB workspace with the function. imaqfind To remove an image acquisition object from memory, use the delete function. See Also...

  • Page 275

    closepreview Purpose Close Video Preview window Syntax closepreview(obj) closepreview Description stops the image acquisition object from closepreview(obj) previewing and, if the default Video Preview window was used, closes the window. stops all image acquisition objects from previewing and, closepreview for all image acquisition objects that used the default Video Preview window, closes the windows.

  • Page 276

    Use command to remove invalid image acquisition objects from clear the MATLAB workspace. If multiple references to an image acquisition object exist in the workspace, deleting the image acquisition object invalidates the remaining references.

  • Page 277

    disp Purpose Display method for image acquisition objects Syntax disp(obj) Description displays summary information for image acquisition object displays summary information for image acquisition object disp(obj) is an array of image acquisition objects, outputs a table of disp summary information about the image acquisition objects in the array. In addition to the syntax shown above, you can display summary information for by excluding the semicolon when:...

  • Page 278

    disp This example shows the summary information displayed for an array of video input objects. vid2 = videoinput('winvideo'); [vid vid2] Video Input Object Array: Index: Type: Name: videoinput RGB555_128x96-winvideo-1 videoinput RGB555_128x96-winvideo-1 See Also videoinput 12-6...

  • Page 279

    flushdata Purpose Remove data from memory buffer used to store acquired image frames Syntax flushdata(obj) flushdata(obj,mode) Description removes all the data from the memory buffer used to flushdata(obj) store acquired image frames. can be a single video input object or an array of video input objects. removes all the data from the memory buffer flushdata(obj,mode) used to store acquired image frames, where...

  • Page 280

    Purpose Return image acquisition object properties Syntax get(obj) V = get(obj) V = get(obj,PropertyName) Description displays all property names and their current values for get(obj) image acquisition object returns a structure, , in which each field name is the V = get(obj) name of a property of and each field contains the value of that property.

  • Page 281

    Number of color bands, as specified in the NumberOfBands property The number of frames returned is returned to the MATLAB workspace in its native data type data using the color space specified by the property. ReturnedColorSpace You can use the MATLAB...

  • Page 282

    = getdata(obj,n,type,format) associated with the video input object , where is one of the format text strings in the following table that specify the MATLAB format data Format String Description Returns as an H-by-W-by-B-by-F array. This is...

  • Page 283

    Number of the trigger in which this frame was 'TriggerIndex' acquired is a blocking function that returns execution control to the getdata MATLAB workspace after the requested number of frames becomes available within the time period specified by the object’s Timeout property. The object’s property is automatically...

  • Page 284

    getdata data = getdata(obj); Display each image frame acquired. imaqmontage(data); Remove the video input object from memory. delete(obj); See Also getsnapshot imaqhelp imaqmontage peekdata propinfo 12-12...

  • Page 285

    getselectedsource Purpose Return currently selected video source object Syntax src = getselectedsource(obj) Description searches all the video source objects src = getselectedsource(obj) associated with the video input object and returns the video source object, , that has the property value set to Selected 'on' To select a source for acquisition, use the...

  • Page 286

    ROIPosition Number of bands associated with , as specified in the property NumberOfBands is returned to the MATLAB workspace in its native data type frame using the color space specified by the property. ReturnedColorSpace You can use the MATLAB...

  • Page 287

    Remove the video input object from memory. delete(obj); For an example of using , see the Image Acquisition getsnapshot Toolbox demo Acquiring a Single Image in a Loop, or open the file demoimaq_GetSnapshot.m in the MATLAB Editor. See Also getdata imaqhelp peekdata 12-15...

  • Page 288

    imaqfind Purpose Find image acquisition objects Syntax imaqfind out = imaqfind out = imaqfind(PropertyName, Value, PropertyName2, Value2, ...) out = imaqfind(S) out = imaqfind(obj, PropertyName, Value, PropertyName2, Value2,...) Description returns an array containing all the video input objects that imaqfind exist in memory.

  • Page 289

    imaqfind Note When searching for properties with specific values, imaqfind performs case-sensitive searches. For example, if the value of an object’s property is does not find a match if you Name 'MyObject' imaqfind specify . Note, however, that searches for properties that 'myobject' have an enumerated list of possible values are not case sensitive.

  • Page 290

    imaqhelp Purpose Image acquisition object function and property help Syntax imaqhelp imaqhelp(Name) imaqhelp(obj) imaqhelp(obj,Name) out = imaqhelp(...) Description provides a complete listing of image acquisition object imaqhelp functions. provides online help for the function or property imaqhelp(Name) specified by the text string Name displays a listing of functions and properties for the imaqhelp(obj)

  • Page 291

    imaqhelp vid = videoinput('dt', 1); src = getselectedsource(vid); imaqhelp(vid, 'TriggerType') imaqhelp(src, 'FrameRate') See Also propinfo 12-19...

  • Page 292

    = imaqhwinfo about the image acquisition adaptors available on the system. An adaptor is the interface between MATLAB and the image acquisition devices connected to the system. The adaptor’s main purpose is to pass information between MATLAB and an image acquisition device via its driver.

  • Page 293

    To force the toolbox to search for new hardware that might have been installed while MATLAB was running, use imaqreset Examples This example returns information about all the adaptors available on the system.

  • Page 294

    imaqhwinfo This example returns information about a specific device accessible through a particular adaptor. You identify the device by its device ID. dev_info = imaqhwinfo('winvideo', 1) dev_info = DefaultFormat: 'RGB555_128x96' DeviceFileSupported: 0 DeviceName: 'IBM PC Camera' DeviceID: 1 ObjectConstructor: 'videoinput('winvideo', 1)' SupportedFormats: {1x34 cell} This example gets information about the device associated with a particular video input object.

  • Page 295

    imaqhwinfo winvideo See Also imaqhelp imaqreset 12-23...

  • Page 296

    imaqmem Purpose Limit memory or display memory usage for Image Acquisition Toolbox software Syntax mem = imaqmem imaqmem(field) imaqmem(limit) Description returns a structure containing the following fields: mem = imaqmem Field Description Number between 0 and 100 that gives a general MemoryLoad idea of current memory utilization Total number of bytes of physical memory...

  • Page 297

    Note Configuring the frame memory limit does not remove any logged frames from the image acquisition memory buffer. To remove frames from the buffer, you can bring them into the MATLAB workspace, using the function, or remove them from memory, using the getdata function.

  • Page 298

    imaqmem 38313984 Specify the amount of memory available for the toolbox to log image frames ( FrameMemoryLimit imaqmem(30000000) ans = MemoryLoad: 85 TotalPhys: 263766016 AvailPhys: 37634048 TotalPageFile: 643878912 AvailPageFile: 391479296 TotalVirtual: 2.1474e+009 AvailVirtual: 1.6307e+009 FrameMemoryLimit: 30000000 FrameMemoryUsed: 0 See Also flushdata getdata videoinput...

  • Page 299

    MATLAB figure window using the function. must be a 1-by-1 video input object. imagesc displays a montage of image frames, where imaqmontage(...,CLIM)

  • Page 300

    imaqmontage Create an axes object. a = axes; Display each image frame acquired on axes imaqmontage(data, 'Parent', a); Remove the video input object from memory. delete(obj); See Also getdata getsnapshot imaqhelp peekdata 12-28...

  • Page 301

    As a result, the image acquisition hardware is reset. is the image acquisition command that returns MATLAB to imaqreset the known state of having no image acquisition objects and no loaded image acquisition adaptors.

  • Page 302

    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.

  • Page 303

    islogging Purpose Determine whether video input object is logging Syntax bool = islogging(obj) Description returns if the video input object bool = islogging(obj) true logging data, otherwise . A video input object is logging if the false value of its property is set to Logging 'on'...

  • Page 304

    islogging Start one of the video input objects again, such as , and use to determine which of the two objects is logging. islogging start(vid) bool = islogging([vid vid2]) bool = See Also isrunning isvalid videoinput Properties Logging LoggingMode 12-32...

  • Page 305

    isrunning Purpose Determine whether video input object is running Syntax bool = isrunning(obj) Description returns if the video input object bool = isrunning(obj) true running, otherwise . A video input object is running if the value of false property is set to Running 'on' is an array of video input objects,...

  • Page 306

    isvalid Purpose Determine whether image acquisition object is associated with image acquisition device Syntax bool = isvalid(obj) Description returns if the video input object bool = isvalid(obj) true valid, otherwise . An object is an invalid image acquisition object false if it is no longer associated with any hardware;...

  • Page 307

    Purpose Load image acquisition object into MATLAB workspace Syntax load filename load filename obj1 obj2 ... S = load(filename,obj1,obj2,...) Description returns all variables from the MAT-file load filename filename the MATLAB workspace. returns the specified image acquisition load filename obj1 obj2 ...

  • Page 308

    M-file with the name specified by . The M-file contains the filename MATLAB code required to create the object and set its properties. can be a single video input object or an array of objects. function simplifies the process of restoring an object...

  • Page 309

    (dot 'dot' obj2mfile notation) when specifying property values. converts to the obj2mfile(obj,filename,syntax,mode) equivalent MATLAB code where specifies which properties are mode configured. can be either of the following strings. The default mode value is enclosed in braces ({}).

  • Page 310

    obj2mfile String Description and modify an existing object, if the existing object {'reuse'} Find is associated with the same adaptor and the values of , and properties match DeviceID VideoFormat the object being created. If no matching object can be found, creates a new object.

  • Page 311

    obj2mfile delete(vidobj); clear vidobj; Execute the M-file to recreate the object. Note that creates obj2mfile and configures the associated video source object as well. vidObj = myvidobj; See Also getselectedsource imaqhelp propinfo videoinput 12-39...

  • Page 312

    Number of color bands, as specified in the NumberOfBands property Number of frames returned is returned to the MATLAB workspace in its native data type data using the color space specified by the property. ReturnedColorSpace You can use the MATLAB...

  • Page 313

    peekdata The behavior of depends on the settings of the peekdata Running properties. Logging Running Logging Object State Result The object has been started returns a single peekdata but is waiting for a trigger. frame of data and issues a is set to warning, if you requested more TriggerType...

  • Page 314

    preview Purpose Preview of live video data Syntax preview(obj) preview(obj,himage) himage = preview(...) Description creates a Video Preview window that displays live video preview(obj) data for video input object . The window also displays the timestamp and video resolution of each frame, and the current status of .

  • Page 315

    preview displays live video data for video input object preview(obj,himage) in the image object specified by the handle scales himage preview the image data to fill the entire area of the image object but does not modify the values of any image object properties. Use this syntax to preview video data in a custom GUI of your own design (see Examples).

  • Page 316

    Update 'UpdatePreviewWindowFcn' its value to an empty array ( ). You can configure the value of Function application data and retrieve its 'UpdatePreviewWindowFcn' value using the MATLAB functions, setappdata getappdata respectively. will not necessarily be called for 'UpdatePreviewWindowFcn' every frame that is acquired. If a new frame is acquired and the...

  • Page 317

    preview The event structure contains the following fields: Field Description Current image frame specified as an H-by-W-by-B Data matrix where H and W are the image height and width, respectively, as specified in the ROIPosition property, and B is the number of color bands, as specified in the property.

  • Page 318

    propinfo Purpose Property characteristics for image acquisition objects Syntax out = propinfo(obj) out = propinfo(obj,PropertyName) Description returns the structure whose field names out = propinfo(obj) are the names of all the properties supported by must be a 1-by-1 image acquisition object. The value of each field is a structure containing the fields shown below.

  • Page 319

    propinfo array of strings, returns a structure for each property, stored propinfo in a cell array. Examples Create the video input object vid = videoinput('winvideo',1); Capture all property information for all properties. out = propinfo(vid); Access property information for a particular property. out1 = propinfo(vid,'LoggingMode');...

  • Page 320

    MATLAB workspace are saved. Note that any data associated with the image acquisition object is not stored in the MAT-file. To save the data, bring it into the MATLAB workspace (using the function), and then save the variable getdata to the MAT-file.

  • Page 321

    Purpose Configure or display image acquisition object properties Syntax set(obj) prop_struct = set(obj) set(obj,PropertyName) prop_cell = set(obj,PropertyName) set(obj,PropertyName,PropertyValue,...) set(obj,S) set(obj,PN,PV) Description displays property names and any enumerated values for all set(obj) configurable properties of image acquisition object must be a single image acquisition object. returns the property names and any prop_struct = set(obj) enumerated values for all configurable properties of image acquisition...

  • Page 322

    objects, in which case configures the property values for all the image acquisition objects specified. configures the properties of with the values specified in set(obj,S) , where is a structure whose field names are object property names. configures the properties specified in the cell array of set(obj,PN,PV) strings, , to the corresponding values in the cell array...

  • Page 323

    start Purpose Obtain exclusive use of image acquisition device Syntax start(obj) Description obtains exclusive use of the image acquisition device start(obj) associated with the video input object and locks the device’s configuration. Starting an object is a necessary first step to acquire image data, but it does not control when data is logged.

  • Page 324

    start An image acquisition object stops running when one of the following conditions is met: • The function is issued. stop • The requested number of frames is acquired. This occurs when FramesAcquired = FramesPerTrigger * (TriggerRepeat + 1) where , and FramesAcquired FramesPerTrigger...

  • Page 325

    stop Purpose Stop video input object Syntax stop(obj) Description halts an acquisition associated with the video input object stop(obj) can be either a single video input object or an array of video input objects. function stop • Sets the object’s property to Running 'Off'...

  • Page 326

    stoppreview Purpose Stop previewing video data Syntax stoppreview(obj) Description stops the previewing of video data from image stoppreview(obj) acquisition object To restart previewing, call again. preview Examples Create a video input object and open a Video Preview window. vid = videoinput('winvideo',1); preview(vid) Stop previewing video data.

  • Page 327

    trigger Purpose Initiate data logging Syntax trigger(obj) Description initiates data logging for the video input object trigger(obj) can be either a single video input object or an array of video input objects. function trigger • Executes the object’s callback TriggerFcn •...

  • Page 328

    , and values, use TriggerType TriggerCondition TriggerSource triggerinfo(obj) returns a MATLAB structure config = triggerconfig(obj) config containing the object’s current trigger configuration. must be a 1-by-1 video input object. The field names of config TriggerType , and .

  • Page 329

    , a MATLAB structure with field names config , and , each containing TriggerType TriggerCondition TriggerSource the desired property value. Examples Example 1 Construct a video input object. vid = videoinput('winvideo', 1); Configure trigger properties for the object.

  • Page 330

    triggerconfig delete(vid); See Also imaqhelp trigger triggerinfo videoinput 12-58...

  • Page 331

    , an array of MATLAB config = triggerinfo(...) config structures, containing all the valid trigger configurations for the video input object . Each structure in the array contains these fields:...

  • Page 332

    triggerinfo Get information about the available trigger configurations for this object. config = triggerinfo(vid) config = 1x2 struct array with fields: TriggerType TriggerCondition TriggerSource View one of the trigger configurations returned by triggerinfo config(1) ans = TriggerType: 'immediate' TriggerCondition: 'none' TriggerSource: 'none' See Also imaqhelp...

  • Page 333

    ,V1,...) Description constructs the video input object obj = videoinput(adaptorname) . A video input object represents the connection between MATLAB and a particular image acquisition device. is a text string adaptorname that specifies the name of the adaptor used to communicate with the device.

  • Page 334

    videoinput The property name and property value pairs can be in any format supported by the function, i.e., parameter/value string pairs, structures, or parameter/value cell array pairs. To view a complete listing of video input object functions and properties, use the function.

  • Page 335

    videoinput See Also delete imaqfind isvalid preview 12-63...

  • Page 336

    Purpose Wait until image acquisition object stops running or logging Syntax wait(obj) wait(obj,waittime) wait(obj,waittime,state) Description blocks the MATLAB command line until the video input wait(obj) object stops running ( can be either a single Running 'off' video input object or an array of video input objects. When...

  • Page 337

    The example calls the function after calling the function. Notice how wait start wait blocks the MATLAB command line until the acquisition is complete. start(vid), wait(vid); See Also imaqhelp start stop trigger...

  • Page 338

    wait 12-66...

  • Page 339: Video Input Objects

    Property Reference This chapter contains brief descriptions of all the properties of the video input object and the properties of the video source object that are common to all video source objects. Video source objects can also support device-specific properties that vary depending on the image acquisition hardware. To get help on these device-specific properties, use the function, specifying imaqhelp...

  • Page 340: General, Callback, Triggering, Acquisition Source

    General Specify sensor alignment for Bayer BayerSensorAlignment demosaicing Identify image acquisition device DeviceID represented by video input object Specify MATLAB AVI file object DiskLogger used to log data Specify number of frames written to DiskLoggerFrameCount disk Store information about events...

  • Page 341

    Indicate number of color bands in NumberOfBands data to be acquired Indicate whether object is currently Previewing previewing data in separate window Specify color space used in MATLAB ReturnedColorSpace Specify region-of-interest (ROI) ROIPosition window Indicate whether video input object Running...

  • Page 342

    Property Reference Specify number of frames that must FramesAcquiredFcnCount be acquired before frames acquired event is generated Specify MATLAB file executed when StartFcn start event occurs Specify MATLAB file executed when StopFcn stop event occurs Specify MATLAB file callback TimerFcn...

  • Page 343: Video Source Objects

    Video Input Objects Acquisition Source Specify name of currently selected SelectedSourceName video source Indicate video source objects Source associated with video input object 13-5...

  • Page 344

    Property Reference Video Source Objects Video input objects create one or more video source objects that represent the image acquisition data sources. The following table lists the properties common to all video source objects. Note A video source object can support additional, device-specific properties. These properties vary, depending on the image acquisition hardware.

  • Page 345

    Properties — Alphabetical List...

  • Page 346

    BayerSensorAlignment Purpose Specify sensor alignment for Bayer demosaicing Description If the property is set to , then the Image ReturnedColorSpace 'bayer' Acquisition Toolbox software will demosaic Bayer patterns returned by the hardware. This color space setting will interpolate Bayer pattern encoded images into standard RGB images.

  • Page 347

    BayerSensorAlignment The value of this property is only used if the ReturnedColorSpace property is set to 'bayer' Characteristics Access Read/write Data type String Values [ {'grbg'} | 'gbrg' | 'rggb'| 'bggr'] See Also Functions getdata getsnapshot peekdata videoinput Properties ReturnedColorSpace VideoFormat 14-3...

  • Page 348

    DeviceID Purpose Identify image acquisition device represented by video input object Description property identifies the device represented by the video DeviceID input object. A device ID is a number, assigned by an adaptor, that uniquely identifies an image acquisition device. The adaptor assigns the first device it detects the identifier , the second device it detects the identifier...

  • Page 349

    DeviceID Use the function again, specifying the name of the adaptor, imaqhwinfo to find out how many devices are available through that adaptor. The function returns the device IDs for all the devices in the imaqhwinfo field. DeviceIds info = imaqhwinfo('winvideo') info = AdaptorDllName: [1x73 char] AdaptorDllVersion: '2.0 (R2006a+)'...

  • Page 350

    LoggingMode 'disk' 'disk&memory' A MATLAB AVI file object specifies the name and other characteristics of an AVI file. For example, you can use AVI file object properties to specify the codec used for data compression and the desired quality of the output.

  • Page 351

    DiskLogger Examples Create and configure an AVI file object. file = avifile('logfile.avi'); file.Quality = 50; Create and configure a video input object. vid = videoinput('winvideo', 1); vid.LoggingMode = 'disk&memory'; vid.DiskLogger = file; Start logging data to disk. start(vid) To ensure that the logged data is written to the disk file, close the AVI file.

  • Page 352

    DiskLoggerFrameCount Purpose Specify number of frames written to disk Description property indicates the current number of DiskLoggerFrameCount frames written to disk by the . This value is only updated DiskLogger when the property is set to LoggingMode 'disk' 'disk&memory' After are off, it is possible that the Logging Running...

  • Page 353

    ErrorFcn Purpose Specify callback function to execute when run-time error occurs Description property specifies the function to execute when an error ErrorFcn event occurs. A run-time error event is generated immediately after a run-time error occurs. Run-time errors include hardware errors and timeouts. Run-time errors do not include configuration errors such as setting an invalid property value.

  • Page 354

    EventLog Purpose Store information about events Description property is an array of structures that stores information EventLog about events. Each structure in the array represents one event. Events are recorded in the order in which they occur. The first EventLog structure reflects the first event recorded, the second EventLog structure reflects the second event recorded, and so on.

  • Page 355

    EventLog Characteristics Access Read only Data type Structure array Values Default is empty structure array. Examples Create a video input object. vid = videoinput('winvideo'); Start the object. start(vid) View the event log to see which events occurred. elog = vid.EventLog; {elog.Type} ans = 'Start'...

  • Page 356

    FrameGrabInterval Purpose Specify how often to acquire frame from video stream Description property specifies how often the video input FrameGrabInterval object acquires a frame from the video stream. By default, objects acquire every frame in the video stream, but you can use this property to specify other acquisition intervals.

  • Page 357

    FrameGrabInterval Characteristics Access Read only while running Data type double Values Any positive integer. The default value is (acquire every frame). See Also Functions videoinput Properties SelectedSourceName 14-13...

  • Page 358

    FramesAcquired Purpose Indicate total number of frames acquired Description property indicates the total number of frames FramesAcquired that the object has acquired, regardless of how many frames have been extracted from the memory buffer. The video input object continuously updates the value of the property as it acquires frames.

  • Page 359

    A frames acquired event is generated immediately after the number of frames specified by the property is acquired FramesAcquiredFcnCount from the selected video source. This event executes the MATLAB file specified for FramesAcquiredFcn Use the callback if you must access each frame FramesAcquiredFcn that is acquired.

  • Page 360

    FramesAcquiredFcnCount Purpose Specify number of frames that must be acquired before frames acquired event is generated Description property specifies the number of frames FramesAcquiredFcnCount to acquire from the selected video source before a frames acquired event is generated. The object generates a frames acquired event immediately after the number of frames specified by is acquired FramesAcquiredFcnCount...

  • Page 361

    FramesAvailable appropriate number of frames. You use the function to extract getdata data and move it into the MATLAB workspace. Note When you issue a command, the video input object resets start the value of the property to...

  • Page 362

    FramesPerTrigger Purpose Specify number of frames to acquire per trigger using selected video source Description property specifies the number of frames the FramesPerTrigger video input object acquires each time it executes a trigger using the selected video source. When the value of the property is set to , the FramesPerTrigger...

  • Page 363

    Record absolute time of first trigger Description property records the absolute time of the first InitialTriggerTime trigger. The absolute time is recorded as a MATLAB clock vector. For all trigger types, records the time when the InitialTriggerTime property is set to...

  • Page 364

    InitialTriggerTime sprintf('%d:%d:%d', t(4),t(5),t(6)) ans = 13:26:20 See Also Functions clock getdata Properties EventLog Logging TriggerType 14-20...

  • Page 365

    Logging Purpose Indicate whether object is currently logging data Description property indicates whether the video input object is Logging currently logging data. When a trigger occurs, the object sets the property to Logging 'on' logs data to memory, a disk file, or both, depending on the value of property.

  • Page 366

    LoggingMode Purpose Specify destination for acquired data Description property specifies where you want the video input LoggingMode object to store the acquired data. You can specify any of the following values: Value Description Log acquired data to a disk file. 'disk' Log acquired data to both a disk file and to a 'disk&memory'...

  • Page 367

    LoggingMode Properties DiskLogger Logging 14-23...

  • Page 368

    Name Purpose Specify name of image acquisition object Description property specifies a descriptive name for the image acquisition Name object. Characteristics Access Read/write Data type String Values Any text string. The toolbox creates the default name by combining the values of the VideoFormat DeviceID properties with the adaptor name in this format:...

  • Page 369

    NumberOfBands Purpose Indicate number of color bands in data to be acquired Description property indicates the number of color bands in the NumberOfBands data to be acquired. The toolbox defines band as the third dimension in a 3-D array, as shown in this figure. The value of the property indicates the number of color NumberOfBands...

  • Page 370

    NumberOfBands If you retrieve the value of the property, you can see that VideoFormat the video data is in RGB format. get(vid,'VideoFormat') ans = RGB24_320x240 See Also Functions getdata getsnapshot peekdata 14-26...

  • Page 371

    Parent Purpose Identify video input object that is parent of video source object Description property identifies the video input object that is the parent Parent of a video source object. The parent of a video source object is defined as the video input object owning the video source object.

  • Page 372

    Previewing Purpose Indicate whether object is currently previewing data in separate window Description property indicates whether the object is currently Previewing previewing data in a separate window. The object sets the property to when you call the Previewing 'on' function. preview The object sets the property to...

  • Page 373

    Specify color space used in MATLAB Description property specifies the color space you ReturnedColorSpace want the toolbox to use when it returns image data to the MATLAB workspace. This is only relevant when you are accessing acquired image data with the , and functions.

  • Page 374

    ROIPosition Purpose Specify region-of-interest (ROI) window Description property specifies the region-of-interest acquisition ROIPosition window. The ROI window defines the actual size of the frame logged by the toolbox, measured with respect to the top left corner of an image frame. is specified as a 1-by-4 element vector ROIPosition [XOffset YOffset Width Height]...

  • Page 375

    ROIPosition Note The does not include both end points as well as the width Width between the pixels. It includes one end point, plus the width between pixels. For example, if you want to capture an ROI of pixels 20 through 30, including both end pixels 20 and 30, set an and a XOffset...

  • Page 376

    Running Purpose Indicate whether video input object is ready to acquire data Description property indicates if the video input object is ready to Running acquire data. Along with the property, reflects the state of a video Logging Running input object. The property indicates that the object is ready Running to acquire data, while the...

  • Page 377

    Selected Purpose Indicate whether video source object will be used for acquisition Description property indicates if the video source object will be used Selected for acquisition. You select a video source object by specifying its name as the value of the video input object’s property.

  • Page 378

    Selected src = getselectedsource(vid); View its properties. Name Selected src.SourceName ans = input1 src.Selected ans = See Also Functions getselectedsource Properties SelectedSourceName 14-34...

  • Page 379

    SelectedSourceName Purpose Specify name of currently selected video source Description property specifies the name of the video SelectedSourceName source object from which the video input object acquires data. The name is specified as a string. By default, the video input object selects the first available video source object stored in the property.

  • Page 380

    Source Purpose Indicate video source objects associated with video input object Description property is a vector of video source objects that represent Source the physical data sources connected to a device. When a video input object is created, the toolbox creates a vector of video source objects associated with the video input object.

  • Page 381

    Source Examples Create an image acquisition object. vid = videoinput('matrox'); To access all the video source objects associated with a video input object, use the property of the video input object. (To view only Source the currently selected video source object, use the getselectedsource function.) sources = vid.Source;...

  • Page 382

    SourceName Purpose Indicate name of video source object Description property indicates the name of a video source object. SourceName is one of the values in the video input object’s SourceName property. SelectedSourceName Characteristics Access Read only Data type String Values Defined at object creation time See Also Functions...

  • Page 383

    StartFcn Purpose Specify MATLAB file executed when start event occurs Description property specifies the MATLAB file function to execute StartFcn when a start event occurs. A start event occurs immediately after you issue the command. start callback executes synchronously. The toolbox does not StartFcn set the object’s...

  • Page 384

    StopFcn Purpose Specify MATLAB file executed when stop event occurs Description property specifies the MATLAB file function to execute StopFcn when a stop event occurs. A stop event occurs immediately after you issue the command. stop callback executes synchronously. Under most...

  • Page 385

    Purpose Specify descriptive text to associate with image acquisition object Description property specifies any descriptive text that you want to associate with an image acquisition object. property can be useful when you are constructing programs that would otherwise need to define the image acquisition object as a global variable, or pass the object as an argument between callback routines.

  • Page 386

    MATLAB command line. A timeout is one of the conditions for stopping an acquisition. When a timeout occurs, and the object is running, the MATLAB file function specified by is called.

  • Page 387

    TimerFcn Purpose Specify MATLAB file callback function to execute when timer event occurs Description property specifies the MATLAB file callback function to TimerFcn execute when a timer event occurs. A timer event occurs when the time period specified by the property expires.

  • Page 388

    TimerPeriod Purpose Specify number of seconds between timer events Description property specifies the amount of time, in seconds, TimerPeriod that must pass before a timer event is triggered. The toolbox measures time relative to when the object is started with function.

  • Page 389

    TriggerCondition Purpose Indicate required condition before trigger event occurs Description property indicates the condition that must be TriggerCondition met, via the , before a trigger event occurs. The trigger TriggerSource conditions that you can specify depend on the value of the TriggerType property.

  • Page 390

    TriggerCondition Properties TriggerSource TriggerType 14-46...

  • Page 391

    TriggerFcn Purpose Specify MATLAB file callback function to execute when trigger event occurs Description property specifies the MATLAB file callback function TriggerFcn to execute when a trigger event occurs. The toolbox generates a trigger event when a trigger is executed based on the configured TriggerType and data logging is initiated.

  • Page 392

    TriggerFrameDelay Purpose Specify number of frames to skip before acquiring frames after trigger occurs Description property specifies the number of frames to TriggerFrameDelay skip before acquiring frames after a trigger occurs. The object waits the specified number of frames after the trigger before starting to log frames.

  • Page 393

    TriggerFrameDelay Properties FramesPerTrigger 14-49...

  • Page 394

    TriggerRepeat Purpose Specify number of additional times to execute trigger Description property specifies the number of additional times TriggerRepeat you want the object to execute a trigger. This table describes the behavior for several typical values. TriggerRepeat Value Behavior (default) Execute the trigger once when the trigger condition is met.

  • Page 395

    TriggersExecuted Purpose Indicate total number of executed triggers Description property indicates the total number of triggers TriggersExecuted that the video input object has executed. Characteristics Access Read only Data type double Values Any nonnegative integer. The default value is (zero). See Also Functions trigger...

  • Page 396

    TriggerSource Purpose Indicate hardware source to monitor for trigger conditions Description property indicates the hardware source the image TriggerSource acquisition object monitors for trigger conditions. When the condition specified in the property is met, the object executes TriggerCondition the trigger and starts acquiring data. You use the function to specify this value.

  • Page 397

    TriggerType Purpose Indicate type of trigger used by video input object Description property indicates the type of trigger used by the TriggerType video input object. Triggers initiate data acquisition. You use the function to specify one of the following triggerconfig values for this property.

  • Page 398

    TriggerType Properties TriggerCondition TriggerSource 14-54...

  • Page 399

    Type Purpose Identify type of image acquisition object Description property identifies the type of image acquisition object. An Type image acquisition object can be either one of two types: • Video input object • Video source object Characteristics Access Read only Data type String Values...

  • Page 400

    Note The object does not use the data in directly. However, UserData you can access the data by using the function or by referencing the property as you would a field in a MATLAB structure. Characteristics Read/Write Access Data type...

  • Page 401

    VideoFormat Purpose Specify video format or name of device configuration file Description property specifies the video format used by the VideoFormat image acquisition device or the name of a device configuration file, depending on which you specified when you created the object using function.

  • Page 402

    VideoFormat AdaptorDllName: [1x73 char] AdaptorDllVersion: '2.1 (R2007a)' AdaptorName: 'winvideo' DeviceIDs: {[1]} DeviceInfo: [1x1 struct] info.DeviceInfo ans = DefaultFormat: 'RGB555_128x96' DeviceFileSupported: 0 DeviceName: 'IBM PC Camera' DeviceID: 1 ObjectConstructor: 'videoinput('winvideo', 1)' SupportedFormats: {1x34 cell} See Also Functions imaqhwinfo videoinput 14-58...

  • Page 403

    VideoResolution Purpose Indicate width and height of incoming video stream Description property is a two-element vector indicating VideoResolution the width and height of the frames in the incoming video stream. is specified as VideoResolution [Width Height] Width is measured in pixels and height is measured in rows. Note You specify the video resolution when you create the video input object, by passing in the video format argument to the videoinput...

  • Page 404

    VideoResolution 14-60...

  • Page 405

    Block Reference...

  • Page 406

    From Video Device Purpose Acquire live image data from image acquisition device Library Image Acquisition Toolbox Description The From Video Device block lets you acquire image and video data streams from image acquisition devices, such as cameras and frame grabbers, in order to bring the image data into a Simulink model. The block also lets you configure and preview the acquisition directly from Simulink.

  • Page 407

    From Video Device For more information on these features, see the Simulink documentation. Note The From Video Device block is not supported for use with the Real-Time Workshop ® software. Note For an in-depth example of using this block, see Using the From Video Device Block in Simulink.

  • Page 408

    From Video Device 15-4...

  • Page 409

    From Video Device The second diagram illustrates the options that may appear if your device supports using either one output port or multiple output ports for the color bands (the Ports mode option). Ports mode is visible if the selected device and format settings can output color data. The following fields appear in the Source Block Parameters dialog box.

  • Page 410

    From Video Device by the Image Acquisition Toolbox software are supported by the block. Video format Shows the video formats supported by the selected device. This list varies with each device. If your device supports the use of camera files, will be one of the choices in the list.

  • Page 411

    From Video Device ROI position Use this field to input a row vector that specifies the region of acquisition in the video image. The format is [row, column, height, width]. The default values for row and column are 0. The default values for height and width are set to the maximum allowable value, indicated by the video format’s resolution.

  • Page 412

    Data type The image data type when the block outputs frames. This data type indicates how image frames are output from the block to Simulink. It supports all MATLAB data types and is the single default.

  • Page 413

    Video Input (Obsolete) Purpose Connect to image acquisition device Library Image Acquisition Toolbox Description The Video Input block is obsolete. It may be removed in a future version of the Image Acquisition Toolbox block library. Use the replacement block From Video Device. The Video Input block opens, initializes, configures, and controls an acquisition device.

  • Page 414

    Video Input (Obsolete) Device name The image acquisition device to which you want to connect. The items in the list vary, depending on which devices you have connected to your system. Input video format The video formats supported by the device. This list varies with each device.

  • Page 415

    Examples Use this list to find examples in the documentation.

  • Page 416: Fundamentals, Previewing, Image Acquisition Tool (gui)

    Examples Fundamentals “Basic Image Acquisition Procedure” on page 1-6 “Determining the Device Adaptor Name” on page 4-2 “Determining the Device ID” on page 4-3 “Getting More Information About a Particular Device” on page 4-4 “Determining Supported Video Formats” on page 4-5 “Creating a Video Input Object”...

  • Page 417: Acquiring Image Data, Working With Acquired Data, Events And Callbacks

    Acquiring Image Data Acquiring Image Data “Specifying Trigger Type, Source, and Condition” on page 5-5 “Example: Using an Immediate Trigger” on page 5-9 “Example: Using a Manual Trigger” on page 5-12 “Example: Using a Hardware Trigger” on page 5-14 “Example: Acquiring 100 Frames” on page 5-28 “Determining How Many Frames Are Available”...

  • Page 418

    Examples...

  • Page 419

    Index Index acquiring data 3-28 Bayer demosaicing 14-2 acquiring images property 14-2 BayerSensorAlignment basic procedure 1-6 block library connecting to devices 4-1 using 8-1 overview 5-2 blurry frames 3-31 specifying a delay 5-33 specifying the amount 5-26 specifying the frame grab interval 5-27 callback functions specifying the timeout value 14-42 as text string 7-15...

  • Page 420

    Index troubleshooting 10-3 digital video DALSA Coreco Sapera devices support for 2-4 determining driver version 10-6 digitizer configuration format (DCF) files 4-13 troubleshooting 10-5 DirectX drivers dark frames 3-31 finding version 10-23 Data Translation devices disk files troubleshooting 10-7 logging image data to 5-45 data type used by device Disk Logging 3-14 finding 4-15...

  • Page 421

    Index Firewire (IEEE 1394) Digital Camera (DCAM) using 5-28 specification freeing memory support for 2-4 used for image frames 5-42 function 12-7 From Video Device block 15-2 flushdata using 5-42 using 8-1 frame delay specifying 14-48 frame grabbers 2-2 function 12-8 troubleshooting 10-2 using 4-17 troubleshooting DALSA Coreco IFC...

  • Page 422

    Index specifying a delay 14-48 Logging 3-13 specifying the timeout value 14-42 manual triggering 3-16 time-based acquisition 6-5 Memory Logging 3-14 using timers with 14-43 opening 3-2 image acquisition devices 2-2 Preview window 3-25 adaptors 4-2 previewing data 3-27 adding support for 9-1 Region of Interest (ROI) 3-18 connecting to 4-1 saving configurations 3-35...

  • Page 423

    Index troubleshooting 10-2 manual triggers function defined 5-8 imaqcallback using default callback function 7-2 example 5-12 function 12-16 Matrox devices imaqfind using 4-27 determining driver version 10-17 function 12-18 troubleshooting 10-16 imaqhelp getting property information 4-20 Matrox MIL Configuration utility function 12-20 using 10-17 imaqhwinfo...

  • Page 424

    Index using 2-10 property 14-35 SelectedSourceName Preview window 3-25 selecting a device in the GUI 3-5 previewing function 12-49 closing the preview window 2-12 using 4-20 creating custom preview GUIs 2-12 property 14-36 Source opening the Video Preview window 2-10 property 14-38 SourceName performing custom processing 2-14...

  • Page 425

    Index timers property 14-53 TriggerType specifying period of 14-44 configuring 5-6 specifying with image acquisition 14-43 types of triggers 5-8 timing of acquisition troubleshooting retrieving 6-20 image acquisition hardware 10-2 trigger events troubleshooting bad images 3-31 definition 7-6 TV tuner boards information returned 7-8 support for 2-4 specifying callback function 14-47...

  • Page 426

    Index stopping 4-23 function 12-61 videoinput viewing current state 4-10 using 4-8 Video Preview window property 14-59 VideoResolution closing 2-12 viewing images 6-19 opening 2-10 stopping the preview video stream 2-11 troubleshooting 10-25 function 12-64 video source objects wait using 5-36 array of 14-36 waiting for an acquisition to complete 5-36 currently selected source 14-33...

Comments to this Manuals

Symbols: 0

Latest comments:

×

Select the desired size and copy embed code

Copy your embed code and put on your site: