Image Acquisition Toolbox™ User's Guide R2015a
How to Contact MathWorks Latest news: www.mathworks.com Sales and services: www.mathworks.com/sales_and_services User community: www.mathworks.com/matlabcentral Technical support: www.mathworks.com/support/contact_us Phone: 508-647-7000 The MathWorks, Inc. 3 Apple Hill Drive Natick, MA 01760-2098 Image Acquisition Toolbox™ User's Guide © COPYRIGHT 2003–2015 by The MathWorks, Inc. The software described in this document is furnished under a license agreement.
Revision History March 2003 September 2003 June 2004 July 2004 October 2004 March 2005 March 2005 August 2005 September 2005 March 2006 September 2006 March 2007 September 2007 March 2008 October 2008 March 2009 September 2009 March 2010 September 2010 April 2011 September 2011 March 2012 September 2012 March 2013 September 2013 March 2014 October 2014 March 2015 First printing Online only Online only Online only Online only Online only Second printing Third printing Online only Fourth printing Online onl
Contents 1 2 Getting Started Image Acquisition Toolbox Product Description . . . . . . . . . . Key Features . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2 1-2 Product Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Installation and Configuration Notes . . . . . . . . . . . . . . . . . .
3 vi Contents Toolbox Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . The Image Processing Toolbox Software Required to Use the Image Acquisition Toolbox Software . . . . . . . . . . . . . . . . . The Image Acquisition Tool (GUI) . . . . . . . . . . . . . . . . . . . . . Supported Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2-3 Setting Up Image Acquisition Hardware . . . . . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . .
4 Setting Device-Specific Parameters . . . . . . . . . . . . . . . . . . . Logging Your Data . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting Up Triggering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Setting a Region of Interest . . . . . . . . . . . . . . . . . . . . . . . . Restoring Default Parameters . . . . . . . . . . . . . . . . . . . . . . . 3-13 3-16 3-19 3-22 3-27 Previewing and Acquiring Data in Image Acquisition Tool The Preview Window . . . . . . . . . . .
5 6 Connecting to Hardware Getting Hardware Information . . . . . . . . . . . . . . . . . . . . . . . . Getting Hardware Information . . . . . . . . . . . . . . . . . . . . . . . Determining the Device Adaptor Name . . . . . . . . . . . . . . . . . Determining the Device ID . . . . . . . . . . . . . . . . . . . . . . . . . . Determining Supported Video Formats . . . . . . . . . . . . . . . . . 5-2 5-2 5-2 5-3 5-5 Creating Image Acquisition Objects . . . . . . . . . . . . . . . . . . . .
Data Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6-3 6-3 6-4 Setting the Values of Trigger Properties . . . . . . . . . . . . . . . . About Trigger Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . Specifying Trigger Type, Source, and Condition . . . . . . . . . .
7 8 x Contents Working with Acquired Image Data Image Acquisition Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 7-2 Bringing Image Data into the MATLAB Workspace . . . . . . . Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Moving Multiple Frames into the Workspace . . . . . . . . . . . . Viewing Frames in the Memory Buffer . . . . . . . . . . . . . . . . . Bringing a Single Frame into the Workspace . . . . . . . . . . .
Creating and Executing Callback Functions . . . . . . . . . . . . Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Creating Callback Functions . . . . . . . . . . . . . . . . . . . . . . . . Specifying Callback Functions . . . . . . . . . . . . . . . . . . . . . . . Viewing a Sample Frame . . . . . . . . . . . . . . . . . . . . . . . . . . Monitoring Memory Usage . . . . . . . . . . . . . . . . . . . . . . . . .
Linux Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Mac Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11 12 xii Contents 10-5 10-6 Software Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-11 Setting Preferences . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10-13 Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
14 Acquiring from Color and Depth Devices Simultaneously 12-23 Using Skeleton Viewer for Kinect Skeletal Data . . . . . . . . 12-24 Installing the Kinect for Windows Sensor Support Package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 12-27 Using the Matrox Interface Matrox Acquisition – matroxcam Object vs videoinput Object . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13-2 Connect to Matrox Frame Grabbers . . . . . . .
Usage Rules for System Objects in Generated MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Limitations on Using System Objects in Generated MATLAB Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15 xiv Contents 14-15 Adding Support for Additional Hardware Support for Additional Hardware . . . . . . . . . . . . . . . . . . . . . 16 14-15 15-2 Troubleshooting Troubleshooting Overview . . . . . . . . . . . . . . . . . . . .
QImaging Hardware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Troubleshooting QImaging Devices . . . . . . . . . . . . . . . . . . Determining the Driver Version for QImaging Devices . . . 16-18 16-18 16-19 National Instruments Hardware . . . . . . . . . . . . . . . . . . . . . Troubleshooting National Instruments Devices . . . . . . . . . Determining the Driver Version for National Instruments Devices . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
17 18 19 xvi Contents Functions — Alphabetical List Properties — Alphabetical List Block Reference
1 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.
1 Getting Started Image Acquisition Toolbox Product Description Acquire images and video from industry-standard hardware Image Acquisition Toolbox enables you to acquire images and video from cameras and frame grabbers directly into MATLAB® and Simulink®. You can detect hardware automatically, and configure hardware properties. Advanced workflows let you trigger acquisition while processing in-the-loop, perform background acquisition, and synchronize sampling across several multimodal devices.
Product Overview Product Overview In this section... “Introduction” on page 1-3 “Installation and Configuration Notes” on page 1-4 “The Image Processing Toolbox Software Required to Use the Image Acquisition Toolbox Software” on page 1-4 “Related Products” on page 1-5 “Supported Hardware” on page 1-5 Introduction The Image Acquisition Toolbox software is a collection of functions that extend the capability of the MATLAB numeric computing environment.
1 Getting Started Installation and Configuration Notes To determine if the Image Acquisition Toolbox software is installed on your system, type this command at the MATLAB prompt: ver When you enter this command, MATLAB displays information about the version of MATLAB you are running, including a list of all toolboxes installed on your system and their version numbers. For information about installing the toolbox, see the MATLAB Installation Guide.
Product Overview If you have any questions, please contact MathWorks customer service. Related Products 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.
1 Getting Started Image Acquisition Tool (GUI) The functionality of the Image Acquisition Toolbox software is available in a desktop application. You connect directly to your hardware in the tool and can set acquisition parameters, and preview and acquire image data. You can log the data to MATLAB in several formats, and also generate an AVI file, right from the tool. To open the tool, type imaqtool at the MATLAB command line, or select Image Acquisition on the Apps tab in MATLAB.
Getting Started Doing Image Acquisition Programmatically Getting Started Doing Image Acquisition Programmatically In this section...
1 Getting Started Note: With previous versions of the Image Acquisition Toolbox, the files for all of the adaptors were included in your installation. Starting with version R2014a, each adaptor is available separately through the Support Package Installer. In order to use the Image Acquisition Toolbox, you must install the adaptor that your camera uses. See “Image Acquisition Support Packages for Hardware Adaptors” on page 4-2 for information about installing the adaptors.
Getting Started Doing Image Acquisition Programmatically Step 1: Install Your Image Acquisition Device Follow the setup instructions that come with your image acquisition device. Setup typically involves: • Installing the frame grabber board in your computer. • Installing any software drivers required by the device. These are supplied by the device vendor. • Connecting a camera to a connector on the frame grabber board.
1 Getting Started Device Information Description communicate. See “Determining the Device ID” on page 1-10 for more information. Note: Specifying the device ID is optional; the toolbox uses the first available device ID as the default. Video format The video format specifies the image resolution (width and height) and other aspects of the video stream. Image acquisition devices typically support multiple video formats. See “Determining the Supported Video Formats” on page 1-11 for more information.
Getting Started Doing Image Acquisition Programmatically in “Determining the Adaptor Name” on page 1-10.) In the data returned, the DeviceIDs field is a cell array containing the device IDs of all the devices accessible through the specified adaptor. Note This example uses the DCAM adaptor. You should substitute the name of the adaptor you would like to use. info = imaqhwinfo('dcam') info = AdaptorDllName: AdaptorDllVersion: AdaptorName: DeviceIDs: DeviceInfo: [1x77 char] '2.
1 Getting Started SupportedFormats: {'F7_Y8_1024x768' 'Y8_1024x768'} 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. For more information about image acquisition objects, see “Creating Image Acquisition Objects” on page 5-8.
Getting Started Doing Image Acquisition Programmatically vid Summary of Video Input Object Using 'XCD-X700 Acquisition Source(s): Acquisition Parameters: Trigger Parameters: Status: 1.05'. input1 is available. 'input1' is the current selected source. 10 frames per trigger using the selected source. 'Y8_1024x768' video data to be logged upon START. Grabbing first of every 1 frame(s). Log data to 'memory' on trigger. 1 'immediate' trigger(s) on START. Waiting for START. 0 frames acquired since starting.
1 Getting Started Video Preview Window To close the Video Preview window, click the Close button in the title bar or use the closepreview function, specifying the video input object as an argument. closepreview(vid) Calling closepreview without any arguments closes all open Video Preview windows.
Getting Started Doing Image Acquisition Programmatically • Describes the types of image acquisition objects used by the toolbox • Describes how to view all the properties supported by these objects, with their current values • Describes how to set the values of object properties Types of Image Acquisition Objects The toolbox uses two types of objects to represent the connection with an image acquisition device: • Video input objects • Video source objects A video input object represents the connection betw
1 Getting Started FramesAcquired = 0 FramesAvailable = 0 FramesPerTrigger = 10 Logging = off LoggingMode = memory Name = Y8_1024x768-dcam-1 NumberOfBands = 1 Previewing = on ReturnedColorSpace = grayscale ROIPosition = [0 0 1024 768] Running = off Tag = Timeout = 10 Type = videoinput UserData = [] VideoFormat = Y8_1024x768 VideoResolution = [1024 768] . . .
Getting Started Doing Image Acquisition Programmatically FrameRate = 15 Gain = 2048 Shutter = 2715 Setting Object Properties To set the value of a video input object property or a video source object property, you reference the object property as you would a field in a structure, using dot notation. Some properties are read only; you cannot set their values. These properties typically provide information about the state of the object. Other properties become read only when the object is running.
1 Getting Started • Starting the video input object — You start an object by calling the start function. Starting an object prepares the object for data acquisition. For example, starting an object locks the values of certain object properties (they become read only). Starting an object does not initiate the acquiring of image frames, however. The initiation of data logging depends on the execution of a trigger. The following example calls the start function to start the video input object.
Getting Started Doing Image Acquisition Programmatically a difference image, and then displays it. Pixels that have changed values in the acquired frames will have nonzero values in the difference image. The getdata function removes frames from the memory buffer when it brings them into the MATLAB workspace. It is important to move frames from the memory buffer into the MATLAB workspace in a timely manner.
1 Getting Started Figure Window Displayed by Example Image Data in the MATLAB Workspace In the example, the getdata function returns the image frames in the variable data as a 480-by-640-by-1-by-10 array of 8-bit data (uint8).
Getting Started Doing Image Acquisition Programmatically Step 7: Clean Up When you finish using your image acquisition objects, you can remove them from memory and clear the MATLAB workspace of the variables associated with these objects. delete(vid) clear close(gcf) For more information, see “Deleting Image Acquisition Objects” on page 5-25.
2 Introduction This chapter describes the Image Acquisition Toolbox software and its components.
2 Introduction Toolbox Components Overview In this section... “Introduction” on page 2-2 “Toolbox Components” on page 2-3 “The Image Processing Toolbox Software Required to Use the Image Acquisition Toolbox Software” on page 2-4 “The Image Acquisition Tool (GUI)” on page 2-5 “Supported Devices” on page 2-5 Introduction Image Acquisition Toolbox enables you to acquire images and video from cameras and frame grabbers directly into MATLAB and Simulink.
Toolbox Components Overview provides several ways to bring one or more frames of data into the workspace where you can manipulate it as you would any other multidimensional numeric array. “Bringing Image Data into the MATLAB Workspace” on page 7-3 describes this process. Finally, you can enhance your image acquisition application by using event callbacks. The toolbox has defined certain occurrences, such as the triggering of an acquisition, as events.
2 Introduction The Image Acquisition Toolbox Software Components The Image Processing Toolbox Software Required to Use the Image Acquisition Toolbox Software The Image Acquisition Toolbox product, including the Image Acquisition Tool, now requires you to have a license for the Image Processing Toolbox product starting in R2008b. If you already have the Image Processing Toolbox product, you do not need to do anything.
Toolbox Components Overview customers will need to purchase both products to use the Image Acquisition Toolbox product. If you have any questions, please contact MathWorks customer service. The Image Acquisition Tool (GUI) The functionality of the Image Acquisition Toolbox software is available in a desktop application. You connect directly to your hardware in the tool and can then set acquisition parameters, and preview and acquire image data.
2 Introduction Note: The toolbox supports only connections to IEEE 1394 (FireWire) DCAM-compliant devices using the Carnegie Mellon University DCAM driver. The toolbox is not compatible with any other vendor-supplied driver, even if the driver is DCAM compliant. You can add support for additional hardware by writing an adaptor. For more information, see “Support for Additional Hardware” on page 15-2.
Setting Up Image Acquisition Hardware Setting Up Image Acquisition Hardware In this section... “Introduction” on page 2-7 “Setting Up Frame Grabbers” on page 2-7 “Setting Up Generic Windows Video Acquisition Devices” on page 2-8 “Setting Up DCAM Devices” on page 2-8 “Resetting Your Image Acquisition Hardware” on page 2-8 “A Note About Frame Rates and Processing Speed” on page 2-8 Introduction To acquire image data, you must perform the setup required by your particular image acquisition device.
2 Introduction • Installing any software drivers required by the frame grabber. These are supplied by the device vendor.
Setting Up Image Acquisition Hardware 30 frames per second (30 Hz). The CCIR and PAL standards define a frame rate of 25 Hz. Nonstandard devices can be configured to operate at higher rates. Generic Windows image acquisition devices, such as webcams, might support many different frame rates. Depending on the device being used, the frame rate might be configurable using a devicespecific property of the image acquisition object.
2 Introduction Previewing Data In this section... “Introduction” on page 2-10 “Opening a Video Preview Window” on page 2-11 “Stopping the Preview Video Stream” on page 2-12 “Closing a Video Preview Window” on page 2-13 “Previewing Data in Custom GUIs” on page 2-13 “Performing Custom Processing of Previewed Data” on page 2-15 Introduction After you connect MATLAB to the image acquisition device you can view the live video stream using the Video Preview window.
Previewing Data Preview window was designed to only show 8-bit data, but many cameras return 10-, 12-, 14-, or 16-bit data. The Preview window display supports these higher bit-depth cameras. However, larger bit data is scaled to 8-bit for the purpose of displaying previewed data. If you need the full resolution of the data, use the getsnapshot or getdata functions. Opening a Video Preview Window To open a Video Preview window, use the preview function.
2 Introduction Note: The Image Acquisition Toolbox Preview window and the Preview window that is built into the Image Acquisition Tool support the display of up to 16-bit image data. The Preview window was designed to only show 8-bit data, but many cameras return 10-, 12-, 14-, or 16-bit data. The Preview window display supports these higher bit-depth cameras. However, larger bit data is scaled to 8-bit for the purpose of displaying previewed data.
Previewing Data The status displayed in the Video Preview window also changes to indicate that previewing has been stopped. vid = videoinput('winvideo'); preview(vid) stoppreview(vid) To restart the video stream in the Video Preview window, call preview again on the same video input object. preview(vid) Closing a Video Preview Window To close a particular Video Preview window, use the closepreview function, specifying the video input object as an argument.
2 Introduction The following example creates a figure window and then creates an image object in the figure, the same size as the video frames. The example then calls the preview function, specifying a handle to the image object. % Create a video input object. vid = videoinput('winvideo'); % Create a figure window. This example turns off the default % toolbar, menubar, and figure numbering. figure('Toolbar','none',... 'Menubar', 'none',... 'NumberTitle','Off',...
Previewing Data Custom Preview Performing Custom Processing of Previewed Data When you specify an image object to the preview function (see “Previewing Data in Custom GUIs” on page 2-13), you can optionally also specify a function that preview executes every time it receives an image frame. To use this capability, follow these steps: 1 Create the function you want executed for each image frame, called the update preview window function.
2 Introduction Creating the Update Preview Window Function When preview calls the update preview window function you specify, it passes your function the following arguments.
Previewing Data ht = getappdata(himage,'HandleToTimestampLabel'); % Set the value of the text label. ht.String = tstampstr; % Display image data. himage.CData = event.Data Specifying the Update Preview Function To use an update preview window function, store a function handle to your function in the 'UpdatePreviewWindowFcn' application-defined data of the image object.
2 Introduction 'Callback', 'stoppreview(vid)',... 'Units','normalized',... 'Position',[.17 0 .15 .07]); uicontrol('String', 'Close',... 'Callback', 'close(gcf)',... 'Units','normalized',... 'Position',[0.34 0 .15 .07]); % Create the text label for the timestamp hTextLabel = uicontrol('style','text','String','Timestamp', ... 'Units','normalized',... 'Position',[0.85 -.04 .15 .08]); % Create the image object in which you want to % display the video preview data. vidRes = vid.
Previewing Data Custom Preview GUI with Timestamp Text Label 2-19
3 Using the Image Acquisition Tool GUI • “The Image Acquisition Tool Desktop” on page 3-2 • “Getting Started with the Image Acquisition Tool” on page 3-5 • “Selecting Your Device in Image Acquisition Tool” on page 3-8 • “Setting Acquisition Parameters in Image Acquisition Tool” on page 3-11 • “Previewing and Acquiring Data in Image Acquisition Tool” on page 3-28 • “Exporting Data in the Image Acquisition Tool” on page 3-35 • “Saving Image Acquisition Tool Configurations” on page 3-39 • “Exporting Image Acqu
3 Using the Image Acquisition Tool GUI The Image Acquisition Tool Desktop In this section... “Opening the Tool” on page 3-2 “Parts of the Desktop” on page 3-2 Opening the Tool Image Acquisition Toolbox functionality is 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 a VideoWriter or AVI file, right from the tool.
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. Select the device format or camera file you want to use for the acquisition. When the format is selected, you can then set acquisition parameters and preview your data.
3 Using the Image Acquisition Tool GUI MATLAB Workspace, VideoWriter, or to tools provided by the Image Processing Toolbox software. See “Previewing and Acquiring Data in Image Acquisition Tool” on page 3-28 for more information about using the Preview window. • Acquisition Parameters – Use these tabs to set up general acquisition parameters, such as frames per trigger and color space, device-specific properties, logging options, triggering options, and region of interest.
Getting Started with the Image Acquisition Tool Getting Started with the Image Acquisition Tool This section describes an example of the basic work flow of using the Image Acquisition Tool to preview, acquire, and save image data. You don't need to do every step shown here, and you can change the order of some steps. For information on the parts of the Desktop GUI or how to open the Tool, see “The Image Acquisition Tool Desktop” on page 3-2.
3 Using the Image Acquisition Tool GUI and the Number of Triggers field on the Triggering tab. For example, if you set Frames Per Trigger to 4 and Number of Triggers to 2, the total number of frames acquired will be 8. If you just want a snapshot of one frame, leave the default settings of 1 in both of those fields. If you want a specific number of frames, use the fields to set it.
Getting Started with the Image Acquisition Tool You can export the data that has been acquired in memory to a MAT-file, the MATLAB Workspace, VideoWriter, or to the Image Tool, Image File, or Movie Player tools that are provided by the Image Processing Toolbox software using the Export Data button. For more information, see the “Exporting Data” section of the Desktop Help on the Preview Window in the Desktop Help pane in the tool.
3 Using the Image Acquisition Tool GUI Selecting Your Device in Image Acquisition Tool In this section... “Selecting a Device and Format” on page 3-8 “Adding New Hardware” on page 3-10 “Using a Camera File” on page 3-10 Selecting a Device and Format The Hardware Browser pane shows the image acquisition devices currently connected to your system. Each device is a separate node in the browser. All of the formats the device supports are listed under the device.
Selecting Your Device in Image Acquisition Tool 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.
3 Using the Image Acquisition Tool GUI Adding New Hardware When you open the Image Acquisition Tool, the Hardware Browser automatically shows the image acquisition devices supported by the toolbox that are currently connected to your system. If you plug a new device in while the Image Acquisition Tool is open, select Tools > Refresh Image Acquisition Hardware to display the new device in the Hardware Browser.
Setting Acquisition Parameters in Image Acquisition Tool Setting Acquisition Parameters in Image Acquisition Tool In this section...
3 Using the Image Acquisition Tool GUI Note: Once you have changed parameters of a device, you can restore the device's default parameters by selecting the device format in the Hardware Browser and right-clicking Clear Selected Hardware Configuration. Setting Frames Per Trigger The Frames Per Trigger field on the General tab is used to set the number of frames per trigger you want to acquire.
Setting Acquisition Parameters in Image Acquisition Tool Note that if you set Frames Per Trigger to infinite, you cannot set Number of Triggers on the Triggering tab. Note: Some devices need a few frames to warm up, or may always skip the first frame. If your device does that, change the number of frames accordingly to adjust for that. You can also adjust for camera warm-up by using manual triggering on the Triggering tab.
3 Using the Image Acquisition Tool GUI 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 input1, port1, or input0 by default. If your device supports multiple source names, they will appear in the drop-down list. Use the Properties area to view or edit properties: • If a property has an edit box or slider, that value is editable.
Setting Acquisition Parameters in Image Acquisition Tool To get help on any of the properties in the Device Properties tab, right-click a property and select What's This?. A Help window opens and displays the help for the selected property, as well as the rest of the properties, which are available by scrolling. This is the same information as the device help you access using the imaqhelp command. For more detailed information on device-specific properties, see your device's documentation.
3 Using the Image Acquisition Tool GUI 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 to log your acquisition. Select one of the following: • Memory — Acquisition is logged to memory. This means that the acquired data that you do not otherwise save (using Export Data) will be logged to your system's memory, and will be available to you only during the acquisition session.
Setting Acquisition Parameters in Image Acquisition Tool Memory Logging If you select Memory or Disk and memory in the Log to options, the Memory limit field displays how much memory is available on your system. This equals the total number of bytes that image acquisition frames can occupy in memory. By default, the tool sets this limit to equal all available physical memory when you first use the tool, or 1 GB, whichever is less.
3 Using the Image Acquisition Tool GUI of five different cultures and save them for later analysis. The technician may want resulting file names such as sample_0001.avi, sample_0002.avi, etc. 4 You can use any of the profiles offered by VideoWriter. Accept the default profile (Uncompressed AVI for color devices and Grayscale AVI for monochrome devices) or select another. Currently supported profiles are: • 'Motion JPEG 2000' — Compressed Motion JPEG 2000 file.
Setting Acquisition Parameters in Image Acquisition Tool the compressed image. The data is compressed as much as possible, up to the specified target. This is only available for objects associated with Motion JPEG 2000 files. The default is 10. • Frame Rate is the rate of playback for the video in frames per second. The default is 30. If your device has a set frame rate, that will be used instead.
3 Using the Image Acquisition Tool GUI Use the Triggering tab to set up triggering options. 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 4 and Number of Triggers to 2, the total number of frames in the acquisition will be 8.
Setting Acquisition Parameters in Image Acquisition Tool 2 Optionally set any acquisition parameters and stop the preview. 3 Select Manual in the Trigger Type field on the Triggering tab. 4 Click the Start Acquisition button to get live feed from the device. The Trigger button is activated in the Preview window once the acquisition starts. 5 Click the Trigger button when you want to start logging data.
3 Using the Image Acquisition Tool GUI 4 Select your Trigger Source. This indicates the hardware source that is monitored for trigger conditions. When the condition specified in Trigger Condition is met, the trigger is executed and the acquisition starts. 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 Port0 and Port1, or OptoTrig and TTL. 5 Select your Trigger Condition.
Setting Acquisition Parameters in Image Acquisition Tool Use the arrows in each field to adjust the numbers. The preview resizes as you make changes. 3 When the region is the desired size, start your acquisition by clicking the Start Acquisition button. Note: You cannot adjust the ROI after starting the acquisition. Setting Region of Interest Interactively You can also set a region of interest interactively while previewing your image.
3 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 3-24 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.
Setting Acquisition Parameters in Image Acquisition Tool 4 Release the mouse button to freeze the region. The region is not set until you take action to commit it. 5 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 Using the Image Acquisition Tool GUI Before starting the acquisition, if you want to adjust the region further, you can drag the selected region around while still in selection mode. You can also drag any of the handles on the region outline to change the dimensions of the region. You can then commit the region by pressing Enter or using the right-click menu Commit Region of Interest inside the region.
Setting Acquisition Parameters in Image Acquisition Tool You can clear the drawn region before you commit it by single-clicking anywhere in the Preview Window outside of the selected area. You will still be in ROI selection mode. If you want to clear the selected region and exit ROI selection mode, press the Delete key, press the Escape key, or use the right-click menu Exit Region of Interest Mode inside the region.
3 Using the Image Acquisition Tool GUI Previewing and Acquiring Data in Image Acquisition Tool In this section... “The Preview Window” on page 3-28 “Previewing Data” on page 3-30 “Acquiring Data” on page 3-30 The Preview Window The Preview window displays the image data when you preview or acquire data.
Previewing and Acquiring Data in Image Acquisition Tool Use the buttons in the Preview window to: • Preview your image. See “Previewing Data” on page 3-30 for more information. • Acquire data. See “Acquiring Data” on page 3-30 for more information. • Export data. See “Exporting Data in the Image Acquisition Tool” on page 3-35 for more information. • Set Region of Interest. See “Setting a Region of Interest” on page 3-22 for more information.
3 Using the Image Acquisition Tool GUI Below the area that displays the frames you will see text messages with information relative to the current state of the window. For example in the figure above, that text indicates that all the frames that were acquired are being displayed. After you start and stop a preview, the text will indicate that the tool is ready to acquire data. During an acquisition, a running timer appears under the display area that indicates the actual time of the frame acquisition.
Previewing and Acquiring Data in Image Acquisition Tool The nodes listed under the device name are the formats the device supports. They may correspond to the different resolutions and color spaces that your device supports, or to different video standards or camera configurations. This information comes from your device adaptor. Select the format you want to use. See “Selecting Your Device in Image Acquisition Tool” on page 3-8 for more information about devices and formats.
3 Using the Image Acquisition Tool GUI • If you set Trigger Type (on the Triggering tab) to Immediate, the tool will immediately start logging data. • If you set Trigger Type to Manual, click the Trigger button when you want to start logging data. For more information about manual triggering, see “Setting Up Triggering” on page 3-19. 7 Stop the acquisition: • If you set Frames Per Trigger (on the General tab) to 1 or any other number, your acquisition will stop when that number of frames is reached.
Previewing and Acquiring Data in Image Acquisition Tool 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.
3 Using the Image Acquisition Tool GUI To use manual triggering, go to the Triggering tab of the Acquisition Parameters pane and select Manual in the Trigger Type field. For more detailed instructions about manual triggering, see “Selecting the Trigger Type” on page 3-20. For more information about troubleshooting specific devices, see “Troubleshooting Overview” on page 16-2 in the Troubleshooting chapter.
Exporting Data in the Image Acquisition Tool Exporting Data in the Image Acquisition Tool You can export the data that has been acquired in memory to a MAT-file, the MATLAB Workspace, VideoWriter, or other options. To export the acquisition data: 1 Click the Export Data button in the Preview window to export the last acquisition that was logged to memory. 2 In the Data Exporter dialog box, select MAT-File, MATLAB Workspace, or one of the other options in the Data Destination field.
3 Using the Image Acquisition Tool GUI The VideoWriter Parameters dialog box opens after you select a file name and profile and click OK. If you selected Motion JPEG 2000 or Archival as your profile, you can set the Compression Ratio, Frame Rate, Lossless Compression, and MJ2 Bit Depth options. Accept the default values or change them. If you selected Motion JPEG AVI as your profile, you can set the Frame Rate and Quality options. Accept the default values or change them.
Exporting Data in the Image Acquisition Tool VideoWriter Options • Compression Ratio is a number greater than 1 that specifies the target ratio between the number of bytes in the input image and the number of bytes in the compressed image. The data is compressed as much as possible, up to the specified target. This is only available for objects associated with Motion JPEG 2000 files. The default is 10. • Frame Rate is the rate of playback for the video in frames per second. The default is 30.
3 Using the Image Acquisition Tool GUI • Quality is a number from 0 to 100. Higher quality numbers result in higher video quality and larger file sizes. Lower quality numbers result in lower video quality and smaller file sizes. Only available for objects associated with the Motion JPEG AVI profile. The default is 75. 5 If you exported to the MATLAB Workspace, the dialog box closes and the data is saved to the Workspace.
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. To save a configuration: 1 Select File > Save Configuration. The Save Configuration dialog box opens.
3 Using the Image Acquisition Tool GUI You can then open the saved configuration file in a future tool session by selecting File > Open Configuration. In the Open Configuration dialog box, browse to an IAT file and click Open. Note: You can also export hardware configuration information to other formats such as a MATLAB code file or a MAT-file that can be accessed from MATLAB. See “Exporting Image Acquisition Tool Hardware Configurations to MATLAB” on page 3-41.
Exporting Image Acquisition Tool Hardware Configurations to MATLAB Exporting Image Acquisition Tool Hardware Configurations to MATLAB You can export the video input objects and their configured parameters from the tool to a choice of multiple formats. You can then access the video object in MATLAB. To export a hardware configuration: 1 Select File > Export Hardware Configuration. The Export Hardware Configuration dialog box opens. 2 Select the file format from the Object destination list.
3 Using the Image Acquisition Tool GUI The Object Exporter dialog box lists the currently selected device format, as well as any others you selected in the Hardware Browser during the tool session. All formats are selected by default, meaning their configurations will be saved. If you do not want to save a configuration, clear it from the list. 4 Click Save. If you exported to the MATLAB Workspace, the dialog box closes and the data is saved to the MATLAB Workspace.
Saving and Copying Image Acquisition Tool Session Log Saving and Copying Image Acquisition Tool Session Log In this section... “About the Session Log” on page 3-43 “Saving the Session Log” on page 3-43 “Copying the Session Log” on page 3-44 About the Session Log The session log dynamically records every action you perform in the Image Acquisition Tool. The corresponding command-line functionality for actions on a videoinput object or videosource object is reflected in the log.
3 Using the Image Acquisition Tool GUI 2 In the Save Session Log dialog box, browse to the location where you want to save the file. 3 Use the default name, imaqtoolSessionLog.m, or rename it. 4 When you click the Save button, the file will open in the MATLAB Editor. You can then either edit it or close it. Note that the entire contents of the session log is saved. If you just want to save a portion of the log, use the Copy command instead.
Saving and Copying Image Acquisition Tool Session Log This copies the selected contents to the system clipboard. 3 Go to the application or file that you wish to copy it into, and right-click Paste. You can then edit or save it as your application allows.
3 Using the Image Acquisition Tool GUI Registering a Third-Party Adaptor in the Image Acquisition Tool If you are using a third-party adaptor that requires the use of the imaqregister function, you can use this menu as an easier way to add the adaptor. Note that this function is not documented in the Image Acquisition Toolbox User's Guide, but is documented in the Image Acquisition Toolbox Adaptor Kit User's Guide.
4 Image Acquisition Support Packages • “Image Acquisition Support Packages for Hardware Adaptors” on page 4-2 • “Installing the Support Packages for Image Acquisition Toolbox Adaptors” on page 4-7
4 Image Acquisition Support Packages Image Acquisition Support Packages for Hardware Adaptors The existing support for all supported hardware, such as GigE Vision and Windows Video, is now available via the Support Package Installer. This is the same functionality for acquiring images using all supported cameras that has always been part of the Image Acquisition Toolbox. With previous versions of the Image Acquisition Toolbox, the files for all of the adaptors were included in your installation.
Image Acquisition Support Packages for Hardware Adaptors Adaptor Name Support package name in list Contents Kinect for Windows (kinect) Kinect for Windows Sensor MATLAB files to use Kinect for Windows cameras with the toolbox Third party files – Kinect for Windows Runtime QImaging (qimaging) QImaging Hardware MATLAB files to use QImaging cameras with the toolbox Third party files – QImaging QCam DALSA IFC (dalsaifc) Teledyne DALSA IFC Hardware MATLAB files to use DALSA IFC cameras with the toolb
4 Image Acquisition Support Packages Adaptor Name Support package name in list Contents Point Grey (pointgrey) Point Grey Hardware MATLAB files to use Point Grey cameras with the toolbox Third party files – Point Grey FlyCapture Linux Video (linuxvideo) OS Generic Video Interface MATLAB files to use Windows Video, Macintosh Video, or Linux Video cameras with the toolbox. The correct OS files will be installed, depending on your system.
Image Acquisition Support Packages for Hardware Adaptors if you have a Webcam on a Windows system and a Matrox camera, you would need to install the OS Generic Video Interface support package for the winvideo adaptor for the Webcam and the Matrox Hardware support package for the matrox adaptor. Run the Support Package Installer and use the adaptor name in the table to install the correct package(s) that you need.
4 Image Acquisition Support Packages The following topic describes how to install the Image Acquisition Toolbox support packages: “Installing the Support Packages for Image Acquisition Toolbox Adaptors” on page 4-7 4-6
Installing the Support Packages for Image Acquisition Toolbox Adaptors Installing the Support Packages for Image Acquisition Toolbox Adaptors With previous versions of the Image Acquisition Toolbox, the files for all of the adaptors were included in your installation. Starting with version R2014a, each adaptor is available separately through the Support Package Installer. All of the support packages contain the necessary MATLAB files to use the toolbox with your adaptor.
4 4-8 Image Acquisition Support Packages 2 On the Select an action screen, select Install from Internet and then click Next. This option is selected by default. Support Package Installer downloads and installs the support package and third-party software from the Internet. 3 On the Select support package to install screen, all of the adaptors are listed if you have the Image Acquisition Toolbox.
Installing the Support Packages for Image Acquisition Toolbox Adaptors You should select the adaptor that you need to install. If you use multiple adaptors, you need to do this installation for each of them separately.
4 Image Acquisition Support Packages Adaptor Name Support package name in list Contents Windows Video (winvideo) OS Generic Video Interface MATLAB files to use Windows Video, Macintosh Video, or Linux Video cameras with the toolbox. The correct OS files will be installed, depending on your system.
Installing the Support Packages for Image Acquisition Toolbox Adaptors Adaptor Name Support package name in list Contents DCAM (dcam) DCAM Hardware MATLAB files to use DCAM cameras with the toolbox Third party files – CMU DCAM on Windows driver file GenICam GenTL (gentl) GenICam Interface MATLAB files to use GenTL cameras with the toolbox Point Grey (pointgrey) Point Grey Hardware MATLAB files to use Point Grey cameras with the toolbox Third party files – Point Grey FlyCapture Linux Video (linu
4 Image Acquisition Support Packages Adaptor Name Support package name in list Contents Hamamatsu (hamamatsu) Hamamatsu Hardware MATLAB files to use Hamamatsu cameras with the toolbox National Instruments (ni) NI Frame Grabbers MATLAB files to use NI hardware with the toolbox Third party files – NIIMAQ file The table also tells you what files get installed for each adaptor. Accept or change the Installation folder and click Next. Note: You must have write privileges for the Installation folder.
Installing the Support Packages for Image Acquisition Toolbox Adaptors 8 If your adaptor includes third-party files, that installation starts, and a download status dialog box appears during the installation. You can continue working in MATLAB as the download proceeds. 9 After the installation of the third-party files (if included) and the Image Acquisition Toolbox files is complete you will see a confirmation message on the Support Package Installer Install/update complete screen.
5 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.
5 Connecting to Hardware Getting Hardware Information In this section... “Getting Hardware Information” on page 5-2 “Determining the Device Adaptor Name” on page 5-2 “Determining the Device ID” on page 5-3 “Determining Supported Video Formats” on page 5-5 Getting Hardware Information 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.
Getting Hardware Information acquisition equipment and for particular classes of image acquisition devices. For the latest information about supported hardware, 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 imaqhwinfo function. The imaqhwinfo function returns information about the toolbox software and lists the adaptors available on the system in the InstalledAdaptors field.
5 Connecting to Hardware AdaptorDllName: AdaptorDllVersion: AdaptorName: DeviceIDs: DeviceInfo: [1x73 char] '2.1 (R2007a)' 'matrox' {[1]} [1x1 struct] The fields in the structure returned by imaqhwinfo provide the following information.
Getting Hardware Information SupportedFormats: {1x10 cell} The fields in the device information structure provide the following information about a device. Field Description DefaultFormat Text string that identifies the video format used by the device if none is specified at object creation time DeviceFileSupported If set to 1, the device supports device configuration files; otherwise 0. See “Using Device Configuration Files (Camera Files)” on page 5-12 for more information.
5 Connecting to Hardware To determine which video formats an image acquisition device supports, look in the SupportedFormats field of the DeviceInfo structure returned by the imaqhwinfo function. To view the information for a particular device, call imaqhwinfo, specifying the device ID as an argument.
Getting Hardware Information 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 5-7
5 Connecting to Hardware Creating Image Acquisition Objects In this section...
Creating Image Acquisition Objects objects by default, but you can change this selection. See “Specifying the Selected Video Source Object” on page 5-13 for more information. The following figure illustrates how a video input object acts as a container for one or more video source objects. Relationship of Video Input Objects and Video Source Objects For example, a Matrox frame grabber device can support eight physical connections, which Matrox calls channels.
5 Connecting to Hardware This syntax uses the default video format listed in the DefaultFormat field of the data returned by imaqhwinfo. You can optionally specify the video format. See “Specifying the Video Format” on page 5-11 for more information. Viewing a Summary of a Video Input Object To view a summary of the characteristics of the video input object you created, enter the variable name you assigned to the object at the command prompt. For example, this is the summary for the object vid.
Creating Image Acquisition Objects 4 The Trigger Parameters section lists the trigger type configured for the object and the number of times the trigger is to be executed. Trigger execution initiates data logging, and the toolbox supports several types of triggers. The example object is configured by default with an immediate trigger. For more information about configuring triggers, see “Specifying the Trigger Type” on page 6-8. 5 The Status section lists the current state of the object.
5 Connecting to Hardware In this example, each of the text strings is a video format supported by a Matrox device. info = imaqhwinfo('matrox'); info.DeviceInfo.SupportedFormats ans = Columns 1 through 4 'M_RS170' 'M_RS170_VIA_RGB' 'M_CCIR' 'M_CCIR_VIA_RGB' Columns 5 through 8 'M_NTSC' 'M_NTSC_RGB' 'M_NTSC_YC' 'M_PAL' Columns 9 through 10 'M_PAL_RGB' 'M_PAL_YC' For Matrox devices, the toolbox uses the RS170 format as the default.
Creating Image Acquisition Objects For example, with Matrox frame grabbers, you can download digitizer configuration format (DCF) files, in their terminology. These files configure their devices to support particular cameras. Some image acquisition device vendors provide utility programs you can use to create a device configuration file or edit an existing one. See your hardware vendor's documentation for more information.
5 Connecting to Hardware To illustrate, this example lists the video source objects associated with the video input object vid. vid.Source Display Summary for Video Source Object Array: Index: 1 2 3 4 5 6 7 8 SourceName: 'CH0' 'CH1' 'CH2' 'CH3' 'CH4' 'CH5' 'CH6' 'CH7' Selected: 'on' 'off' 'off' 'off' 'off' 'off' 'off' 'off' By default, the video input object makes the first video source object in the array the selected source.
Creating Image Acquisition Objects AdaptorName: DeviceName: MaxHeight: MaxWidth: NativeDataType: TotalSources: VendorDriverDescription: VendorDriverVersion: 'winvideo' 'IBM PC Camera' 96 128 'uint8' 1 'Windows WDM Compatible Driver' 'DirectX 9.
5 Connecting to Hardware Configuring Image Acquisition Object Properties In this section...
Configuring Image Acquisition Object Properties Viewing the Values of Object Properties To view all the properties of an image acquisition object, with their current values, use the get function. You can also use the inspect function to view a list of object properties in the Property Inspector window, where you can also edit their values. This example uses the get function to display a list of all the properties of the video input object vid.
5 Connecting to Hardware StopFcn = [] TimerFcn = [] TimerPeriod = 1 TriggerFcn = [] Trigger Settings: InitialTriggerTime = [0 0 0 0 0 0] TriggerCondition = none TriggerFrameDelay = 0 TriggerRepeat = 0 TriggersExecuted = 0 TriggerSource = none TriggerType = immediate Acquisition Sources: SelectedSourceName = CH0 Source = [1x8 videosource] Viewing the Properties of a Video Source Object To view the properties supported by the video source object (or objects) associated with a video input object, use the ge
Configuring Image Acquisition Object Properties InputFilter = lowpass UserOutputBit3 = off UserOutputBit4 = off XScaleFactor = 1 YScaleFactor = 1 Viewing the Value of a Particular Property To view the value of a particular property of an image acquisition object, access the value of the property as you would a field in a MATLAB structure. This example illustrates how to access a property by referencing the object as if it were a MATLAB structure using dot notation. vid.
5 Connecting to Hardware The imaqhelp function returns reference information about the property with a complete description. This example uses imaqhelp to get information about the LoggingMode property. imaqhelp(vid,'LoggingMode') Setting the Value of an Object Property To set the value of a particular property of an image acquisition object, you assign the value to the property as you would a field in a MATLAB structure, using dot notation.
Configuring Image Acquisition Object Properties Setting Trigger Properties The values of certain trigger properties, TriggerType, TriggerCondition, and TriggerSource, are interrelated. For example, some TriggerCondition values are only valid with specific values of the TriggerType property.
5 Connecting to Hardware 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 start function. start(vid); When you start an object, you reserve the device for your exclusive use and lock the configuration. Thus, certain properties become read only while running.
Starting and Stopping a Video Input Object The following example illustrates starting and stopping an object: 1 Create an image acquisition object — This example creates a video input object for a webcam image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
5 Connecting to Hardware islogging(vid) ans = 0 6 Execute the manual trigger — Call the trigger function to execute the manual trigger. trigger(vid) While the acquisition is underway, check the logging state of the video input object. islogging(vid) ans = 1 After it acquires the specified number of frames, the video input object stops running. isrunning(vid) ans = 0 7 Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
Deleting Image Acquisition Objects Deleting Image Acquisition Objects When you finish using your image acquisition objects, use the delete function 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.
5 Connecting to Hardware Nest a call to the imaqfind function within the delete function to delete all these objects from memory. delete(imaqfind) Note that the variables associated with the objects remain in the workspace. whos Name vid vid2 vid3 vids Size 1x1 1x1 1x1 1x3 Bytes 1120 1120 1120 1280 Class videoinput videoinput videoinput videoinput object object object object These variables are not valid image acquisition objects.
Saving Image Acquisition Objects Saving Image Acquisition Objects In this section... “Using the save Command” on page 5-27 “Using the obj2mfile Command” on page 5-27 Using the save Command You can save a video input object to a MAT-file just as you would any workspace variable by using the save command. This example saves the video input object vid to the MATfile myvid.mat.
5 Connecting to Hardware Image Acquisition Toolbox Properties The following properties are available in the toolbox.
Image Acquisition Toolbox Properties • StopFcn • Tag • Timeout • TimerFcn • TimerPeriod • TriggerCondition • TriggerFcn • TriggerFrameDelay • TriggerRepeat • TriggersExecuted • TriggerSource • TriggerType • Type • UserData • VideoFormat • VideoResolution 5-29
6 Acquiring Image Data
6 Acquiring Image Data 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. For some types of triggers, the condition can be the execution of a toolbox function. For other types of triggers, the condition can be a signal from an external source that is monitored by the image acquisition hardware.
Data Logging Data Logging In this section... “Overview” on page 6-3 “Trigger Properties” on page 6-4 Overview When a trigger occurs, the toolbox sets the object's Logging property to 'on' and starts storing the acquired frames in a buffer in memory, a disk file, or both. When the acquisition stops, the toolbox sets the object's Logging property to 'off'. The following figure illustrates when an object moves into a logging state and the relation between running and logging states.
6 Acquiring Image Data Overview of Data Logging Trigger Properties The video input object supports several properties that you can use to configure aspects of trigger execution. Some of these properties return information about triggers. For example, to find out when the first trigger occurred, look at the value of the InitialTriggerTime property. Other properties enable you to control trigger behavior.
Data Logging Property Description TriggerFrameDelay Specifies the number of frames to skip before logging data to memory, disk, or both. For more information, see “Delaying Data Logging After a Trigger” on page 6-31. TriggerRepeat Specifies the number of additional times to execute a trigger. If the value of TriggerRepeat is 0 (zero), the trigger executes but is not repeated any additional times. For more information, see “Specifying Multiple Triggers” on page 6-32.
6 Acquiring Image Data Setting the Values of Trigger Properties In this section... “About Trigger Properties” on page 6-6 “Specifying Trigger Type, Source, and Condition” on page 6-6 About Trigger Properties Most trigger properties can be set in the same way you set any other image acquisition object property: referencing the property as you would a field in a structure using dot notation.
Setting the Values of Trigger Properties config = triggerinfo(vid); This function returns an array of structures, one structure for each valid combination of property values. Each structure in the array is made up of three fields that contain the values of each of these trigger properties.
6 Acquiring Image Data Specifying the Trigger Type In this section... “Comparison of Trigger Types” on page 6-8 “Using an Immediate Trigger” on page 6-9 “Using a Manual Trigger” on page 6-11 “Using a Hardware Trigger” on page 6-14 “Setting DCAM-Specific Trigger Modes” on page 6-17 Comparison of Trigger Types To specify the type of trigger you want to execute, set the value of the TriggerType property of the video input object. You must use the triggerconfig function to set the value of this property.
Specifying the Trigger Type TriggerType Value TriggerSource and Description TriggerCondition Values type of trigger is used when synchronization with another device is part of the image acquisition setup or when speed is required. A hardware device can process an input signal much faster than software. For more information, see “Using a Hardware Trigger” on page 6-14. Note: Only a subset of image acquisition devices supports hardware triggers.
6 Acquiring Image Data Immediate Trigger The following example illustrates how to use an immediate trigger: 1 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 imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code. vid = videoinput('matrox',1); Verify that the object has not acquired any frames. vid.
Specifying the Trigger Type TriggerType: 'immediate' TriggerCondition: 'none' TriggerSource: 'none' This example sets the value of the FramesPerTrigger property to 5. (The default is 10 frames per trigger.) vid.FramesPerTrigger = 5 3 Start the image acquisition object — Call the start function to start the image acquisition object. By default, the object executes an immediate trigger and acquires five frames of data, logging the data to a memory buffer.
6 Acquiring Image Data Manual Trigger The following example illustrates how to use a manual trigger: 1 Create an image acquisition object — This example creates a video input object for a webcam image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code. vid = videoinput('winvideo',1); Verify that the object has not acquired any frames. vid.
Specifying the Trigger Type 3 Start the image acquisition object — Call the start function to start the image acquisition object. start(vid); The video object is now running but not logging. With manual triggers, the video stream begins when the object starts but no frames are acquired until the trigger executes. isrunning(vid) ans = 1 islogging(vid) ans = 0 Verify that the object has still not acquired any frames. vid.
6 Acquiring Image Data 0 To execute another manual trigger, you must first restart the video input object. Note that this deletes the frames acquired by the first trigger. To execute multiple manual triggers, specify a value for the TriggerRepeat property. See “Specifying Multiple Triggers” on page 6-32 for more information. 5 Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
Specifying the Trigger Type Hardware Trigger The following example illustrates how to use a hardware trigger: 1 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 imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code. The device must support hardware triggers.
6 Acquiring Image Data 'hardware' 'hardware' 3 'risingEdge' 'fallingEdge' 'TTL' 'TTL' Configure properties — Configure the video input object trigger properties to one of the valid combinations returned by triggerinfo. You can specify each property value as an argument to the triggerconfig function triggerconfig(vid, 'hardware','risingEdge','TTL') Alternatively, you can set these values by passing one of the structures returned by the triggerinfo function to the triggerconfig function.
Specifying the Trigger Type vid.FramesAcquired ans = 5 After it executes the trigger and acquires the specified number of frames, the video input object stops running. isrunning(vid) ans = 0 To execute another hardware trigger, you must first restart the video input object. Note that this deletes the frames acquired by the first trigger. To execute multiple triggers, specify a value for the TriggerRepeat property. See “Specifying Multiple Triggers” on page 6-32 for more information.
6 Acquiring Image Data Trigger Mode Parameter External Source Multiple Frames Per Trigger 1 none yes no 2 (N >= 2) yes no 3 (N >= 1) no yes 4 (N >= 1) yes no 5 (N >= 1) yes no 14 unknown unknown unknown 15 unknown unknown unknown For example, the second triggersource for trigger mode 1 is called externalTrigger1-mode1. To use mode 3, the triggersource is internalTrigger-mode3.
Specifying the Trigger Type If the camera supports only trigger mode 0 with source 0, then the original functionality of having only the externalTrigger triggersource is supported. Trigger modes 14 and 15 are vendor-specific and are assumed to be external triggers and have no restrictions on any settings. You must validate any settings you use. The following sections detail the trigger modes. Trigger Mode 0 This is the only trigger mode supported before R2010a.
6 Acquiring Image Data 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. The camera starts the integration of the incoming light from the external trigger input falling edge. Integration time is equal to the low state time of the external trigger input if triggersource is fallingEdge, otherwise it is equal to the high state time.
Specifying the Trigger Type The camera starts the integration of the incoming light from the first external trigger input falling edge. At the Nth external trigger input falling edge, integration stops. Parameter N is required and must be 2 or greater. (N >= 2). Trigger Mode 3 Use this internal trigger mode to achieve a lower frame rate. When the trigger generates internally, a frame is acquired and returned.
6 Acquiring Image Data The camera starts integration of incoming light from the first external trigger input falling edge and exposes incoming light at shutter time. Repeat this sequence until the Nth external trigger input falling edge, then finish integration. Parameter N is required and must be 1 or greater (N >= 1). Trigger Mode 5 This mode is the “multiple shutter pulse width mode.” It is a combination of modes 1 and 2.
Specifying the Trigger Type Trigger Mode 14 This is a vendor-specific mode and no information is available. Consult the documentation for your camera. Trigger Mode 15 This is a vendor-specific mode and no information is available. Consult the documentation for your camera.
6 Acquiring Image Data Controlling Logging Parameters In this section... “Data Logging” on page 6-24 “Specifying Logging Mode” on page 6-24 “Specifying the Number of Frames to Log” on page 6-25 “Determining How Much Data Has Been Logged” on page 6-26 “Determining How Many Frames Are Available” on page 6-28 “Delaying Data Logging After a Trigger” on page 6-31 “Specifying Multiple Triggers” on page 6-32 Data Logging The following subsections describe how to control various aspects of data logging.
Controlling Logging Parameters vid.LoggingMode = 'disk&memory'; Because the toolbox stores the image frames in Audio Video Interleaved (AVI) format, you can view the logged frames in any standard media player. For more information, see “Logging Image Data to Disk” on page 6-42. Specifying the Number of Frames to Log In the Image Acquisition Toolbox software, you specify the amount of data you want to acquire as the number of frames per trigger.
6 Acquiring Image Data Specifying a Noncontiguous Acquisition Although FramesPerTrigger specifies the number of frames to acquire, these frames do not have to be captured contiguously from the video stream. You can specify that the toolbox skip a certain number of frames between frames it acquires. To do this, set the value of the FrameGrabInterval property. Note The FrameGrabInterval property controls the interval at which the toolbox acquires frames from the video stream (measured in frames).
Controlling Logging Parameters Acquiring 100 Frames This example illustrates how you can specify the amount of data to be acquired and determine how much data has been acquired. (For an example of configuring a timebased acquisition, see “Acquiring 10 Seconds of Image Data” on page 7-5.) 1 Create an image acquisition object — This example creates a video input object for a Windows image acquisition device.
6 Acquiring Image Data 100 5 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 Determining How Many Frames Are Available The FramesAcquired property tells how many frames the object has logged since it was started, described in “Determining How Much Data Has Been Logged” on page 6-26.
Controlling Logging Parameters start(vid) The object executes an immediate trigger and begins acquiring frames of data. The start function returns control to the command line immediately but the object continues logging the data to the memory buffer. After logging the specified number of frames, the object stops running.
6 Acquiring Image Data 5 Remove frames from the memory buffer — When you remove frames from the memory buffer, the object decrements the value of the FramesAvailable property by the number of frames removed. To remove frames from the memory buffer, call the getdata function, specifying the number of frames to retrieve. For more information about using getdata, see “Bringing Image Data into the MATLAB Workspace” on page 7-3.
Controlling Logging Parameters Contents of Memory Buffer Before and After Removing Frames 6 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. For example, some cameras require a short warmup time when activated.
6 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 FramesPerTrigger property and logs the data to a memory buffer, a disk file, or both. When it acquires the specified number of frames, the video input object stops running. To execute another trigger, you must restart the video input object.
Controlling Logging Parameters Executing Multiple Triggers 6-33
6 Acquiring Image Data Waiting for an Acquisition to Finish In this section... “Using the wait Function” on page 6-34 “Blocking the Command Line Until an Acquisition Completes” on page 6-35 Using the wait Function The start function and the trigger function are asynchronous functions. That is, they start the acquisition of frames and return control to the MATLAB command line immediately.
Waiting for an Acquisition to Finish Using wait to Block the MATLAB Command Line Blocking the Command Line Until an Acquisition Completes The following example illustrates how to use the wait function to put a 60 second time limit on the execution of a hardware trigger. If the hardware trigger does not execute within the time limit, wait returns control to the MATLAB command line. 1 Create an image acquisition object — This example creates a video input object for a Matrox image acquisition device.
6 Acquiring Image Data imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code. vid = videoinput('matrox',1); 2 Configure a hardware trigger — Use the triggerinfo function to determine valid configurations of the TriggerSource and TriggerCondition properties. See “Determining Valid Configurations” on page 6-6 for more information. In this example, triggerinfo returns the following valid trigger configurations.
Waiting for an Acquisition to Finish wait(vid,60) The wait function blocks the command line until the hardware trigger fires and acquisition completes or until the amount of time specified by the timeout value expires. 6 Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
6 Acquiring Image Data Managing Memory Usage In this section... “Memory Usage” on page 6-38 “Monitoring Memory Usage” on page 6-38 “Modifying the Frame Memory Limit” on page 6-39 “Freeing Memory” on page 6-40 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.
Managing Memory Usage mem_left = out.FrameMemoryLimit - out.FrameMemoryUsed; To see an example of using a callback function to monitor memory usage, see “Monitoring Memory Usage” on page 8-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. Using the imaqmem function you can determine the current frame memory limit and specify a new one. The following example illustrates this process.
6 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 flushdata function, you can delete all the frames currently stored in memory or only those frames associated with the execution of a trigger. The following example illustrates how to use flushdata to delete all the frames in memory or one trigger's worth of frames.
Managing Memory Usage To verify that the object deleted the frames, view the value of the FramesAvailable property. vid.FramesAvailable ans = 10 5 Empty the entire memory buffer — Calling flushdata without 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 FramesAvailable property. vid.
6 Acquiring Image Data Logging Image Data to Disk In this section... “Logging Data to Disk Using VideoWriter” on page 6-42 “Logging Data to Disk Using VideoWriter” on page 6-42 “Logging Data to Disk Using an AVI File” on page 6-44 “Creating an AVI File Object for Logging” on page 6-45 “Logging Data to Disk Using an AVI File” on page 6-47 Logging Data to Disk Using VideoWriter While a video input object is running, you can log image data being acquired to a disk file.
Logging Image Data to Disk This example uses a GigE Vision device in a grayscale format (Mono10). 1 Create a video input object that accesses a GigE Vision image acquisition device and uses grayscale format at 10 bits per pixel. vidobj = videoinput('gige', 1, 'Mono10'); 2 You can log acquired data to memory, to disk, or both. By default, data is logged to memory. To change the logging mode to disk, configure the video input object's LoggingMode property. vidobj.
6 Acquiring Image Data Guidelines for Using a VideoWriter Object to Log Image Data Note the following when using VideoWriter. • You should not delete the video input object until logging has been completed as indicated by the DiskLoggerFrameCount property equaling the FramesAcquired property. Doing so will cause disk logging to stop without all of the data being logged.
Logging Image Data to Disk Logging Data to a Disk File Note: AVI files are limited to a bit-depth of 8 bits per pixel for each band. If you have higher bit data, you should not log it to an AVI file since the AVI format is restricted to 8bit data. If you do log higher bit data to an AVI file, it will be scaled and then logged as 8bit data. Creating an AVI File Object for Logging To create an AVI file in the MATLAB environment, use the avifile function.
6 Acquiring Image Data • “Guidelines for Using an AVI File Object to Log Image Data” on page 6-46 • “Closing the DiskLogger AVI file” on page 6-46 Logging Grayscale Images Using an AVI File When logging images in grayscale format, such as RS170, you must set the value of the AVI object's Colormap property to be a grayscale colormap. Otherwise, the image data in the AVI file will not display correctly.
Logging Image Data to Disk object (aviobj). See “Logging Data to Disk Using an AVI File” on page 6-47 for an example. Before you close the file, make sure that the video input object has finished logging frames to disk. Because logging to disk takes more time than logging to memory, the completion of disk logging can lag behind the completion of memory logging.
6 Acquiring Image Data CurrentState: 'Open' 2 Configure properties of the AVI file object — You can optionally configure the properties of the AVI file object. The AVI file object supports properties that control the data compression used, image quality, and other characteristics of the file. The example sets the quality property to a midlevel value. By lowering the quality, the AVI file object creates smaller log files. aviobj.
Logging Image Data to Disk ans = 40 Note Because it takes longer to write frames to a disk file than to memory, the value of the DiskLoggerFrameCount property can lag behind the value of the FramesAvailable property, which specifies the number of frames logged to memory. To verify that a disk file was created, go to the directory in which the log file resides and make sure it exists. The exist function returns 2 if the file exists. if(exist(my_log)==2) disp('AVI file created.
7 Working with Acquired Image Data When you trigger an acquisition, the toolbox stores the image data in a memory buffer, a disk file, or both. To work with this data, you must bring it into the MATLAB workspace. This chapter describes how you use video input object properties and toolbox functions to bring the logged data into the MATLAB workspace.
7 Working with Acquired Image Data Image Acquisition Overview When a trigger occurs, the toolbox acquires frames from the video stream and logs the frames to a buffer in memory, a disk file, or both, depending on the value of the LoggingMode property. To work with this logged image data, you must bring it into the MATLAB workspace.
Bringing Image Data into the MATLAB Workspace Bringing Image Data into the MATLAB Workspace In this section...
7 Working with Acquired Image Data main Documentation Center page, 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 getdata function. By default, getdata retrieves the number of frames specified in the FramesPerTrigger property but you can specify any number. See the getdata reference page for complete information about this function.
Bringing Image Data into the MATLAB Workspace Acquiring 10 Seconds of Image Data This example shows how you can configure an approximate time-based acquisition using the FramesPerTrigger property: 1 Create an image acquisition object — This example creates a video input object for a Windows image acquisition device. To run this example on your system, use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code.
7 Working with Acquired Image Data delete(vid) clear vid Viewing Frames in the Memory Buffer To view sample frames from the memory buffer without removing them, use the peekdata function. The peekdata function always returns the most recently acquired frames in the memory buffer. For example, if you request three frames, peekdata returns the most recently acquired frame in the buffer at the time of the request and the two frames that immediately precede it. The following figure illustrates this process.
Bringing Image Data into the MATLAB Workspace Frames Returned by peekdata Note: The peekdata function does not return any data while running if in disk logging mode. The following example illustrates how to use peekdata: 1 Create an image acquisition object — This example creates a video input object for a Data Translation image acquisition device.
7 Working with Acquired Image Data In addition, configure a large enough acquisition to allow several calls to peekdata before it finishes. vid.FramesPerTrigger = 300; 3 Start the image acquisition object — Call the start function to start the image acquisition object. start(vid) The video object is now running but not logging.
Bringing Image Data into the MATLAB Workspace Verify that the object has not acquired any frames. vid.FramesAcquired ans = 0 5 Trigger the acquisition — Call the trigger function to trigger an acquisition. trigger(vid) The object begins logging frames to the memory buffer. 6 View the most recently acquired frames — While the acquisition is in progress, call peekdata several times to view the latest frames in the memory buffer.
7 Working with Acquired Image Data Bringing a Single Frame into the Workspace To bring a single frame of image data into the MATLAB workspace, use the getsnapshot function. You can call the getsnapshot function at any time after object creation. This example illustrates how simple it is to use the getsnapshot function. 1 Create an image acquisition object — This example creates a video input object for a Matrox device.
Working with Image Data in MATLAB Workspace Working with Image Data in MATLAB Workspace In this section... “Understanding Image Data” on page 7-11 “Determining the Dimensions of Image Data” on page 7-12 “Determining the Data Type of Image Frames” on page 7-15 “Specifying the Color Space” on page 7-16 “Viewing Acquired Data” on page 7-22 Understanding Image Data The illustrations in this documentation show the video stream and the contents of the memory buffer as a sequence of individual frames.
7 Working with Acquired Image Data • Determines the data type used for the data • Determines the color space of the data This section also describes several ways to view acquired image data. Determining the Dimensions of Image Data The video format used by the image acquisition device is the primary determinant of the width, height, and the number of bands in each image frame. Image acquisition devices typically support multiple video formats.
Working with Image Data in MATLAB Workspace Video Format and Image Dimensions The following example illustrates how video format affects the size of the image frames returned. 1 Select a video format — Use the imaqhwinfo function to view the list of video formats supported by your image acquisition device. This example shows the video formats supported by a Matrox Orion frame grabber. The formats are industry standard, such as RS170, NTSC, and PAL. These standards define the image resolution.
7 Working with Acquired Image Data vid.VideoResolution ans = [640 480] 4 Bring a single frame into the workspace — Call the getsnapshot function to bring a frame into the workspace. frame = getsnapshot(vid); The dimensions of the returned data reflect the image resolution and the value of the NumberOfBands property. vid.NumberOfBands ans = 1 size(frame) ans = 480 640 5 Start the image acquisition object — Call the start function to start the image acquisition object.
Working with Image Data in MATLAB Workspace 7 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 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, getdata chooses a MATLAB data type that preserves numerical accuracy.
7 Working with Acquired Image Data clear vid Specifying the Color Space For most image acquisition devices, the video format of the video stream determines the color space of the acquired image data, that is, the way color information is represented numerically. For example, many devices represent colors as RGB values. In this color space, colors are represented as a combination of various intensities of red, green, and blue. Another color space, widely used for digital video, is the YCbCr color space.
Working with Image Data in MATLAB Workspace use the imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code. vid = videoinput('winvideo',1); 2 View the default color space used for the data — The value of the ReturnedColorSpace property indicates the color space of the image data. vid.
7 Working with Acquired Image Data If your camera can return Bayer data, the toolbox can automatically convert it to RGB data for you, or you can specify it to do so. The following two examples illustrate both use cases.
Working with Image Data in MATLAB Workspace Manual Conversion The camera in this example has a Bayer sensor. The GigE Vision™ standard allows cameras to inform applications that the data is Bayer encoded and provides enough information for the application to convert the Bayer pattern into a color image. In this case the toolbox automatically converts the Bayer pattern into an RGB image. 1 Create a video object vid using the GigE Vision adaptor and the designated video format.
7 Working with Acquired Image Data ans = 480 640 Notice how the size changed from the rgb image to the grayscale image by comparing the size output in steps 4 and 5. 6 You can optionally use the demosaic function in the Image Processing Toolbox to convert Bayer patterns into color images. % Create an image colorImage by using the demosaic function on the % image img and convert it to color. colorImage = demosaic(img, 'gbrg'); % Now check the size of the new color image.
Working with Image Data in MATLAB Workspace grayscale 3 Create a one-frame image img using the getsnapshot function. img = getsnapshot(vid); 4 View the size of the acquired image. size(img) ans = 480 5 640 The value of the ReturnedColorSpace property is grayscale because Bayer data is single-banded and the toolbox doesn't yet know that it needs to decode the data. Setting the ReturnedColorSpace property to 'bayer' indicates that the toolbox should decode the data. % Set the color space to Bayer.
7 Working with Acquired Image 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. imaqmontage arranges the frames so that they roughly form a square. imaqmontage can be useful for visually comparing multiple frames.
Retrieving Timing Information Retrieving Timing Information In this section...
7 Working with Acquired Image Data 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 vid. The example uses the MATLAB datestr function to convert the information into a form that is more convenient to view. datestr(vid.
Retrieving Timing Information To see an example, see “Determining the Frame Delay Duration” on page 7-25. Getting the Absolute Acquisition Time When you use the getdata function, you can optionally specify three return values. The first contains the image data, the second contains a vector of relative acquisition times, and the third is an array of structures where each structure contains metadata associated with a particular frame.
7 Working with Acquired Image Data vid = videoinput('dt',1); 2 Configure properties — For this example, configure a trigger frame delay large enough to produce a noticeable duration. vid.TriggerFrameDelay = 50 3 Start the image acquisition object — Call the start function to start the image acquisition object. start(vid) The object executes an immediate trigger and begins acquiring frames of data.
Retrieving Timing Information delete(vid) clear vid 7-27
8 Using Events and Callbacks
8 Using Events and Callbacks 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. This is called a callback.
Using the Default Callback Function 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” on page 8-5. The example uses the default callback function provided with the toolbox, imaqcallback.
8 Using Events and Callbacks delete(vid) clear vid 8-4
Event Types Event Types The Image Acquisition Toolbox software supports several different types of events. Each event type has an associated video input object property that you can use to specify the function that executes when the event occurs. This table lists the supported event types, the name of the video input object property associated with the event, and a brief description of the event.
8 Using Events and Callbacks Event Callback Property Description When a frames acquired event occurs, the toolbox executes the function specified by the FramesAcquiredFcn property. Start StartFcn The toolbox generates a start event when an object is started. You use the start function to start an object. When a start event occurs, the toolbox executes the function specified by the StartFcn property. Note: The StartFcn callback executes synchronously.
Event Types Event Callback Property Description When a timer event occurs, the toolbox executes the function specified by the TimerFcn property. Trigger TriggerFcn The toolbox generates a trigger event when a trigger executes. The video input object executes immediate triggers. You execute manual triggers by calling the trigger function. The image acquisition device executes hardware triggers when a specified condition is met.
8 Using Events and Callbacks Retrieving Event Information In this section... “Introduction” on page 8-8 “Event Structures” on page 8-8 “Accessing Data in the Event Log” on page 8-10 Introduction Each event has associated with it a set of information, generated by the toolbox and stored in an event structure. This information includes the event type, the time the event occurred, and other event-specific information.
Retrieving Event Information • “Data Fields for Error Events” on page 8-9 • “Data Fields for Timer Events” on page 8-10 Data Fields for Start, Stop, Frames Acquired, and Trigger Events For start, stop, frames acquired, and trigger events, the Data structure contains these fields. Field Name Description AbsTime Absolute time the event occurred, returned inMATLAB clock format [year month day hour minute seconds] FrameMemoryLimit Amount of memory allotted for frame storage.
8 Using Events and Callbacks Data Fields for Timer Events For timer events, the Data structure contains these fields. Field Name Description AbsTime Absolute time the event occurred, returned in MATLAB clock format [year month day hour minute seconds] FrameMemoryLimit Amount of memory allotted for frame storage. You can specify this value using the imaqmem function.
Retrieving Event Information 2 Start the image acquisition object — Start the image acquisition object. By default, the object executes an immediate trigger, acquires 10 frames of data, and then stops. start(vid) 3 View the event log — Access the EventLog property of the video input object. The execution of the video input object generated three events: start, trigger, and stop. Thus the value of the EventLog property is a 1x3 array of event structures. events = vid.
8 Using Events and Callbacks Creating and Executing Callback Functions In this section... “Introduction” on page 8-12 “Creating Callback Functions” on page 8-12 “Specifying Callback Functions” on page 8-14 “Viewing a Sample Frame” on page 8-16 “Monitoring Memory Usage” on page 8-17 Introduction The power of using event callbacks is the processing that you can perform in response to events. You decide which events you want to associate callbacks with and the functions these callbacks execute.
Creating and Executing Callback Functions The function header for this callback function illustrates this basic syntax. function mycallback(obj,event) The first argument, obj, is the image acquisition object itself. Because the object is available, you can use in your callback function any of the toolbox functions, such as getdata, that require the object as an argument. You can also access all object properties. The second argument, event, is the event structure associated with the event.
8 Using Events and Callbacks 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 “Viewing a Sample Frame” on page 8-16. Specifying Callback Functions You associate a callback function with a specific event by setting the value of the event's callback property. The video input object supports callback properties for all types of events.
Creating and Executing Callback Functions vid.StartFcn = {'mycallback'}; To specify additional parameters, include them as additional elements in the cell array. time = datestr(now,0); vid.StartFcn = {'mycallback',time}; The first two arguments passed to the callback function are still the video input object (obj) and the event structure (event). Additional arguments follow these two arguments.
8 Using Events and Callbacks Too many input arguments. Warning: The FramesAcquiredFcn callback is being disabled. To enable a callback that has been disabled, set the value of the property associated with the callback or restart the object. Viewing a Sample Frame This example creates a video input object and sets the frames acquired event callback function property to the display_frame function, created in “Writing a Callback Function” on page 8-13.
Creating and Executing Callback Functions delete(vid) clear vid Monitoring Memory Usage This example creates a callback function for a timer event that displays the toolbox's current memory usage and stops the acquisition when the available memory for frame storage falls below a specified amount. Creating the Memory Monitor Callback Function This callback function implements a simple memory usage monitoring function.
8 Using Events and Callbacks imaqhwinfo function to get the object constructor for your image acquisition device and substitute that syntax for the following code. vid = videoinput('matrox',1); 2 Configure property values — This example sets up a continuous acquisition by setting the FramesPerTrigger value to Inf. The example also specifies the timer event callback function mem_mon, created in “Creating the Memory Monitor Callback Function” on page 8-17, as the value of the TimerFcn callback.
Creating and Executing Callback Functions Memory load: 97 Memory available for frames getting low. Stopping acquisition. 4 Clean up — Always remove image acquisition objects from memory, and the variables that reference them, when you no longer need them.
9 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.
9 Using the From Video Device Block in Simulink Simulink Image Acquisition Overview The Image Acquisition Toolbox software includes a block that can be used in Simulink to bring live video data into models. The topics in this section describe 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.
Opening the Image Acquisition Toolbox Block Library Opening the Image Acquisition Toolbox Block Library In this section... “Using the imaqlib Command” on page 9-3 “Using the Simulink Library Browser” on page 9-4 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.
9 Using the From Video Device Block in Simulink 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. To start the Simulink Library Browser, enter simulink at the MATLAB prompt. MATLAB opens the browser window. The left pane lists available block libraries in alphabetical order. To open the Image Acquisition Toolbox block library, click its icon.
Using Code Generation Using Code Generation The From Video Device block supports the use of code generation. You can generate code from the block. This enables models containing the From Video Device block to run successfully in Accelerator, Rapid Accelerator, External, and Deployed modes. Here is a typical workflow for code generation. 1 Develop a model using the From Video Device block and blocks from the Computer Vision System Toolbox™. 2 Run the simulation to verify that your device is working.
9 Using the From Video Device Block in Simulink Saving Video Data to a File In this section...
Saving Video Data to a File To create a new model, click the New model button on the Simulink Library Browser toolbar. Simulink opens an empty model. To assign the new model a name, use the Save option. 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 Simulink Editor.
9 Using the From Video Device Block in Simulink Drag From Video Device Block into Model 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. To create this model, this example uses a block from Computer Vision System Toolbox. Open the Computer Vision System Toolbox library. In the library window, open the Sinks subsystem.
Saving Video Data to a File Drag Output Block to Model 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. If the ports are not displayed, you can choose the option to display them in the Source Block Parameters dialog box by double-clicking the block.
9 Using the From Video Device Block in Simulink Note that your camera might have output ports that are Y, Cb, Cr and the input ports on the To Multimedia File block are R, G, B. Some devices designate color band by YCbCr and some devices designate it by RGB. Both are valid and will work together.
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. You can set parameters for any of the blocks you include in your model. For example, to specify the name of the AVI file, double-click the To Multimedia File block.
9 Using the From Video Device Block in Simulink While the simulation is running, the status bar at the bottom of the Simulink Editor indicates the progress of the simulation. After the simulation finishes, check the directory in which you ran the simulation to verify that an AVI file was created.
10 Configuring GigE Vision Devices • “Types of Setups” on page 10-2 • “Network Hardware Configuration Notes” on page 10-3 • “Network Adaptor Configuration Notes” on page 10-4 • “Software Configuration” on page 10-11 • “Setting Preferences” on page 10-13 • “Troubleshooting” on page 10-15
10 Configuring GigE Vision Devices Types of Setups The Image Acquisition Toolbox software supports GigE Vision devices. The following sections describe information on installing and configuring the devices to work with the Image Acquisition Toolbox software. Separate troubleshooting information is found in “Troubleshooting GigE Vision Devices on Windows” on page 16-26. Note: Not all cameras that use Ethernet are GigE Vision.
Network Hardware Configuration Notes Network Hardware Configuration Notes The following notes apply to network connections and hardware. Using the same network as the PC on a shared network connection — Plug the camera into the network that the PC is plugged into. They must be on the same subnet. A system administrator can configure a VLAN if necessary. Using a private network connection — You can connect the camera through the main/ only Ethernet card, or through a second Ethernet card.
10 Configuring GigE Vision Devices Network Adaptor Configuration Notes In this section... “Windows Configuration” on page 10-4 “Linux Configuration” on page 10-5 “Mac Configuration” on page 10-6 Windows Configuration Important Note: When you install your vendor software that came with your device, do not install your vendor's filtering or performance networking driver. Let Windows automatically determine the IP if you are using a single direct connection to the PC, instead of attempting to use static IP.
Network Adaptor Configuration Notes If the Status column says “Limited or no connectivity,” it will not impact your camera, as that status applies to the Internet. 3 Open the Properties dialog box of the Ethernet card by double-clicking it in Network Connections. If you are using a separate Ethernet card for the GigE camera, make sure that in the This connection uses the following items section on the General tab you have nothing selected except for Internet Protocol (TCP/IP).
10 Configuring GigE Vision Devices We recommend that you have your system administrator help with the following setup tasks: • Getting the Ethernet card recognized by the kernel. • Getting the IP and MTU configuration set up for direct connection. For dynamic IP configuration of a camera and Ethernet card not connected to an organizational network, avahi-autoipd can be used. However, we recommend that each direct connection to a camera have an interface with a static IP such as 10.10.x.y or 192.168.x.y.
Network Adaptor Configuration Notes In the configuration shown here, the Mac Pro has two Ethernet connections, one to an internal network, and one for GigE Vision. The GigE Vision connection is set to use DHCP. Advanced settings are set as shown in the following diagrams.
10 Configuring GigE Vision Devices The TCP/IP tab.
Network Adaptor Configuration Notes The DNS tab.
10 Configuring GigE Vision Devices The Ethernet tab. If you are using a MacBook, you may not have the option of Jumbo frames in the MTU.
Software Configuration Software Configuration You need to have GenICam installed, but that is done for you by the Image Acquisition Toolbox. The necessary environment variables should automatically be set as part of the installation. You can optionally check to verify the following environment variables. See the examples below.
10 Configuring GigE Vision Devices Note: You do not need to install GenICam to use the GigE adaptor, because it is now included in the installation of the toolbox. However, if you are using the From Video Device block and doing code generation, you would need to install GenICam to run the generated application outside of MATLAB.
Setting Preferences Setting Preferences There are three GigE Vision related preferences in the Image Acquisition Preferences. In MATLAB, on the Home tab, in the Environment section, click Preferences > Image Acquisition. Timeout for packet acknowledgement – this is a timeout value for the time between the sending of a command (for camera discovery or control) and the time that the acknowledgement is received from the camera.
10 Configuring GigE Vision Devices Timeout for heartbeat – the camera requires that the application send a packet every so often (like a heartbeat) to keep the control connection alive. This is the setting for that packet period. Setting it too low can add unnecessary load to the computer and to the camera. Setting it too high can cause the camera to remain in use too long beyond when the toolbox attempts to relinquish control, leading to a failure to obtain control to start another acquisition.
Troubleshooting Troubleshooting For troubleshooting information for GigE Vision devices on Windows, see “Troubleshooting GigE Vision Devices on Windows” on page 16-26. For troubleshooting information for GigE Vision devices on Linux®, see “Troubleshooting GigE Vision Devices on Linux” on page 16-29. For troubleshooting information for GigE Vision devices on Mac, see “Troubleshooting GigE Vision Devices on Mac” on page 16-31.
11 Using the GigE Vision Interface • “GigE Vision Acquisition: gigecam Object vs.
11 Using the GigE Vision Interface GigE Vision Acquisition: gigecam Object vs. videoinput Object The Image Acquisition Toolbox includes a separate interface for use with GigE Vision Compliant cameras. This interface is designed for GigE Vision cameras and supports more GigE-specific functionality.
Connect to GigE Vision Cameras Connect to GigE Vision Cameras Use the gigecamlist function to return the list of available GigE Vision Compliant cameras connected to your system. The function returns a table with the following information for each camera detected: model, manufacturer, IP address, and serial number. If you plug in different cameras during the MATLAB session, the gigecamlist function returns an updated list of cameras. In this example, two cameras have been detected.
11 Using the GigE Vision Interface Set Properties for GigE Acquisition In this section... “Property Display” on page 11-4 “Set GigE Properties” on page 11-6 “Use GigE Commands” on page 11-7 Property Display One of the main advantages of using the gigecam object for image acquisition, instead of the gige adaptor with the videoinput object, is the advanced property features of GigE Vision Compliant hardware. When you create the gigecam object, the basic properties are displayed, as shown here.
Set Properties for GigE Acquisition 11-5
11 Using the GigE Vision Interface The list of available properties is specific to your camera. The display of properties is broken into categories based on GenICam categories as specified by camera manufacturers. For example, in the display shown here, you can see a set of device control properties, and a set of acquisition control properties. There are other categories not shown in this graphic, such as analog control, convolver, and image format control.
Set Properties for GigE Acquisition g = gigecam(1, 'ExposureTime', 20000, 'PixelFormat', 'Mono10') Set a Property After Creating the Object You can set or change properties any time after you create the object, using this syntax, where g is the object name. g.ExposureTime = 20000 If you want to change the Timeout from its default value of 10 seconds, to increase it to 20 seconds for example, use this syntax. g.Timeout = 20 This way of setting properties also supports both character strings and numerics.
11 Using the GigE Vision Interface Then use executeCommand to execute any of the commands found by the commands function. The command name is passed as a character string. For example, set a calibration correction. executeCommand(g, 'Correction_CalibrateGrey'); The camera is set to correct the grey calibration when you acquire images. You may have a camera that has a command to perform auto focus. With a gigecam object named gcam and a GigE command named AutoFocus.
Acquire Images from GigE Vision Cameras Acquire Images from GigE Vision Cameras In this section... “Create the gigecam Object” on page 11-9 “Acquire One Image Frame from a GigE Camera” on page 11-12 Create the gigecam Object To acquire images from a GigE Vision Compliant camera, you first use the gigecam function to create a GigE object.
11 Using the GigE Vision Interface ans = Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 'Photonofocus AG' '169.254.192.165' '022600017445' Using the gigecam function with no arguments creates the object, and connects to the single GigE Vision camera on your system.
Acquire Images from GigE Vision Cameras Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 'mvBlueCOUGER-X120aG' 'Photonofocus AG' 'MATRIX VISION GmbH' '169.254.192.165' '169.254.242.122' '022600017445' 'GX000818' Create an object, g, using the IP address of the camera. g = gigecam('169.254.242.
11 Using the GigE Vision Interface ans = Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 'mvBlueCOUGER-X120aG' 'Photonofocus AG' 'MATRIX VISION GmbH' '169.254.192.165' '169.254.242.122' '022600017445' 'GX000818' Create an object, g, using the index number.
Acquire Images from GigE Vision Cameras Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 2 'Photonofocus AG' '169.254.192.165' '022600017445' Use the gigecam function to create the object and connect it to the camera. g = gigecam g = Display Summary for gigecam: DeviceModelName: SerialNumber: IPAddress: PixelFormat: AvailablePixelFormats: Height: Width: Timeout: 'MV1-D1312-80-G2-12' '022600017445' '169.254.192.
11 Using the GigE Vision Interface closePreview(g) 7 Acquire a single image from the camera using the snapshot function, and assign it to the variable img img = snapshot(g); 8 Display the acquired image. imshow(img) 9 Clean up by clearing the object.
12 Using the Kinect for Windows Adaptor • “Important Information About the Kinect Adaptor” on page 12-2 • “Data Streams Returned by the Kinect” on page 12-4 • “Detecting the Kinect Devices” on page 12-7 • “Acquiring Image and Skeletal Data Using Kinect” on page 12-9 • “Acquiring from Color and Depth Devices Simultaneously” on page 12-23 • “Using Skeleton Viewer for Kinect Skeletal Data” on page 12-24 • “Installing the Kinect for Windows Sensor Support Package” on page 12-27
12 Using the Kinect for Windows Adaptor Important Information About the Kinect Adaptor The Kinect Adaptor lets you acquire images using a Kinect® for Windows device. Kinects are often used in automotive IVS, robotics, human-computer interaction (HCI), security systems, entertainment systems, game design, and civil engineering. They can be used for analyzing skeletons, 3D mapping, gesture recognition, human travel patterns, sports and games, etc.
Important Information About the Kinect Adaptor Kinect for Windows Sensor support package. See “Image Acquisition Support Packages for Hardware Adaptors” on page 4-2 for information about installing the adaptors. See “Installing the Kinect for Windows Sensor Support Package” on page 12-27 for information specific to installing the Kinect support package. Also, in order to use the Kinect for Windows support, you must have version 1.6 of the Kinect for Windows Runtime installed on your system.
12 Using the Kinect for Windows Adaptor Data Streams Returned by the Kinect The Kinect for Windows device returns these data streams. • Image stream (returned by the color sensor) • Depth stream (returned by the depth sensor) • Skeletal stream (returned by the depth sensor) • Audio stream (not used by the Image Acquisition Toolbox, but could be used with MATLAB audiorecorder) Image Stream The image stream returns color image data and other formats using the Kinect color sensor.
Data Streams Returned by the Kinect Format Description RawBayer_1280x960 Raw Bayer format. MONO8 frame type with resolution of 1280 x 960, frame rate of 12 frames per second, which is the maximum allowed. This format returns the raw Bayer pattern, so you can use your own algorithm to reconstruct the color image. RawBayer_640x480 Raw Bayer format. MONO8 frame type with resolution of 640 x 480, frame rate of 30 frames per second, which is the maximum allowed.
12 Using the Kinect for Windows Adaptor Skeletal Stream The skeletal stream returns skeletal data using the Kinect depth device. The skeleton frame returned contains data on the ground plane position and a time stamp. It contains the overall position of the skeleton and the 3-D position of all 20 joints (position in meters). Two skeletons are actively tracked, and another four are tracked passively.
Detecting the Kinect Devices Detecting the Kinect Devices Typically in the Image Acquisition Toolbox, each camera or image device has one DeviceID. Because the Kinect for Windows camera has two separate sensors, the color sensor and the depth sensor, the toolbox lists two DeviceIDs. If you use imaqhwinfo on the adaptor, you can see this.
12 Using the Kinect for Windows Adaptor The following shows the depth sensor, which is Device 2. info.DeviceInfo(2) ans = DefaultFormat: DeviceFileSupported: DeviceName: DeviceID: VideoInputConstructor: VideoDeviceConstructor: SupportedFormats: 'Depth_640x480' 0 'Kinect Depth Sensor' 2 'videoinput('kinect', 2)' 'imaq.VideoDevice('kinect', 2)' {'Depth_640x480' 'Depth_320x240' 'Depth_80x60'} You can use multiple Kinect cameras together.
Acquiring Image and Skeletal Data Using Kinect Acquiring Image and Skeletal Data Using Kinect In “Detecting the Kinect Devices” on page 12-7, you could see that the two sensors on the Kinect for Windows are represented by two device IDs, one for the color sensor and one of the depth sensor. In that example, Device 1 is the color sensor and Device 2 is the depth sensor.
12 Using the Kinect for Windows Adaptor Saturation = 1 Sharpness = 0.5 WhiteBalance = 2700 As you can see in the output, the color sensor has a set of device-specific properties. Device-Specific Property – Color Description Sensor Accelerometer Returns 3D vector of acceleration data for both the color and depth sensors. The data is updated while the device is running or previewing. This 1 x 3 double represents the x, y, and z values of acceleration in gravity units g (9.81m/s^2). For example, [0.06 -1.
Acquiring Image and Skeletal Data Using Kinect Device-Specific Property – Color Description Sensor AutoWhiteBalance Use to enable or disable automatic white balance setting. on (default) means that it will automatically configure white balance and the WhiteBalance property cannot be set. off means that the WhiteBalance property is settable. BacklightCompensation Configures backlight compensation modes to adjust the camera to capture images dependent on environmental conditions.
12 Using the Kinect for Windows Adaptor Device-Specific Property – Color Description Sensor CameraElevationAngle Controls the angle of the sensor lens. This is the camera angle relative to the ground. The value must be an integer property with range of -27 to 27 degrees. The default value is the last set value, since this is a sticky setting. Only set it if you want to change the angle of the camera. This property is shared with the depth sensor also. Contrast Indicates contrast level.
Acquiring Image and Skeletal Data Using Kinect Device-Specific Property – Color Description Sensor Hue Indicates hue setting. Values must be in the range -22 to 22, with a default value of 0. PowerLineFrequency Option for reducing flicker caused by the frequency of a power line. Values are Disabled, FiftyHertz, and SixtyHertz. The default is Disabled. Note that this property is only valid if AutoExposure is set to Enabled. Saturation Indicates saturation level.
12 Using the Kinect for Windows Adaptor vid2 = videoinput('kinect',2,'Depth_640x480'); 6 Look at the device-specific properties on the source device, which is the depth sensor on the Kinect. src = getselectedsource(vid2); src Display Summary for Video Source Object: General Settings: Parent = [1x1 videoinput] Selected = on SourceName = DepthSource Tag = Type = videosource Device Specific Properties: Accelerometer = [0.0 -1.0 0.
Acquiring Image and Skeletal Data Using Kinect Device-Specific Property – Depth Description Sensor [0.06 -1.00 -0.09] represents values of x as 0.06 g, y as -1.00 g, and z as -0.09 g. BodyPosture Indicates whether the tracked skeletons are standing or sitting. Values are Standing (gives 20 point skeleton data) and Seated (gives 10 point skeleton data, using joint indices 2 - 11). Standing is the default.
12 Using the Kinect for Windows Adaptor Device-Specific Property – Depth Description Sensor IREmitter Controls whether the IR emitter is on or off. Values are on and off. Initially, the default value is on. However, this is a sticky property, so the default value is the last set value. If you set it to off, it will remain off in future uses until you change the setting. An advantage of this property is that it is useful when using multiple Kinect devices to avoid interference.
Acquiring Image and Skeletal Data Using Kinect start(vid2); 8 Skeletal data is accessed as metadata on the depth stream. You can use getdata to access it. % Get the data on the object. [frame, ts, metaData] = getdata(vid2); % Look at the metadata to see the parameters in the skeletal data.
12 Using the Kinect for Windows Adaptor MetaData Description indicates the position is tracked and a 0 indicates it is not. IsSkeletonTracked This is a 1 x 6 Boolean matrix of true/ false values for the tracked state of each of the six skeletons. A 1 indicates it is tracked and a 0 indicates it is not.
Acquiring Image and Skeletal Data Using Kinect MetaData Description JointWorldCoordinates This is a 20 x 3 x 6 double matrix of x-, yand z-coordinates for 20 joints, in meters from the sensor, for the six possible skeletons, if the BodyPosture is set to Standing. If it is set to Seated, this would be a 10 x 3 x 6 double for 10 joints. See step 9 for the syntax on how to see this data.
12 Using the Kinect for Windows Adaptor MetaData Description SkeletonTrackingID This 1 x 6 integer matrix contains the tracking IDs of all six skeletons. These IDs track specific skeletons using the SkeletonsToTrack property in step 5. Tracking IDs are generated by the Kinect and change from acquisition to acquisition. This is a 1 x 1 double and represents the trigger the event is associated with if triggering is used.
Acquiring Image and Skeletal Data Using Kinect 0.0301 0.2364 0.3775 0.4075 -0.2532 -0.1869 -0.1869 -0.1969 -0.0360 0.0382 0.1096 0.1196 -0.0125 0.2775 0.5872 0.6372 -0.4392 -0.8425 -1.2941 -1.3541 -0.4436 -0.8350 -1.2114 -1.2514 2.2603 2.2117 2.2022 2.2022 2.0742 1.8432 1.8432 1.8432 2.0771 1.8286 1.5896 1.5896 The columns represent the X, Y, and Z coordinates in meters of the 20 points on skeleton 1. 11 You can optionally view the segmentation data as an image. % View the segmentation data as an image.
12 Using the Kinect for Windows Adaptor BodyPosture Joint Indices The BodyPosture property, in step 5, indicates whether the tracked skeletons are standing or sitting. Values are Standing (gives 20 point skeleton data) and Seated (gives 10 point skeleton data, using joint indices 2 - 11).
Acquiring from Color and Depth Devices Simultaneously Acquiring from Color and Depth Devices Simultaneously You can synchronize the data from the Kinect for Windows color stream and the depth stream using software manual triggering. This synchronization method example triggers both objects manually. 1 Create the objects for the color and depth sensors. Device 1 is the color sensor and Device 2 is the depth sensor.
12 Using the Kinect for Windows Adaptor Using Skeleton Viewer for Kinect Skeletal Data If you do an acquisition with a Kinect for Windows and get skeletal data, you can view the skeleton joints in this viewer. This example function displays one RGB image with skeleton joint locations overlaid on the image. 1 Create the Kinect objects and acquire image and skeletal data, as shown in “Acquiring Image and Skeletal Data Using Kinect” on page 12-9.
Using Skeleton Viewer for Kinect Skeletal Data SkeletonConnectionMap = [[1 2]; % Spine [2 3]; [3 4]; [3 5]; %Left Hand [5 6]; [6 7]; [7 8]; [3 9]; %Right Hand [9 10]; [10 11]; [11 12]; [1 17]; % Right Leg [17 18]; [18 19]; [19 20]; [1 13]; % Left Leg [13 14]; [14 15]; [15 16]]; 5 Draw the skeletons on the RGB image.
12 Using the Kinect for Windows Adaptor 12-26
Installing the Kinect for Windows Sensor Support Package Installing the Kinect for Windows Sensor Support Package With previous versions of the Image Acquisition Toolbox, the files for all of the adaptors were included in your installation. Starting with version R2014a, each adaptor is available separately through the Support Package Installer. In order to use the Image Acquisition Toolbox, you must install the adaptor that your camera uses, in this case, the Kinect for Windows Sensor support package.
12 Using the Kinect for Windows Adaptor 3 12-28 On the Select support package to install screen, select Kinect for Windows Runtime from the list.
Installing the Kinect for Windows Sensor Support Package Accept or change the Installation folder and click Next. Note: You must have write privileges for the Installation folder. 4 On the MATHWORKS AUXILIARY SOFTWARE LICENSE AGREEMENT screen, select the I accept checkbox and click Next. 5 The Third-party software licenses screen displays your choice of Image Acquisition Toolbox Support Package for Kinect for Windows Runtime.
12 Using the Kinect for Windows Adaptor Review the information, including the license agreements, and click Next. 6 12-30 On the Confirm installation screen, Support Package Installer confirms that you are installing the support package, and lists the installation location. Confirm your selection and click Install.
Installing the Kinect for Windows Sensor Support Package 7 Support Package Installer displays a progress bar while it downloads and installs the Image Acquisition Toolbox support package and third-party software. Note: If you installed the support package previously, Support Package Installer removes the files from that installation before installing the current support package. If Support Package Installer cannot remove those files automatically, it instructs you to delete the files manually.
12 Using the Kinect for Windows Adaptor 12-32 3 Under the Security subsection, uncheck Check for publisher’s certificate revocation to temporarily disable it, and click OK. 4 Run the installer again. 5 After you have installed the support package, re-enable the security option in Internet Explorer.
13 Using the Matrox Interface • “Matrox Acquisition – matroxcam Object vs videoinput Object” on page 13-2 • “Connect to Matrox Frame Grabbers” on page 13-3 • “Set Properties for Matrox Acquisition” on page 13-4 • “Acquire Images from Matrox Frame Grabbers” on page 13-6
13 Using the Matrox Interface Matrox Acquisition – matroxcam Object vs videoinput Object The Image Acquisition Toolbox includes a separate interface for use with Matrox frame grabbers. This interface is designed for Matrox hardware and supports more Matroxspecific functionality. You can continue to use the Matrox adaptor (matrox) with the videoinput object, or you can use the matroxcam object, which takes advantage of Matrox features.
Connect to Matrox Frame Grabbers Connect to Matrox Frame Grabbers Use the matroxlist function to return the list of available Matrox frame grabbers connected to your system. The function returns a cell array with model name and digitizer number for each frame grabber detected. In this example, three frame grabbers have been detected. matroxlist ans = Solios XCL (digitizer 0) Solios XCL (digitizer 1) VIO (digitizer 0) If no boards are detected, it returns an empty cell array.
13 Using the Matrox Interface Set Properties for Matrox Acquisition You cannot directly set properties for the matroxcam object in the Image Acquisition Toolbox. To set acquisition properties, use your Digitizer Configuration File (DCF) file. You can set properties in the DCF file using the Matrox Intellicam software. The DCF file contains properties relating to exposure signal, grab mode, sync signal, camera, video signal, video timing, and pixel clock.
Set Properties for Matrox Acquisition 4 You can then preview and acquire images, as described in “Acquire Images from Matrox Frame Grabbers” on page 13-6. Note: If you need to change any properties after you preview your image, you must change them in the DCF file, and then create a new object to pick up the changes. Configuring Hardware Triggering If your DCF file is configured for hardware triggering, then you must provide the trigger to acquire images.
13 Using the Matrox Interface Acquire Images from Matrox Frame Grabbers In this section... “Create the matroxcam Object” on page 13-6 “Acquire One Image Frame from a Matrox Frame Grabber” on page 13-7 Create the matroxcam Object To acquire images from a Matrox frame grabber, use the matroxcam function to create a Matrox object. Specify a frame grabber by the list order, using an index number, as the first input argument.
Acquire Images from Matrox Frame Grabbers Solios XCL (digitizer 0) Solios XCL (digitizer 1) VIO (digitizer 0) Create an object, m, using the index number and DCF file. If you want to use the second frame grabber in the list, the Solios XCL at digitizer 1, use a 2 as the index number, since it is the second camera on the list. The second argument must be the name of your DCF file, entered as a string. It must contain the fully qualified path to the file as well.
13 Using the Matrox Interface 2 Use the matroxcam function to create the object and connect it to the frame grabber. If you want to use the second frame grabber in the list, the Solios XCL at digitizer 1, use a 2 as the index number, since it is the second board on the list. The second argument must be the name and path of your DCF file, entered as a string. 3 Preview the image from the camera. preview(m) 4 You can leave the Preview window open, or close it any time.
14 Using the VideoDevice System Object • “VideoDevice System Object Overview” on page 14-2 • “Creating the VideoDevice System Object” on page 14-3 • “Using VideoDevice System Object to Acquire Frames” on page 14-5 • “Using Properties on a VideoDevice System Object” on page 14-10 • “Code Generation with VideoDevice System Object” on page 14-14
14 Using the VideoDevice System Object VideoDevice System Object Overview The Image Acquisition Toolbox introduces the VideoDevice System object™, which allows single-frame image acquisition and code generation from MATLAB. You use the imaq.VideoDevice function to create the System object. It supports the same adaptors and hardware that the videoinput object supports; however, it has different functions and properties associated with it.
Creating the VideoDevice System Object Creating the VideoDevice System Object You use the imaq.VideoDevice function to create the System object. You can specify the adaptorname, deviceid, and format at the time of object creation, or it will use defaults, as follows. Constructor Purpose obj = imaq.VideoDevice Creates a VideoDevice System object, obj, that acquires images from a specified image acquisition device.
14 Using the VideoDevice System Object Constructor Purpose invalid property name or property value is specified, the object is not created. Specifying properties at the time of object creation is optional. They can also be specified after the object is created. See “Using Properties on a VideoDevice System Object” on page 14-10 for a list of applicable properties.
Using VideoDevice System Object to Acquire Frames Using VideoDevice System Object to Acquire Frames You can use these functions with the VideoDevice System object. Function Purpose step Acquire a single frame from the image acquisition device. frame = step(obj); acquires a single frame from the VideoDevice System object, obj. Note that the first time you call step, it acquires exclusive use of the hardware and will start streaming data.
14 Using the VideoDevice System Object Function Purpose determined by the value of the VideoDevice System object ROI property. If not specified, it uses the default resolution for the device. closepreview Close live image preview window. closepreview(obj) closes the live preview window for VideoDevice System object, obj. imaqhwinfo Returns information about the object. imaqhwinfo(obj) displays information about the VideoDevice System object, obj.
Using VideoDevice System Object to Acquire Frames 5 Acquire a single frame using the step function. frame = step(vidobj); 6 Display the acquired frame. imshow(frame) 7 Release the hardware resource. release(vidobj); 8 Clear the VideoDevice System object. clear vidobj; Kinect for Windows Metadata You can return Kinect for Windows skeleton data using the VideoDevice System object on the Kinect Depth sensor. Typically in the Image Acquisition Toolbox, each camera or image device has one device ID.
14 Using the VideoDevice System Object To create a System object using the Color sensor: vidobjcolor = imaq.VideoDevice('kinect', 1); To create a System object using the Depth sensor: vidobjdepth = imaq.VideoDevice('kinect', 2); The Depth sensor returns skeleton metadata. To access this, you need to add a second output argument for the step function. The Color sensor works the same way as other devices.
Using VideoDevice System Object to Acquire Frames You can then look at both outputs. To see the image frame: imshow(imageData) To see the metadata output: metadata Note: The Kinect for Windows Depth sensor may take some seconds to be ready to begin acquiring skeletal metadata. In order to see values in the metadata output, you need to acquire multiple frames using the step function repeatedly. You can do this by using a for loop.
14 Using the VideoDevice System Object Using Properties on a VideoDevice System Object You can specify properties at the time of object creation, or they can be specified and changed after the object is created. Properties that can be used with the VideoDevice System object include: Property Description Device Device from which to acquire images. Specify the image acquisition device to use to acquire a frame. It consists of the device name, adaptor, and device ID.
Using Properties on a VideoDevice System Object Property Description shows a device-specific property for VideoDevice System object, obj. ROI Region-of-interest for acquisition. This is set to the default ROI value for the specified device, which is the maximum resolution possible for the specified format. You can change the value to change the size of the captured image.
14 Using the VideoDevice System Object Property Description BayerSensorAlignment String indicating the 2x2 sensor alignment. Specifies Bayer patterns returned by hardware. Specify the sensor alignment for Bayer demosaicing. The default value of this property is 'grbg'. Possible values are {grbg|gbrg|rggb|bggr}. Visible only if ReturnedColorSpace is set to 'bayer'. obj.BayerSensorAlignment shows the list of available sensor alignments. ReturnedDataType The returned data type of the acquired frame.
Using Properties on a VideoDevice System Object Note: This ROI value is 1-based. This differs from the videoinput object, the Image Acquisition Tool, and the From Video Device block, all of which are 0-based. To set a device-specific property, use this syntax: vidobj.DeviceProperties.
14 Using the VideoDevice System Object Code Generation with VideoDevice System Object In this section... “Using the codegen Function” on page 14-14 “Shared Library Dependencies” on page 14-14 “Usage Rules for System Objects in Generated MATLAB Code” on page 14-15 “Limitations on Using System Objects in Generated MATLAB Code” on page 14-15 Using the codegen Function The VideoDevice System object supports code generation in MATLAB via the codegen function.
Code Generation with VideoDevice System Object • Specific MathWorks shared libraries under [MATLABROOT]\bin\\ • MathWorks adaptor libraries under [MATLABROOT]\toolbox\imaq\imaqadaptors \\ specific to the device selected. You will need to add the above folders to your system path before running the generated executable outside of MATLAB. Usage Rules for System Objects in Generated MATLAB Code • Assign System objects to persistent variables. • Global variables are not supported.
14 Using the VideoDevice System Object The only System object functions supported in code generation are: • get • getNumInputs • getNumOutputs • reset • step Do not set System objects to become outputs from the MATLAB Function block. Do not pass a System object as an example input argument to a function being compiled with codegen. Do not pass a System object to functions declared as extrinsic (i.e., functions called in interpreted mode) using the coder.extrinsic function.
15 Adding Support for Additional Hardware
15 Adding Support for Additional Hardware 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. The Image Acquisition Toolbox Adaptor Kit is a C++ framework that you can use to implement an adaptor.
16 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.
16 Troubleshooting 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. 1 Verify that your image acquisition hardware is functioning properly.
DALSA Coreco IFC Hardware DALSA Coreco IFC Hardware In this section... “Troubleshooting DALSA Coreco IFC Devices” on page 16-3 “Determining the Driver Version for DALSA Coreco IFC Devices” on page 16-4 Troubleshooting DALSA Coreco IFC Devices The Image Acquisition Toolbox software supports the use of both DALSA Coreco IFC hardware and DALSA Coreco Sapera hardware. Please see the appropriate section depending on which driver your hardware uses.
16 Troubleshooting • Verify that the version is compatible with the Image Acquisition Toolbox software. For the correct driver information, check the list of 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 (www.imaging.com) to download the correct driver.
DALSA Coreco Sapera Hardware DALSA Coreco Sapera Hardware In this section... “Troubleshooting DALSA Coreco Sapera Devices” on page 16-5 “Determining the Driver Version for DALSA Coreco Sapera Devices” on page 16-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. Please see the appropriate section depending on which driver your hardware uses.
16 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 16-6. • Verify that the version is compatible with the Image Acquisition Toolbox software. For the correct driver information, check the list of supported drivers on the Image Acquisition Toolbox product page at the MathWorks Web site (www.mathworks.com/products/imaq).
Data Translation Hardware 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: 1 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.
16 Troubleshooting device driver installation. If you get error messages about missing files, insert the Imaging Omni CD into your CD-ROM drive and install the SDK.
DCAM IEEE 1394 (FireWire) Hardware on Windows DCAM IEEE 1394 (FireWire) Hardware on Windows In this section...
16 Troubleshooting dcam or winvideo adaptors. If you can connect to your camera from the toolbox but cannot access some camera features, such as hardware triggering, you might be accessing the camera through a DirectX® driver. See “Creating a Video Input Object” on page 5-9 for more information about specifying adaptors. 4 Verify that your IEEE 1394 (FireWire) camera is using the Carnegie Mellon University (CMU) DCAM driver version 6.4.6.
DCAM IEEE 1394 (FireWire) Hardware on Windows Note The CMU DCAM driver is the only DCAM driver supported by the toolbox. You cannot use vendor-supplied drivers, even if they are compliant with the DCAM specification. Installing the Driver To install the CMU DCAM driver on your system, follow this procedure: 1 Obtain the CMU DCAM driver files. The Image Acquisition Toolbox software includes the CMU DCAM installation file, 1394camera646.
16 Troubleshooting You can use this demo application to verify whether your camera is using the CMU DCAM driver. The following describes the step-by-step procedure you must perform to access a camera through this demo application. 1 Select Start > Programs > CMU 1394 Camera > 1394 Camera Demo. 2 The application opens a window, shown in the following figure. 3 From the Camera Demo application, select Camera > Check Link.
DCAM IEEE 1394 (FireWire) Hardware on Windows 5 Select Camera > Init Camera. In this step, the demo application checks the values of various camera properties. The demo application might resize itself to fit the video format of the specified camera. If you see the following dialog box message, click Yes. Note: If you are using 1394b, select Camera > 1394b Support, and then check the Maximum Speed option after choosing 1394b support.
16 Troubleshooting 7 16-14 To exit, select Stop Camera from the Camera menu and then click Exit.
Hamamatsu Hardware Hamamatsu Hardware If you are having trouble using the Image Acquisition Toolbox software with a x Hamamatsu digital camera, follow these troubleshooting steps: 1 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. • Run the application that came with your hardware and verify that you can acquire video frames. Use the exAcq.
16 Troubleshooting Matrox Hardware In this section... “Troubleshooting Matrox Devices” on page 16-16 “Determining the Driver Version for Matrox Devices” on page 16-17 Troubleshooting Matrox Devices If you are having trouble using the Image Acquisition Toolbox software with a supported Matrox frame grabber, follow these troubleshooting steps: 1 Verify that your image acquisition hardware is functioning properly.
Matrox Hardware Note: There is no difference between MIL and MIL-Lite software inside of MATLAB. They both work with Matrox Imaging devices. 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. The software version is listed on the Information tab.
16 Troubleshooting QImaging Hardware In this section... “Troubleshooting QImaging Devices” on page 16-18 “Determining the Driver Version for QImaging Devices” on page 16-19 Troubleshooting QImaging Devices If you are having trouble using the Image Acquisition Toolbox software with a supported QImaging® camera, follow these troubleshooting steps: 1 Verify that your image acquisition hardware is functioning properly.
QImaging Hardware • Verify that the version is compatible with the Image Acquisition Toolbox software. For the correct driver information, check the list of 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 QImaging Web site (www.qimaging.com) to download the correct drivers.
16 Troubleshooting National Instruments Hardware In this section... “Troubleshooting National Instruments Devices” on page 16-20 “Determining the Driver Version for National Instruments Devices” on page 16-21 Troubleshooting National Instruments Devices If you are having trouble using the Image Acquisition Toolbox software with a supported National Instruments frame grabber, follow these troubleshooting steps: 1 Verify that your image acquisition hardware is functioning properly.
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. • Verify that the version is compatible with the Image Acquisition Toolbox software.
16 Troubleshooting Point Grey Hardware In this section...
Point Grey Hardware Note: The Image Acquisition Toolbox software is compatible only with specific driver versions provided with the Point Grey 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 for Point Grey Devices” on page 16-23. • Verify that the version is compatible with the Image Acquisition Toolbox software.
16 Troubleshooting Kinect for Windows Hardware The Kinect adaptor is supported on 32-bit and 64-bit Windows. Note: The Kinect adaptor is intended for use only with the Kinect for Windows sensor. If you are having trouble using the Image Acquisition Toolbox software with a supported Kinect for Windows sensor, follow these troubleshooting steps: 1 Verify that your image acquisition hardware is functioning properly.
Kinect for Windows Hardware Troubleshooting the Support Package Installation If the setup fails, it could be caused by an internet security setting. If you get an error message such as “KINECT Setup Failed – An error occurred while installing,” try the following and then run the installer again. 1 In Internet Explorer, go to Tools > Internet Options. 2 In Internet Options, select the Advanced tab.
16 Troubleshooting GigE Vision Hardware In this section...
GigE Vision Hardware For more information on this, see Step 3 in “Installation of GigE Vision Cameras and Drivers on Windows” on page 10-4. 5 Make sure the Ethernet card is configured properly. For more information on this, see “Network Hardware Configuration Notes” on page 10-3 and “Network Adaptor Configuration Notes” on page 10-4. Also, if you have multiple cameras connected to multiple Ethernet cards, you cannot have them all set to automatic IP configuration.
16 Troubleshooting http://www.mathworks.com/support/solutions/en/data/1-F36R0R/index.html 8 If you are able to start acquisition without error but do not receive any frames, and if you are using a larger PacketSize, make sure that your hardware and the network between the computer and the camera support jumbo frames, and also that your Ethernet card driver is set to allow them at the size that you are attempting to use. 9 The toolbox attaches the block ID (frame ID) as metadata to the frame.
GigE Vision Hardware Troubleshooting GigE Vision Devices on Linux If you are having trouble using the Image Acquisition Toolbox software with a GigE Vision camera on a Linux machine, using the toolbox's gige adaptor, follow these troubleshooting steps: 1 With previous versions of the Image Acquisition Toolbox, the files for all of the adaptors were included in your installation. Starting with version R2014a, each adaptor is available separately through the Support Package Installer.
16 Troubleshooting “Block 23 is being dropped because packets are unavailable for resend” and it does not mention buffer size, it is likely that packets are being dropped due to overload of the CPU. To lower the CPU load, raise the value of the PacketSize device-specific (source) property. In order to do this, you must be using hardware that supports jumbo frames. You might also want to calculate and set the PacketDelay device-specific (source) property.
GigE Vision Hardware frames, you can check the metadata – if the first frame's block ID is not 1, you may have some missing frames. For example, use this command in MATLAB: [d t m]=getdata(vid,2); m(1) The answer will include the Block ID and the FrameNumber. 10 Run the imaqsupport function for further troubleshooting information.
16 Troubleshooting For more information on this, see “Network Hardware Configuration Notes” on page 10-3 and “Network Adaptor Configuration Notes” on page 10-4. Also, if you have multiple cameras connected to multiple Ethernet cards, you cannot have them all set to automatic IP configuration. You must specify the IP address for each card and each card must be on a different subnet. 5 Examine the connectivity of your device separate from using the Image Acquisition Toolbox.
GigE Vision Hardware 8 If you receive an error that says a block or frame is being dropped because a packet is unavailable for resend, one likely cause is that the buffer size of the socket could not be set to the reported value, for example 1000000. See your system administrator about using sysctl for net.core.rmem_max. For example, the system administrator could try: sysctl -w net.inet.udp.
16 Troubleshooting GenICam GenTL Hardware Troubleshooting GenICam GenTL Hardware If you are having trouble using the Image Acquisition Toolbox software with a GenICam GenTL camera driver using the toolbox's gentl adaptor, follow these troubleshooting steps: 1 With previous versions of the Image Acquisition Toolbox, the files for all of the adaptors were included in your installation. Starting with version R2014a, each adaptor is available separately through the Support Package Installer.
GenICam GenTL Hardware command and so sometimes after plugging in a new camera, it will not be found. Using the toolbox’s gige adaptor first can resolve this. 8 You can also look at producers in other vendor software. For example, Leutron Vision uses a program called Simplon Explorer. Using this program you can see what producers are installed and what cameras are connected. You can double-click on a camera within the Simplon Explorer to control it.
16 Troubleshooting Windows Video Hardware In this section... “Troubleshooting Windows Video Devices” on page 16-36 “Determining the Microsoft DirectX Version” on page 16-37 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: 1 Verify that your image acquisition hardware is functioning properly.
Windows Video Hardware • Verify that the version is compatible with the Image Acquisition Toolbox software. For the correct driver information, check the list of 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 hardware manufacturer's Web site for the correct drivers.
16 Troubleshooting In the DirectX Diagnostic Tool, the Microsoft DirectX version is listed on the System tab under the System Information section.
Linux Video Hardware Linux Video Hardware Troubleshooting Linux Video Devices If you have trouble using the Image Acquisition Toolbox software with a supported Linux Video acquisition device, follow these recommended troubleshooting steps: 1 Verify that your image acquisition hardware functions properly and that you have permission to access it. Be sure that your system and login have the proper permissions to access the hardware. See your system administrator if you need help.
16 Troubleshooting on the Image Acquisition Toolbox product page at the MathWorks Web site (www.mathworks.com/products/imaq). 4 The Linux Video adaptor only supports Video 4 Linux 2 compatible devices. However, there is a library that might make Video 4 Linux 1 devices work with the toolbox. The libv4l package provides a library that provides compatibility between the different versions of Video 4 Linux. To try this, start MATLAB with the following command: LD_PRELOAD=/usr/lib/libv4l/v4l1compat.
Linux DCAM IEEE 1394 Hardware Linux DCAM IEEE 1394 Hardware Troubleshooting Linux DCAM Devices If you are having trouble using the Image Acquisition Toolbox software with a supported Linux DCAM IEEE 1394 hardware acquisition device, follow these recommended troubleshooting steps: 1 Verify that your IEEE 1394 (FireWire) camera can be accessed through the dcam adaptor. • Make sure the camera is compliant with the IIDC 1394-based Digital Camera (DCAM) specification.
16 Troubleshooting Macintosh Video Hardware Troubleshooting Macintosh Video Devices If you are having trouble using the Image Acquisition Toolbox software with a supported Macintosh video acquisition device, follow these recommended troubleshooting steps: 1 Verify that your image acquisition hardware is functioning properly. You can verify that your hardware is functioning properly by running the WebCam application that came with OSX, for example, Photo Booth or iMovie.
Macintosh DCAM IEEE 1394 Hardware Macintosh DCAM IEEE 1394 Hardware Troubleshooting Macintosh DCAM Devices If you are having trouble using the Image Acquisition Toolbox software with a supported Macintosh DCAM IEEE 1394 hardware acquisition device, follow these recommended troubleshooting steps: 1 Verify that your IEEE 1394 (FireWire) camera can be accessed through the dcam adaptor. • Make sure the camera complies with the IIDC 1394-based Digital Camera (DCAM) specification.
16 Troubleshooting Video Preview Window Troubleshooting When previewing the video stream, if you encounter a problem, try one of the following solutions. Problem Possible Solutions Video Preview window stops running. • Close the preview window and reopen it. • 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. Video Preview window displays blank, gray window.
Contacting MathWorks and Using the imaqsupport Function Contacting MathWorks and Using the imaqsupport Function If you need support from MathWorks, visit our Web site at http://www.mathworks.com/ support/. Before contacting MathWorks, you should run the imaqsupport function.
17 Functions — Alphabetical List
17 Functions — Alphabetical List clear Clear image acquisition object from MATLAB workspace Syntax clear obj Description clear obj removes the image acquisition object obj from the MATLAB workspace. obj can be either a video input object or a video source object. It is important to note that if you clear a video input object that is running (the Running property is set to 'on'), the object continues executing. You can restore cleared objects to the MATLAB workspace with the imaqfind function.
closepreview closepreview Close Video Preview window Syntax closepreview(obj) closepreview Description closepreview(obj) stops the image acquisition object obj from previewing and, if the default Video Preview window was used, closes the window. closepreview stops all image acquisition objects from previewing and, for all image acquisition objects that used the default Video Preview window, closes the windows.
17 Functions — Alphabetical List commands List of commands available for GigE Vision camera Syntax commands(g) Description commands(g) lists the available commands for the GigE camera g, where g is the object created using the gigecam function. The output depends on the commands that are supported by your specific hardware. Examples List Commands Available for GigE Camera The commands function tells you what commands are available for your camera to use.
commands Get the list of supported commands from the camera.
17 Functions — Alphabetical List The list shows the commands that the camera supports. You can then use the executeCommand function to execute any of these commands.
delete delete Remove image acquisition object from memory Syntax delete(obj) Description delete(obj) removes obj, an image acquisition object or array of image acquisition objects, from memory. Use delete to free memory at the end of an image acquisition session. If obj is an array of image acquisition objects and one of the objects cannot be deleted, the delete function deletes the objects that can be deleted and returns a warning. When obj is deleted, it becomes invalid and cannot be reused.
17 Functions — Alphabetical List disp Display method for image acquisition objects Syntax obj disp(obj) Description obj displays summary information for image acquisition object obj. disp(obj) displays summary information for image acquisition object obj. If obj is an array of image acquisition objects, disp outputs a table of summary information about the image acquisition objects in the array.
disp This example shows the summary information displayed for an array of video input objects.
17 Functions — Alphabetical List executeCommand Execute command on GigE Vision camera Syntax executeCommand(g, 'commandname') Description executeCommand(g, 'commandname') executes the specified command for the GigE camera g, where g is the object created using the gigecam function, and 'commandname' is the name of the command to execute. Use the commands function to get the list of available commands for your camera.
executeCommand Get the list of supported commands from the camera.
17 Functions — Alphabetical List Execute a command, such as setting a calibration correction. executeCommand(g, 'Correction_CalibrateGrey'); Input Arguments commandname — Name of GigE camera command to execute character string Name of command you want to execute on your GigE camera, specified as a character string. Use the commands function to get the list of available commands for your camera. Then use executeCommand to execute any of the available commands.
executeCommand See Also commands | gigecam | gigecamlist | snapshot 17-13
17 Functions — Alphabetical List flushdata Remove data from memory buffer used to store acquired image frames Syntax flushdata(obj) flushdata(obj,mode) Description flushdata(obj) removes all the data from the memory buffer used to store acquired image frames. obj can be a single video input object or an array of video input objects.
get get Return image acquisition object properties Syntax get(obj) V = get(obj) V = get(obj,PropertyName) Description get(obj) displays all property names and their current values for image acquisition object obj. V = get(obj) returns a structure, V, in which each field name is the name of a property of obj and each field contains the value of that property. V = get(obj,PropertyName) returns the value of the property specified by PropertyName for image acquisition object obj.
17 Functions — Alphabetical List Instead of using get to query individual property values, you should use dot notation. So for example, instead of this: get(vid, 'FramesPerTrigger') You should use this syntax: vid.
getdata getdata Acquired image frames to MATLAB workspace Syntax data = getdata(obj) data = getdata(obj,n) data = getdata(obj,n,type) data = getdata(obj,n,type,format) [data,time] = getdata(...) [data, time, metadata] = getdata(...) Description data = getdata(obj) returns data, which contains the number of frames specified in the FramesPerTrigger property of the video input object obj. obj must be a 1-by-1 video input object.
17 Functions — Alphabetical List data = getdata(obj,n,type) returns n frames of data associated with the video input object obj, where type is one of the text strings in the following table that specify the data type used to store the returned data. Type String Data Type 'uint8' Unsigned 8-bit integer 'uint16' Unsigned 16-bit integer 'uint32' Unsigned 32-bit integer 'single' Single precision 'double' Double precision 'native' Uses native data type. This is the default.
getdata information about the corresponding frame in data.
17 Functions — Alphabetical List delete(obj); See Also getsnapshot | peekdata | propinfo | imaqhelp | imaqmontage 17-20
getselectedsource getselectedsource Return currently selected video source object Syntax src = getselectedsource(obj) Description src = getselectedsource(obj) searches all the video source objects associated with the video input object obj and returns the video source object, src, that has the Selected property value set to 'on'. To select a source for acquisition, use the SelectedSourceName property of the video input object. obj must be a 1-by-1 video input object.
17 Functions — Alphabetical List getsnapshot Immediately return single image frame Syntax frame = getsnapshot(obj) [frame, metadata] = getsnapshot(obj) Description frame = getsnapshot(obj) immediately returns one single image frame, frame, from the video input object obj. The frame of data returned is independent of the video input object FramesPerTrigger property and has no effect on the value of the FramesAvailable or FramesAcquired property. The object obj must be a 1-by-1 video input object.
getsnapshot Note If obj is running but not logging, and has been configured with a hardware trigger, a timeout error will occur. To interrupt the getsnapshot function and return control to the MATLAB command line, issue the ^C (Ctrl+C) command. Examples Create a video input object. obj = videoinput('matrox', 1); Acquire and display a single frame of data. frame = getsnapshot(obj); image(frame); Remove the video input object from memory.
17 Functions — Alphabetical List gigecam Create gigecam object to acquire images from GigE Vision cameras Syntax g g g g = = = = gigecam gigecam('IPAddress') gigecam(devicenumber) gigecam('serialnumber') Description g = gigecam creates the gigecam object g and connects to the single GigE Vision camera on your system.
gigecam with no input argument, it creates the object and connects it to the first camera it finds listed in the output of the gigecamlist function. Use the gigecamlist function to ensure that MATLAB is discovering your camera. gigecamlist ans = Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 'Photonofocus AG' '169.254.192.165' '022600017445' Create an object, g.
17 Functions — Alphabetical List gigecamlist ans = Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 'mvBlueCOUGER-X120aG' 'Photonofocus AG' 'MATRIX VISION GmbH' '169.254.192.165' '169.254.242.122' '022600017445' 'GX000818' Create an object, g, using the IP address of the camera. You can also create the object in this same way using the serial number.
gigecam ans = Model Manufacturer IPAddress SerialNumber ____________________ ___________________ _______________ ______________ 'MV1-D1312-80-G2-12' 'mvBlueCOUGER-X120aG' 'Photonofocus AG' 'MATRIX VISION GmbH' '169.254.192.165' '169.254.242.122' '022600017445' 'GX000818' Create an object, g, using the index number. g = gigecam(2) g = Display Summary for gigecam: DeviceModelName: SerialNumber: IPAddress: PixelFormat: AvailablePixelFormats: 'mvBlueCOUGER-X120aG' 'GX000818' '169.254.242.
17 Functions — Alphabetical List with that address. You can see the IP address for your camera in the list returned by the gigecamlist function. Example: g = gigecam('169.254.192.165') Data Types: char devicenumber — Device number of your camera numeric scalar Device number of your camera, specified as a numeric scalar. This number identifies a particular camera by its index order. It creates the object corresponding to that index and connects it to that camera.
gigecam See Also commands | executeCommand | gigecamlist | snapshot 17-29
17 Functions — Alphabetical List gigecamlist List of GigE Vision cameras connected to your system Syntax gigecamlist Description gigecamlist returns a list of available GigE Vision Compliant cameras connected to your system, with model, manufacturer, IP address, and serial number. If the camera has a user-defined name, that name is displayed. If you plug in different cameras during the same MATLAB session, then the gigecamlist function returns an updated list of cameras.
imaqfind imaqfind 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 imaqfind returns an array containing all the video input objects that exist in memory. If only a single video input object exists in memory, imaqfind displays a detailed summary of that object.
17 Functions — Alphabetical List imaqfind does not find a match if you specify 'myobject'. Note, however, that searches for properties that have an enumerated list of possible values are not case sensitive. For example, imaqfind will find an object with a Running property value of 'Off' or 'off'. Use the get function to determine the exact spelling of a property value. Examples To illustrate various imaqfind syntaxes, first create two video input objects.
imaqhelp imaqhelp Image acquisition object function and property help Syntax imaqhelp imaqhelp(Name) imaqhelp(obj) imaqhelp(obj,Name) out = imaqhelp(...) Description imaqhelp provides a complete listing of image acquisition object functions. imaqhelp(Name) provides online help for the function or property specified by the text string Name. imaqhelp(obj) displays a listing of functions and properties for the image acquisition object obj along with the online help for the object's constructor.
17 Functions — Alphabetical List imaqhelp('videoinput') out = imaqhelp('videoinput'); imaqhelp getsnapshot imaqhelp LoggingMode Getting property help with device-specific information.
imaqhwinfo imaqhwinfo Information about available image acquisition hardware Syntax out out out out out out = = = = = = imaqhwinfo imaqhwinfo(adaptorname) imaqhwinfo(adaptorname,field) imaqhwinfo(adaptorname, deviceID) imaqhwinfo(obj) imaqhwinfo(obj,field) Description out = imaqhwinfo returns out, a structure that contains information 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.
17 Functions — Alphabetical List name, device name, video resolution, native data type, and device driver name and version. If obj is an array of device objects, then out is a 1-by-n cell array of structures where n is the length of obj. out = imaqhwinfo(obj,field) returns the information in the field specified by field for the device object obj. field can be a single field name or a cell array of field names. out is an m-by-n cell array where m is the length of obj and n is the length of field.
imaqhwinfo dev_info = imaqhwinfo('winvideo', 1) dev_info = DefaultFormat: DeviceFileSupported: DeviceName: DeviceID: VideoInputConstructor: VideoDeviceConstructor: SupportedFormats: 'RGB555_128x96' 0 'IBM PC Camera' 1 'videoinput('winvideo', 1)' 'imaq.VideoDevice('winvideo', 1)' {1x34 cell} This example gets information about the device associated with a particular video input object.
17 Functions — Alphabetical List imaqmem Limit memory or display memory usage for Image Acquisition Toolbox software Syntax mem = imaqmem imaqmem(field) imaqmem(limit) Description mem = imaqmem returns a structure containing the following fields: Field Description MemoryLoad Number between 0 and 100 that gives a general idea of current memory utilization. TotalPhys Total number of bytes of physical memory. AvailPhys Number of bytes of physical memory currently available.
imaqmem Field Description FrameMemoryUsed Number of bytes currently allocated by the Image Acquisition Toolbox software. imaqmem(field) returns information for the field specified by the text string field. imaqmem(limit) configures the frame memory limit, in bytes, for the Image Acquisition Toolbox software. limit is used to determine the maximum amount of memory the toolbox can use for logging image frames.
17 Functions — Alphabetical List TotalPhys: AvailPhys: TotalPageFile: AvailPageFile: TotalVirtual: AvailVirtual: FrameMemoryLimit: FrameMemoryUsed: 263766016 37306368 643878912 391446528 2.1474e+009 1.6307e+009 38313984 0 Retrieve information about a specific field returned by imaqmem. memlimit = imaqmem('FrameMemoryLimit') memlimit = 38313984 Specify the amount of memory available for the toolbox to log image frames (FrameMemoryLimit).
imaqmontage imaqmontage Sequence of image frames as montage Syntax imaqmontage(frames) imaqmontage(obj) imaqmontage(...,CLIM) imaqmontage(..., 'CLim', CLIM, 'Parent', PARENT) h = imaqmontage(...) Description imaqmontage(frames) displays a montage of image frames in a MATLAB figure window using the imagesc function. frames can be any data set returned by getdata, peekdata, or getsnapshot.
17 Functions — Alphabetical List obj = videoinput('matrox', 1); Initiate an acquisition and access the logged data. start(obj); data = getdata(obj); Create an axes object. a = axes; Display each image frame acquired on axes a. imaqmontage(data, 'Parent', a); Remove the video input object from memory.
imaqreset imaqreset Disconnect and delete all image acquisition objects Syntax imaqreset Description imaqreset deletes any image acquisition objects that exist in memory and unloads all adaptors loaded by the toolbox. As a result, the image acquisition hardware is reset. imaqreset is the image acquisition command that returns MATLAB to the known state of having no image acquisition objects and no loaded image acquisition adaptors.
17 Functions — Alphabetical List imaqtool Launch Image Acquisition Tool Syntax imaqtool imaqtool(file) Description imaqtool launches an interactive GUI to allow you to explore, configure, and acquire data from your installed and supported image acquisition devices. The functionality of the Image Acquisition Toolbox software is available in this desktop application. You connect directly to your hardware in the tool and can preview and acquire image data.
imaq.VideoDevice imaq.VideoDevice Acquire one frame at a time from video device Syntax obj = imaq.VideoDevice obj = imaq.VideoDevice(adaptorname) obj = imaq.VideoDevice(adaptorname, deviceid) obj = imaq.VideoDevice(adaptorname, deviceid, format) obj = imaq.VideoDevice(adaptorname, deviceid, format, P1, V1, ...) frame = step(obj) [frame metadata] = step(obj) Description The VideoDevice System object allows single-frame image acquisition and code generation from MATLAB. You use the imaq.
17 Functions — Alphabetical List video format supported by the device or a device configuration file (also known as a camera file). obj = imaq.VideoDevice(adaptorname, deviceid, format, P1, V1, ...) Creates a VideoDevice System object, obj, with the specified property values. If an invalid property name or property value is specified, the object is not created. Specifying properties at the time of object creation is optional. They can also be specified after the object is created.
imaq.VideoDevice Property Description DeviceFile Name of file specifying video format. This property is only visible when VideoFormat is set to 'From device file'. DeviceProperties Object containing properties specific to the image acquisition device. ROI Region-of-interest for acquisition. This is set to the default ROI value for the specified device, which is the maximum resolution possible for the specified format. You can change the value to change the size of the captured image.
17 Functions — Alphabetical List Property Description BayerSensorAlignment String indicating the 2x2 sensor alignment. Specifies Bayer patterns returned by hardware. Specify the sensor alignment for Bayer demosaicing. The default value of this property is 'grbg'. Possible values are {grbg|gbrg|rggb|bggr}. Visible only if ReturnedColorSpace is set to 'bayer'. ReturnedDataType The returned data type of the acquired frame. The default ReturnedDataType is single.
imaq.VideoDevice Function Purpose release Release VideoDevice resources and allow property value changes. release(obj) releases system resources (such as memory, file handles, or hardware connections) of System object, obj, and allows all its properties and input characteristics to be changed. isLocked Returns a value that indicates if the VideoDevice resource is locked. (Use release to unlock.
17 Functions — Alphabetical List Function Purpose imaqhwinfo Returns information about the object. imaqhwinfo(obj) displays information about the VideoDevice System object, obj. Examples Construct a VideoDevice System object associated with the Winvideo adaptor with device ID of 1. vidobj = imaq.VideoDevice('winvideo', 1); Set an object-level property, such as ReturnedColorSpace. The syntax for an objectlevel property uses the object name, property name, and property value. vidobj.
islogging islogging Determine whether video input object is logging Syntax bool = islogging(obj) Description bool = islogging(obj) returns true if the video input object obj is logging data, otherwise false. A video input object is logging if the value of its Logging property is set to 'on'. If obj is an array of video input objects, bool is a logical array where each element in bool represents the corresponding element in obj.
17 Functions — Alphabetical List 1 Create a second video input object. vid2 = videoinput('winvideo'); Start one of the video input objects again, such as vid, and use islogging to determine which of the two objects is logging.
isrunning isrunning Determine whether video input object is running Syntax bool = isrunning(obj) Description bool = isrunning(obj) returns true if the video input object obj is running, otherwise false. A video input object is running if the value of its Running property is set to 'on'. If obj is an array of video input objects, bool is a logical array where each element in bool represents the corresponding element in obj.
17 Functions — Alphabetical List Use isrunning to determine which of the two objects is running.
isvalid isvalid Determine whether image acquisition object is associated with image acquisition device Syntax bool = isvalid(obj) Description bool = isvalid(obj) returns true if the video input object obj is valid, otherwise false. An object is an invalid image acquisition object if it is no longer associated with any hardware; that is, the object was deleted using the delete function. If this is the case, obj should be cleared from the workspace.
17 Functions — Alphabetical List load Load image acquisition object into MATLAB workspace Syntax load filename load filename obj1 obj2 ... S = load(filename,obj1,obj2,...) Description load filename returns all variables from the MAT-file filename to the MATLAB workspace. load filename obj1 obj2 ... returns the specified image acquisition objects (obj1, obj2, etc.) from the MAT-file specified by filename to the MATLAB workspace. S = load(filename,obj1,obj2,...
matroxcam matroxcam Create matroxcam object to acquire images from Matrox frame grabbers Syntax m = matroxcam(devicenumber, 'DCFfilename') Description m = matroxcam(devicenumber, 'DCFfilename') creates a matroxcam object m, where devicenumber is a numeric scalar value that identifies a particular device by its index number and DCFfilename is the name and fully qualified path of your Matrox DCF file, and connects it to that frame grabber.
17 Functions — Alphabetical List Create an object, m, using the index number. In this example, for the Solios XCL at digitizer 1, use a 2 as the index number, since it is the second device on the list. The second argument must be the name of your DCF file, entered as a string. It must contain the fully qualified path to the file as well. In this example, the DCF file is named mycam.dcf. m = matroxcam(2, 'C:\Drivers\Solios\dcf\XCL\Basler\A404K\mycam.
matroxcam Name of your DCF file, specified as a character string. The Digitizer Configuration File (DCF) is used to set acquisition properties and is configured using the Matrox Intellicam software. The DCF file contains properties relating to exposure signal, grab mode, sync signal, camera, video signal, video timing, and pixel clock. Once you have configured these properties in your DCF file, you create the matroxcam object using that file as an input argument.
17 Functions — Alphabetical List matroxlist List of Matrox frame grabbers connected to your system Syntax matroxlist Description matroxlist returns a list of available Matrox frame grabbers connected to your system, with model name and digitizer number. If no boards are detected, it returns an empty cell array. Examples Display List of Matrox Frame Grabbers The output of matroxlist shows any Matrox frame grabbers connected to your system.
matroxlist See Also closepreview | matroxcam | preview | snapshot 17-61
17 Functions — Alphabetical List obj2mfile Convert video input objects to MATLAB code Syntax obj2mfile(obj,filename) obj2mfile(obj,filename,syntax) obj2mfile(obj,filename,syntax,mode) obj2mfile(obj,filename,syntax,mode,reuse) Description obj2mfile(obj,filename) converts the video input object obj into an M-file with the name specified by filename. The M-file contains the MATLAB code required to create the object and set its properties. obj can be a single video input object or an array of objects.
obj2mfile obj2mfile(obj,filename,syntax) converts obj to the equivalent MATLAB code where syntax specifies how obj2mfile assigns values to properties of the object. syntax can be either of the following text strings. The default value is enclosed in braces ({}). String Description {'set'} obj2mfile uses the set function when specifying property values. 'dot' obj2mfile uses subscripted assignment (dot notation) when specifying property values.
17 Functions — Alphabetical List Examples Create a video input object. vidobj = videoinput('winvideo', 1, 'RGB24_640x480'); Configure several properties of the video input object. vidobj.FramesPerTrigger = 100; vidobj.FrameGrabInterval = 2; vidobj.Tag = 'CAM1'; Retrieve the selected video source object associated with the video input object. src = getselectedsource(vidobj); Configure the properties of the video source object. src.Contrast = 85; src.Saturation = 125; Save the video input object.
peekdata peekdata Most recently acquired image data Syntax data = peekdata(obj,frames) Description data = peekdata(obj,frames) returns data containing the latest number of frames specified by frames. If frames is greater than the number of frames currently acquired, all available frames are returned with a warning message stating that the requested number of frames was not available. obj must be a 1-by-1 video input object.
17 Functions — Alphabetical List The behavior of peekdata depends on the settings of the Running and the Logging properties. Running Logging Object State Result On Off The object has been started peekdata returns a single frame but is waiting for a trigger. of data and issues a warning, if you (TriggerType is set to 'manual' requested more than one frame. or 'hardware'). No data has been acquired so none is available.
preview preview Preview of live video data Syntax preview(obj) preview(obj,himage) himage = preview(...) Description preview(obj) creates a Video Preview window that displays live video data for video input object obj. The window also displays the timestamp and video resolution of each frame, and the current status of obj. The Video Preview window displays the video data at 100% magnification (one screen pixel represents one image pixel).
17 Functions — Alphabetical List The Video Preview window remains active until it is either stopped using stoppreview or closed using closepreview. If you delete the object, by calling delete(obj), the Video Preview window stops previewing and closes automatically. preview(obj,himage) displays live video data for video input object obj in the image object specified by the handle himage.
preview 14-, or 16-bit data. The Preview window display supports these higher bit-depth cameras. However, larger bit data is scaled to 8-bit for the purpose of displaying previewed data. If you need the full resolution of the data, use the getsnapshot or getdata functions. Custom Update Function preview creates application-defined data for the image object, himage, assigning it the name 'UpdatePreviewWindowFcn' and setting its value to an empty array ([]).
17 Functions — Alphabetical List The event structure contains the following fields: Field Description Data Current image frame specified as an H-by-W-by-B 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 NumberOfBands property. Resolution String specifying current image width and height, as defined by the ROIPosition property.
propinfo propinfo Property characteristics for image acquisition objects Syntax out = propinfo(obj) out = propinfo(obj,PropertyName) Description out = propinfo(obj) returns the structure out whose field names are the names of all the properties supported by obj. obj must be a 1-by-1 image acquisition object. The value of each field is a structure containing the fields shown below. Field Name Description Type Data type of the property.
17 Functions — Alphabetical List Examples Create the video input object vid. vid = videoinput('winvideo',1); Capture all property information for all properties. out = propinfo(vid); Access property information for a particular property.
save save Save image acquisition objects to MAT-file Syntax save filename save filename obj1 obj2 ... save(filename,obj1,obj2,...) Description save filename saves all variables in the MATLAB workspace to the MAT-file filename. If filename does not include a file extension, save appends the .MAT extension to the filename. save filename obj1 obj2 ... saves the specified image acquisition objects (obj1, obj2, etc.) to the MAT-file filename. save(filename,obj1,obj2,...
17 Functions — Alphabetical List save fname obj obj.
set set 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 set(obj) displays property names and any enumerated values for all configurable properties of image acquisition object obj. obj must be a single image acquisition object.
17 Functions — Alphabetical List acquisition object obj. You can specify multiple property name/property value pairs in a single statement. obj can be a single image acquisition object or a vector of image acquisition objects, in which case set configures the property values for all the image acquisition objects specified. set(obj,S) configures the properties of obj with the values specified in S, where S is a structure whose field names are object property names.
snapshot snapshot Acquire single image frame from GigE Vision camera Syntax img = snapshot(g); Description img = snapshot(g); acquires the current frame as a single image from the GigE camera g and assigns it to the variable img. If you call snapshot in a loop, then it returns a new frame each time. The returned image is based on the Pixel Format of your camera. snapshot uses the camera’s default resolution or another resolution that you specify using the Height and Width properties, if available.
17 Functions — Alphabetical List 'MV1-D1312-80-G2-12' 'Photonofocus AG' '169.254.192.165' '022600017445' Use the gigecam function to create the object and connect it to the camera. g = gigecam Preview the image from the camera. preview(g) The preview window displays live video stream from your camera. If you change a property while previewing, then the preview dynamically updates, and the image reflects the property change. Close the preview.
snapshot clear g See Also commands | executeCommand | gigecam | gigecamlist 17-79
17 Functions — Alphabetical List snapshot Acquire single image frame from Matrox frame grabber Syntax img = snapshot(m); [img, ts] = snapshot(m); Description img = snapshot(m); acquires the current frame as a single image from the Matrox frame grabber m and assigns it to the variable img. If you call snapshot in a loop, then it returns a new frame each time. Note: The snapshot function is for use only with the matroxcam object.
snapshot Solios XCL (digitizer 0) Solios XCL (digitizer 1) VIO (digitizer 0) Use the matroxcam function to create the object and connect it to the frame grabber. If you want to use the second frame grabber in the list, the Solios XCL at digitizer 1, use a 2 as the index number, since it is the second board on the list. The second argument must be the name and path of your DCF file, entered as a string. m = matroxcam(2, 'C:\Drivers\Solios\dcf\XCL\Basler\A404K\mycam.
17 Functions — Alphabetical List snapshot function as you normally would, as shown in this example, and then perform the hardware trigger to acquire the frame. When you call the snapshot function with hardware triggering set, it will not timeout as it normally would. Therefore, the MATLAB command-line will be blocked until you perform the hardware trigger.
start start Obtain exclusive use of image acquisition device Syntax start(obj) Description start(obj) obtains exclusive use of the image acquisition device associated with the video input object obj 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. obj can either be a 1-by-1 video input object or an array of video input objects. Data logging is controlled with the TriggerType property.
17 Functions — Alphabetical List An image acquisition object stops running when one of the following conditions is met: • The stop function is issued. • The requested number of frames is acquired. This occurs when FramesAcquired = FramesPerTrigger * (TriggerRepeat + 1) where FramesAcquired, FramesPerTrigger, and TriggerRepeat are properties of the video input object. • A run-time error occurs. • The object's Timeout value is reached.
stop stop Stop video input object Syntax stop(obj) Description stop(obj) halts an acquisition associated with the video input object obj. obj can be either a single video input object or an array of video input objects.
17 Functions — Alphabetical List obj.
stoppreview stoppreview Stop previewing video data Syntax stoppreview(obj) Description stoppreview(obj) stops the previewing of video data from image acquisition object obj. To restart previewing, call preview again. Examples Create a video input object and open a Video Preview window. vid = videoinput('winvideo',1); preview(vid) Stop previewing video data. stoppreview(vid); Restart previewing.
17 Functions — Alphabetical List trigger Initiate data logging Syntax trigger(obj) Description trigger(obj) initiates data logging for the video input object obj. obj can be either a single video input object or an array of video input objects.
triggerconfig triggerconfig Configure video input object trigger properties Syntax triggerconfig(obj,type) triggerconfig(obj,type,condition) triggerconfig(obj,type,condition,source) config = triggerconfig(obj) triggerconfig(obj,config) Description triggerconfig(obj,type) configures the value of the TriggerType property of the video input object obj to the value specified by the text string type. For a list of valid TriggerType values, use triggerinfo(obj).
17 Functions — Alphabetical List names of config are TriggerType, TriggerCondition, and TriggerSource. Each field contains the current value of the object's property. triggerconfig(obj,config) configures the TriggerType, TriggerCondition, and TriggerSource property values for video input object obj using config, a MATLAB structure with field names TriggerType, TriggerCondition, and TriggerSource, each containing the desired property value. Examples Example 1 Construct a video input object.
triggerconfig Pass one of the configurations to the triggerconfig function. triggerconfig(vid,config(2)); Remove video input object from memory.
17 Functions — Alphabetical List triggerinfo Provide information about available trigger configurations Syntax triggerinfo(obj) triggerinfo(obj,type) config = triggerinfo(...) Description triggerinfo(obj) displays all available trigger configurations for the video input object obj. obj can only be a 1-by-1 video input object. triggerinfo(obj,type) displays the available trigger configurations for the specified TriggerType, type, for the video input object obj.
triggerinfo 1 Create a video input object. vid = videoinput('winvideo'); 2 Get information about the available trigger configurations for this object. config = triggerinfo(vid) config = 1x2 struct array with fields: TriggerType TriggerCondition TriggerSource 3 View one of the trigger configurations returned by triggerinfo.
17 Functions — Alphabetical List videoinput Create video input object Syntax obj obj obj obj = = = = videoinput(adaptorname) videoinput(adaptorname,deviceID) videoinput(adaptorname,deviceID,format) videoinput(adaptorname,deviceID,format,P1,V1,...) Description obj = videoinput(adaptorname) constructs the video input object obj. A video input object represents the connection between MATLAB and a particular image acquisition device.
videoinput obj = videoinput(adaptorname,deviceID,format,P1,V1,...) creates a video input object obj with the specified property values. If an invalid property name or property value is specified, the object is not created. The property name and property value pairs can be in any format supported by the set 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 imaqhelp function.
17 Functions — Alphabetical List More About Tips The toolbox chooses the first available video source object as the selected source and specifies this video source object's name in the object's SelectedSourceName property. Use getselectedsource(obj) to access the video source object that is used for acquisition.
wait wait Wait until image acquisition object stops running or logging Syntax wait(obj) wait(obj,waittime) wait(obj,waittime,state) Description wait(obj) blocks the MATLAB command line until the video input object obj stops running (Running = 'off'). obj can be either a single video input object or an array of video input objects. When obj is an array of objects, the wait function waits until all objects in the array stop running. If obj is not running or is an invalid object, wait returns immediately.
17 Functions — Alphabetical List An image acquisition object stops running or logging when one of the following conditions is met: • The stop function is issued. • The requested number of frames is acquired. This occurs when FramesAcquired = FramesPerTrigger * (TriggerRepeat + 1) where FramesAcquired, FramesPerTrigger, and TriggerRepeat are properties of the video input object. • A run-time error occurs. • The object's Timeout value is reached. Examples Create a video input object.
18 Properties — Alphabetical List
18 Properties — Alphabetical List BayerSensorAlignment Specify sensor alignment for Bayer demosaicing Description If the ReturnedColorSpace property is set to 'bayer', then the Image 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. If your camera uses Bayer filtering, the toolbox supports the Bayer pattern and can return color if desired.
BayerSensorAlignment The value of this property is only used if the ReturnedColorSpace property is set to 'bayer'. For examples showing how to convert Bayer images, see “Converting Bayer Images” on page 7-17.
18 Properties — Alphabetical List DeviceID Identify image acquisition device represented by video input object Description The DeviceID property identifies the device represented by the video 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 1, the second device it detects the identifier 2, and so on.
DeviceID ToolboxName: 'Image Acquisition Toolbox' ToolboxVersion: '2.1 (R2007a)' Use the imaqhwinfo function again, specifying the name of the adaptor, to find out how many devices are available through that adaptor. The imaqhwinfo function returns the device IDs for all the devices in the DeviceIds field. info = imaqhwinfo('winvideo') info = AdaptorDllName: AdaptorDllVersion: AdaptorName: DeviceIDs: DeviceInfo: [1x73 char] '2.
18 Properties — Alphabetical List DiskLogger Specify MATLAB VideoWriter file used to log data Description The DiskLogger property specifies the VideoWriter or AVI file object used to log data when the LoggingMode property is set to 'disk' or 'disk&memory'. For the best performance, VideoWriter is the recommended file type. VideoWriter File For the best performance, logging to disk requires a MATLAB VideoWriter object, which is a MATLAB object, not an Image Acquisition Toolbox object.
DiskLogger AVI File 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. For complete information about the AVI file object and its properties, see the avifile documentation.
18 Properties — Alphabetical List Using VideoWriter Create a video input object that accesses a GigE Vision image acquisition device and uses grayscale format at 10 bits per pixel. vidobj = videoinput('gige', 1, 'Mono10'); You can log acquired data to memory, to disk, or both. By default, data is logged to memory. To change the logging mode to disk, configure the video input object's LoggingMode property. vidobj.LoggingMode = 'disk' Create a VideoWriter object with the profile set to Motion JPEG 2000.
DiskLogger clear vidobj Using an AVI File 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. As an argument to the close function, specify the value of the video input object DiskLogger property, vid.
18 Properties — Alphabetical List Delete the image acquisition object from memory when it is no longer needed.
DiskLoggerFrameCount DiskLoggerFrameCount Specify number of frames written to disk Description The DiskLoggerFrameCount property indicates the current number of frames written to disk by the DiskLogger. This value is only updated when the LoggingMode property is set to 'disk' or 'disk&memory'. After Logging and Running are off, it is possible that the DiskLogger might still be writing data to disk.
18 Properties — Alphabetical List ErrorFcn Specify callback function to execute when run-time error occurs Description The ErrorFcn property specifies the function to execute when an error 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. Run-time error event information is stored in the EventLog property.
EventLog EventLog Store information about events Description The EventLog property is an array of structures that stores information 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. Each event log structure contains two fields: Type and Data.
18 Properties — Alphabetical List 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' 'Trigger' 'Stop' View the data associated with a trigger event. elog(2).
EventLog See Also Properties Logging 18-15
18 Properties — Alphabetical List FrameGrabInterval Specify how often to acquire frame from video stream Description The FrameGrabInterval property specifies how often the video input 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. Note Do not confuse the frame grab interval with the frame rate.
FrameGrabInterval Characteristics Access Read only while running Data type double Values Any positive integer. The default value is 1 (acquire every frame).
18 Properties — Alphabetical List FramesAcquired Indicate total number of frames acquired Description The FramesAcquired property indicates the total number of frames 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 FramesAcquired property as it acquires frames.
FramesAcquiredFcn FramesAcquiredFcn Specify MATLAB file executed when specified number of frames have been acquired Description The FramesAcquiredFcn specifies the MATLAB file function to execute every time a predefined number of frames have been acquired. A frames acquired event is generated immediately after the number of frames specified by the FramesAcquiredFcnCount property is acquired from the selected video source. This event executes the MATLAB file specified for FramesAcquiredFcn.
18 Properties — Alphabetical List FramesAcquiredFcnCount Specify number of frames that must be acquired before frames acquired event is generated Description The FramesAcquiredFcnCount property specifies the number of frames 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 FramesAcquiredFcnCount is acquired from the selected video source.
FramesAvailable FramesAvailable Indicate number of frames available in memory buffer Description The FramesAvailable property indicates the total number of frames that are available in the memory buffer. When you extract data, the object reduces the value of the FramesAvailable property by the appropriate number of frames. You use the getdata function to extract data and move it into the MATLAB workspace.
18 Properties — Alphabetical List FramesPerTrigger Specify number of frames to acquire per trigger using selected video source Description The FramesPerTrigger property specifies the number of frames the video input object acquires each time it executes a trigger using the selected video source. When the value of the FramesPerTrigger property is set to Inf, the object keeps acquiring frames until an error occurs or you issue a stop command.
InitialTriggerTime InitialTriggerTime Record absolute time of first trigger Description The InitialTriggerTime property records the absolute time of the first trigger. The absolute time is recorded as a MATLAB clock vector. For all trigger types, InitialTriggerTime records the time when the Logging property is set to 'on'. To find the time when a subsequent trigger executed, view the Data.AbsTime field of the EventLog property for the particular trigger.
18 Properties — Alphabetical List 1.0e+003 * 1.9990 0.0020 0.0190 0.0130 0.0260 Convert the clock vector into an integer form for display. t = fix(abstime); sprintf('%d:%d:%d', t(4),t(5),t(6)) ans = 13:26:20 See Also Functions clock, getdata Properties EventLog, Logging, TriggerType 18-24 0.
Logging Logging Indicate whether object is currently logging data Description The Logging property indicates whether the video input object is currently logging data. When a trigger occurs, the object sets the Logging property to 'on' and logs data to memory, a disk file, or both, depending on the value of the LoggingMode property. The object sets the Logging property to 'off' when it acquires the requested number of frames, an error occurs, or you issue a stop command.
18 Properties — Alphabetical List LoggingMode Specify destination for acquired data Description The LoggingMode property specifies where you want the video input object to store the acquired data. You can specify any of the following values: Value Description 'disk' Log acquired data to a disk file. 'disk&memory' Log acquired data to both a disk file and to a memory buffer. 'memory' Log acquired data to a memory buffer.
LoggingMode See Also Functions getdata Properties DiskLogger, Logging 18-27
18 Properties — Alphabetical List Name Specify name of image acquisition object Description The Name property specifies a descriptive name for the image acquisition 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 and DeviceID properties with the adaptor name in this format: VideoFormat + '-' + adaptor name + '-' + DeviceID Examples Create an image acquisition object.
Name Properties DeviceID, VideoFormat 18-29
18 Properties — Alphabetical List NumberOfBands Indicate number of color bands in data to be acquired Description The NumberOfBands property indicates the number of color bands in the 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 NumberOfBands property indicates the number of color bands in the data returned by getsnapshot, getdata, and peekdata.
NumberOfBands vid.NumberOfBands ans = 3 If you retrieve the value of the VideoFormat property, you can see that the video data is in RGB format. vid.
18 Properties — Alphabetical List Parent Identify video input object that is parent of video source object Description The Parent property identifies the video input object that is the 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.
Previewing Previewing Indicate whether object is currently previewing data in separate window Description The Previewing property indicates whether the object is currently previewing data in a separate window. The object sets the Previewing property to 'on' when you call the preview function. The object sets the Previewing property to 'off' when you close the preview window using the closepreview function or by clicking the Close button in the preview window title bar.
18 Properties — Alphabetical List ReturnedColorSpace Specify color space used in MATLAB Description The ReturnedColorSpace property specifies the color space you 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 getsnapshot, getdata, and peekdata functions. This property can have any of the following values: Value Description 'grayscale' MATLAB grayscale color space. 'rgb' MATLAB RGB color space.
ReturnedColorSpace For an example showing how to determine the default color space and change the color space setting, see “Specifying the Color Space” on page 7-16.
18 Properties — Alphabetical List ROIPosition Specify region-of-interest (ROI) window Description The ROIPosition property specifies the region-of-interest acquisition 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. ROIPosition is specified as a 1-by-4 element vector [XOffset YOffset Width Height] where 18-36 XOffset Position of the upper left corner of the ROI, measured in pixels.
ROIPosition Note: The Width does not include both end points as well as the 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 XOffset of 19 and a Width of 11. The same rule applies to height.
18 Properties — Alphabetical List Running Indicate whether video input object is ready to acquire data Description The Running property indicates if the video input object is ready to acquire data. Along with the Logging property, Running reflects the state of a video input object. The Running property indicates that the object is ready to acquire data, while the Logging property indicates that the object is acquiring data. The object sets the Running property to 'on' when you issue the start command.
Running See Also Properties getsnapshot, start, stop Properties Logging 18-39
18 Properties — Alphabetical List Selected Indicate whether video source object will be used for acquisition Description The Selected property indicates if the video source object will be used for acquisition. You select a video source object by specifying its name as the value of the video input object's SelectedSourceName property. The video input object Source property is an array of all the video source objects associated with the video input object.
Selected ans = input1 Retrieve the currently selected video source object. src = getselectedsource(vid); View its Name and Selected properties. src.SourceName ans = input1 src.
18 Properties — Alphabetical List SelectedSourceName Specify name of currently selected video source Description The SelectedSourceName property specifies the name of the video 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 Source property. The toolbox defines a video source as one or more hardware inputs that are treated as a single entity.
SelectedSourceName See Also Functions set Properties Source 18-43
18 Properties — Alphabetical List Source Indicate video source objects associated with video input object Description The Source property is a vector of video source objects that represent 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. Each video source object created is provided a unique source name.
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 Source property of the video input object. (To view only the currently selected video source object, use the getselectedsource function.) sources = vid.Source; src = sources(1); To view the properties of the video source object src, use the get function.
18 Properties — Alphabetical List SourceName Indicate name of video source object Description The SourceName property indicates the name of a video source object. SourceName is one of the values in the video input object's SelectedSourceName property.
StartFcn StartFcn Specify MATLAB file executed when start event occurs Description The StartFcn property specifies the MATLAB file function to execute when a start event occurs. A start event occurs immediately after you issue the start command. The StartFcn callback executes synchronously. The toolbox does not set the object's Running property to 'on' until the callback function finishes executing. If the callback function encounters an error, the object never starts running.
18 Properties — Alphabetical List StopFcn Specify MATLAB file executed when stop event occurs Description The StopFcn property specifies the MATLAB file function to execute when a stop event occurs. A stop event occurs immediately after you issue the stop command. The StopFcn callback executes synchronously. Under most circumstances, the image acquisition object will be stopped and the Running property will be set to 'off' by the time the MATLAB file completes execution.
Tag Tag Specify descriptive text to associate with image acquisition object Description The Tag property specifies any descriptive text that you want to associate with an image acquisition object. The Tag 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.
18 Properties — Alphabetical List Timeout Specify how long to wait for image data Description The Timeout property specifies the amount of time (in seconds) that the getdata and getsnapshot functions wait for data to be returned. The Timeout property is only associated with these blocking functions. If the specified time period expires, the functions return control to the MATLAB command line. A timeout is one of the conditions for stopping an acquisition.
TimerFcn TimerFcn Specify MATLAB file callback function to execute when timer event occurs Description The TimerFcn property specifies the MATLAB file callback function to execute when a timer event occurs. A timer event occurs when the time period specified by the TimerPeriod property expires. The toolbox measures time relative to when the object is started with the start function. Timer events stop being generated when the image acquisition object stops running.
18 Properties — Alphabetical List TimerPeriod Specify number of seconds between timer events Description The TimerPeriod property specifies the amount of time, in seconds, that must pass before a timer event is triggered. The toolbox measures time relative to when the object is started with the start function. Timer events stop being generated when the image acquisition object stops running.
TriggerCondition TriggerCondition Indicate required condition before trigger event occurs Description The TriggerCondition property indicates the condition that must be met, via the TriggerSource, before a trigger event occurs. The trigger conditions that you can specify depend on the value of the TriggerType property. TriggerType Value Conditions Available 'hardware' (if available for your device) Device-specific.
18 Properties — Alphabetical List Properties TriggerSource, TriggerType 18-54
TriggerFcn TriggerFcn Specify MATLAB file callback function to execute when trigger event occurs Description The TriggerFcn property specifies the MATLAB file callback function 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.
18 Properties — Alphabetical List TriggerFrameDelay Specify number of frames to skip before acquiring frames after trigger occurs Description The TriggerFrameDelay property specifies the number of frames to skip before acquiring frames after a trigger occurs. The object waits the specified number of frames after the trigger before starting to log frames. In this figure, the TriggerFrameDelay is set to 5, so the object lets five frames pass before starting to acquire frames.
TriggerFrameDelay See Also Functions trigger Properties FramesPerTrigger 18-57
18 Properties — Alphabetical List TriggerRepeat Specify number of additional times to execute trigger Description The TriggerRepeat property specifies the number of additional times you want the object to execute a trigger. This table describes the behavior for several typical TriggerRepeat values. Value Behavior 0 (default) Execute the trigger once when the trigger condition is met. Any positive integer Execute the trigger the specified number of additional times when the trigger condition is met.
TriggerRepeat Properties FramesPerTrigger, TriggersExecuted, TriggerType 18-59
18 Properties — Alphabetical List TriggersExecuted Indicate total number of executed triggers Description The TriggersExecuted property indicates the total number of triggers that the video input object has executed. Characteristics Access Read only Data type double Values Any nonnegative integer. The default value is 0 (zero).
TriggerSource TriggerSource Indicate hardware source to monitor for trigger conditions Description The TriggerSource property indicates the hardware source the image acquisition object monitors for trigger conditions. When the condition specified in the TriggerCondition property is met, the object executes the trigger and starts acquiring data. You use the triggerconfig function to specify this value. The value of the TriggerSource property is device specific.
18 Properties — Alphabetical List See Also Functions trigger, triggerconfig, triggerinfo Properties TriggerCondition, TriggerType 18-62
TriggerType TriggerType Indicate type of trigger used by video input object Description The TriggerType property indicates the type of trigger used by the video input object. Triggers initiate data acquisition. You use the triggerconfig function to specify one of the following values for this property. Trigger Type Description 'hardware' (if available for your device) Trigger executes when a specified condition is met.
18 Properties — Alphabetical List See Also Functions trigger, triggerconfig, triggerinfo Properties TriggerCondition, TriggerSource 18-64
Type Type Identify type of image acquisition object Description The Type property identifies the type of image acquisition object. An image acquisition object can be either one of two types: • Video input object • Video source object Characteristics Access Read only Data type String Values [ 'videoinput' | 'videosource' ] Defined at object creation time Examples vid = videoinput('winvideo',1) vid.Type ans = videoinput This example gets the type of a video source object.
18 Properties — Alphabetical List See Also Functions getselectedsource, videoinput 18-66
UserData UserData Store data to associate with image acquisition object Description The UserData property specifies any data that you want to associate with an image acquisition object. Note The object does not use the data in UserData directly. However, you can access the data by referencing the property as you would a field in a MATLAB structure using dot notation.
18 Properties — Alphabetical List VideoFormat Specify video format or name of device configuration file Description The VideoFormat property specifies the video format used by the image acquisition device or the name of a device configuration file, depending on which you specified when you created the object using the videoinput function. Image acquisition devices typically support multiple video formats.
VideoFormat info = imaqhwinfo('winvideo') info = AdaptorDllName: AdaptorDllVersion: AdaptorName: DeviceIDs: DeviceInfo: [1x73 char] '2.1 (R2007a)' 'winvideo' {[1]} [1x1 struct] info.DeviceInfo ans = DefaultFormat: DeviceFileSupported: DeviceName: DeviceID: VideoInputConstructor: VideoDeviceConstructor: SupportedFormats: 'RGB555_128x96' 0 'IBM PC Camera' 1 'videoinput('winvideo', 1)' 'imaq.
18 Properties — Alphabetical List VideoResolution Indicate width and height of incoming video stream Description The VideoResolution property is a two-element vector indicating the width and height of the frames in the incoming video stream. VideoResolution is specified as [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 function.
19 Block Reference
19 Block Reference From Video Device 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.
From Video Device The From Video Device block supports the use of model referencing. This feature lets your model include other Simulink models as modular components. For more information on these features, see the Simulink documentation. The From Video Device block supports the use of code generation along with the packNGo function to group required source code and dependent shared libraries. See the next section.
19 Block Reference information for your models. One of the Build Information functions that Simulink Coder provides is packNGo. This function allows you to package model code and dependent shared libraries into a zip file for deployment. The target system does not need to have MATLAB installed but it does need to be supported by MATLAB. The block supports use of the packNGo function. Source-specific properties for your device are honored when code is generated.
From Video Device 19-5
19 Block Reference 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. Some fields may not appear, as they are device dependent. If your selected device does not support a feature, it may not appear in the dialog box.
From Video Device 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. All video capture devices supported 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, From camera file will be one of the choices in the list.
19 Block Reference 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. Therefore you only need to change the values in this field if you do not want to capture the full image size. Output color space Use this field to select the color space for devices that support color. Possible values are rgb, grayscale, and YCbCr. The default value is rgb.
From Video Device Note: The block acquires data in the default ReturnedColorSpace setting for the specified device and format. 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 single is the default.
19 Block Reference Kinect for Windows Metadata Output Ports This is used to return skeleton information in Simulink during simulation and code generation. You can output metadata information in normal, accelerator, and deployed simulation modes. Each metadata item in the Selected Metadata list becomes an output port on the block. If you are using a Kinect for Windows camera, and you select the Depth sensor as your Device and the Depth Source as your Video source, the Metadata Output Ports section appears.
From Video Device This section is only visible when a Kinect Depth sensor is selected. The All Metadata list shows which metadata are available. The Selected Metadata list shows which metadata items will be returned to Simulink. This is empty by default. To use one of the metadata, add it from the All to the Selected list by selecting it in the All list and clicking the Add button (blue arrow icon). The Remove button (red X icon) removes an item from the Selected Metadata list.
19 Block Reference buttons to change the order of items in the Selected list. The list supports multi-select as well. You can see in the example above that three metadata items have been put in the Selected list. When you click Apply, output ports are created on the block for these metadata, as shown here. The first port is the depth frame.
Video Input (Obsolete) Video Input (Obsolete) 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. The opening, initializing, and configuration occur once, at the start of the model's execution.
19 Block Reference Dialog Box 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. Frame rate The speed at which frames are delivered to the block, expressed as frames per second (fps). Output data type The image data type used when the block outputs frames.
