MATLAB IMAGE ACQUISITION TOOLBOX - RELEASE NOTES Guida Utente

Image Acquisition Toolbox™ Adaptor KitUser's GuideR2015a

x ContentsTest Suite Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8-16

5 Acquiring Image Data5-22Your thread function must accept a single parameter, which is defined as a pointer tothe object itself, i.e., the this point

Implementing the Acquisition Thread Function5-23 } // while(isAcquisitionNotComplete() break; } //switch-case WM_USER

5 Acquiring Image Data5-24Supporting ROIsThe toolbox supports the specification of regions of interest (ROIs) in both software andhardware. The follow

Supporting ROIs5-25Note You use the ROI width and height when you create the frame but you use the fullimage width and height when you copy the image

5 Acquiring Image Data5-26} // if isSendFrame()Implementing Hardware ROIFor hardware ROI, the user defines the ROI on the device. The device returns o

Supporting Hardware Triggers5-27Supporting Hardware TriggersThe toolbox supports three types of triggers:• Immediate — Trigger fires when video input

5 Acquiring Image Data5-28Main Acquisition Loop with Test for Hardware TriggerExampleThe following is an acquisition thread function that includes a c

Supporting Hardware Triggers5-29 // Add code here to configure the image // acquisition device for hardware

5 Acquiring Image Data5-30Using Critical SectionsThis section describes how to use critical sections to protect portions of your adaptor code.The sect

Using Critical Sections5-31The auto critical section object ensures that you always exit a critical section. However,you must also ensure that the au

1Getting StartedThis section introduces the Image Acquisition Toolbox™ Adaptor Kit.• “Custom Adaptors” on page 1-2• “Creating an Adaptor” on page 1-4•

5 Acquiring Image Data5-32done. Insert this code just before the acquisition thread function breaks out of theframe acquisition loop — see “Implementi

Specifying Device Driver Identification Information5-33Specifying Device Driver Identification InformationTwo of the virtual functions you must imple

5 Acquiring Image Data5-34const char* MyDeviceAdaptor::getDriverVersion() const { return "1.0.0";}

6Defining Device-Specific PropertiesThis chapter describes how to define the properties that toolbox users can use toconfigure various attributes of a

6 Defining Device-Specific Properties6-2Defining Device-Specific PropertiesYou define which properties of your image acquisition device you want to ex

Defining Device-Specific Properties6-3 Device Specific Properties: Brightness = -10 Contrast = 266 Exposure = 1024 ExposureMode = auto

6 Defining Device-Specific Properties6-41Determine the device the user wants to establish a connection with, specified bydevice ID.2Determine the form

Creating Device Properties6-5Creating Device PropertiesTo define properties for a device, follow this procedure:1Create the property using the approp

6 Defining Device-Specific Properties6-6For example, use the createDoubleProperty() function to create a property whosevalue is of type double.hprop =

Creating Device Properties6-7 // Create a property of type double with a default value hProp = devicePropFact->createDoubleProperty("MyDouble

1 Getting Started1-2Custom AdaptorsThe Image Acquisition Toolbox Adaptor Kit is a C++ framework that you can use tocreate an adaptor. A C++ framework

6 Defining Device-Specific Properties6-8 Type = videosource Device Specific Properties: MyDoubleProp = 2.5MyBoundedIntProp = 100MyEnumeratedPro

Defining Hardware Trigger Configurations6-9Defining Hardware Trigger ConfigurationsTo define hardware trigger configurations, use the addConfiguratio

6 Defining Device-Specific Properties6-10Implementing Get and Set Support for Device-Specific PropertiesAfter connecting to a device through your adap

Implementing Get and Set Support for Device-Specific Properties6-11In this example, the constructor accepts a handle to an IAdaptor object. Because t

6 Defining Device-Specific Properties6-12IPropInfo functions you can retrieve the property name, its storage type and itsdefault value. This informati

Implementing Get and Set Support for Device-Specific Properties6-13ExampleThis example shows an implementation of a getValue() function for integer t

6 Defining Device-Specific Properties6-14The following example iterates through all properties in the adaptor propertycontainer, associating a get lis

Implementing Get and Set Support for Device-Specific Properties6-15Defining a Set Listener ClassCreate a set listener class, deriving it from the abs

6 Defining Device-Specific Properties6-16 // The new value for double properties. double _lastDoubleValue; // The new value for string propertie

Implementing Get and Set Support for Device-Specific Properties6-17Alternatively, you could define a separate set listener class for each property or

Custom Adaptors1-3MATLAB code files (MATLAB commands)Image Acquisition Toolbox engineAdaptor DLLVendor InterfaceHardwareRelationship of Adaptor to To

6 Defining Device-Specific Properties6-18 getEngine()->getAdaptorPropContainer();2Add a set listener to a property in the c

Implementing Get and Set Support for Device-Specific Properties6-19 delete [] devicePropNames; }

7Storing Adaptor Information in anIMDF FileThis chapter describes how to store information about adaptor properties in an ImageDevice File (IMDF) in a

7 Storing Adaptor Information in an IMDF File7-2Using the IMDF Markup LanguageThis chapter describes how to use an XML-based markup language to specif

Using the IMDF Markup Language7-3Hierarchy of IMDF Elements

7 Storing Adaptor Information in an IMDF File7-4Creating an IMDF File: Toplevel ElementsThe ImageAcquisitionInfo element must be the root node of all

Specifying Help in an IMDF File7-5Specifying Help in an IMDF FileTo define help text for adaptor properties in an IMDF file, use the Help element. Yo

7 Storing Adaptor Information in an IMDF File7-6Element Description Attributes<Help> Defines the help section in anIMDF file. Must be child of t

Specifying Help in an IMDF File7-7The items in this list correspond to the numbered elements above.1Device-specific properties are properties of the

1 Getting Started1-4Creating an AdaptorTo create an adaptor, you must implement the C++ routines and the classes requiredby the adaptor framework. The

7 Storing Adaptor Information in an IMDF File7-84The first line of the help lists the name of the property with its constraints, such asrange and perm

Specifying Help in an IMDF File7-9Upon enabling the strobe output, it will start detectionof triggers and generate output as appropriate. Consult yo

7 Storing Adaptor Information in an IMDF File7-10Specifying Device InformationTo specify information about a particular device in an IMDF file, use th

Specifying Device Information7-11The following table summarizes the elements that can be children of a Device node, inthe order they must be specifie

7 Storing Adaptor Information in an IMDF File7-12<Device name="PCVision"> <Property optional="on" constrain

Specifying Property Information7-13Specifying Property InformationTo specify property information in an IMDF file, use the Property element. You cani

7 Storing Adaptor Information in an IMDF File7-14Specifying Property Element AttributesThe following table lists the attributes of a Property node in

Specifying Property Information7-15Constraint Value Descriptionbounded Property has both a minimum and maximum value. If you setthe constraint attrib

7 Storing Adaptor Information in an IMDF File7-16Specifying Format InformationTo specify the video formats supported by a particular device in an IMDF

Specifying Format Information7-17Element Description AttributesThis is an optional element. AVideoFormat node can containmultiple Include nodes.ident

Creating an Adaptor1-5Stage 3: Provide Hardware InformationIn this stage, you start development by creating a stub implementation of your adaptor.Eve

7 Storing Adaptor Information in an IMDF File7-18Specifying Hardware Trigger InformationTo specify hardware trigger information in an IMDF file, use t

Specifying Hardware Trigger Information7-19Element Description Attributescan contain zero or moreTriggerCondition nodes.Specifying Trigger SourcesWhe

7 Storing Adaptor Information in an IMDF File7-20Specifying Video SourcesTo specify the video source in an IMDF file, use the Source element. A Source

Defining and Including Sections7-21Defining and Including SectionsYou can gather one or more Property or TriggernInfo nodes into a group by usingthe

8Test Suite for Adaptor Writers• “Testing Adaptors or Hardware” on page 8-2• “Creating a Stub Adaptor Test Procedure” on page 8-3• “Specifying Format

8 Test Suite for Adaptor Writers8-2Testing Adaptors or HardwareAs part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and

Creating a Stub Adaptor Test Procedure8-3Creating a Stub Adaptor Test ProcedureAs part of the Image Acquisition Toolbox Adaptor Kit, we now offer a t

8 Test Suite for Adaptor Writers8-4Test Procedures Expected ResultsdevInfo(:).DeviceInfo DefaultFormat: '640x480'DeviceFileSupported: 0Devic

Creating a Stub Adaptor Test Procedure8-5Test Procedures Expected ResultsvidObj = videoinput ('AdaptorName')format without any error and

1 Getting Started1-6an alternative, you can define device-specific properties in an image device definitionfile (IMDF). For more information, see “Def

8 Test Suite for Adaptor Writers8-6Specifying Format of Image Data Test ProcedureAs part of the Image Acquisition Toolbox Adaptor Kit, we now offer a

Implementing the Acquisition Thread Function Test Procedure8-7Implementing the Acquisition Thread Function Test ProcedureAs part of the Image Acquisi

8 Test Suite for Adaptor Writers8-8Supporting ROIs Test ProcedureAs part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure a

Specifying Device Driver Identification Information Test Procedure8-9Specifying Device Driver Identification Information Test ProcedureAs part of the

8 Test Suite for Adaptor Writers8-10Test Procedures Expected ResultsSourceName = input1Tag =Type = videosourceDevice-specific Properties:Brightness =

Using the Test Suite Functions and Properties8-11Using the Test Suite Functions and PropertiesIn this section...“Test Suite Properties” on page 8-11“

8 Test Suite for Adaptor Writers8-12Property Description• current test name• current test details/information• any applicable information on how toint

Using the Test Suite Functions and Properties8-13Function PurposerunAllAutomatedTestsFor automated testing, run all automated tests.This runs all tes

8 Test Suite for Adaptor Writers8-14Function PurposerunAutomatedRepeated AcquisitionTestFor automated testing, run automated repeatedacquisition tes

Using the Test Suite Functions and Properties8-15Function PurposerunAutomatedHardware TriggerTestFor automated testing, run automated triggertest f

Looking at the Demo Adaptor1-7Looking at the Demo AdaptorA good way to get a quick introduction to adaptors and adaptor development is by lookingat t

8 Test Suite for Adaptor Writers8-16Function PurposemethodsGet the list of tests that can be run.For an imaqkit.AdaptorTest object calledtestObj, use

Using the Test Suite Functions and Properties8-17This example shows the basic workflow of creating and running a test using some of thefunctions outl

1 Getting Started1-8Source File DescriptionDemoSourceListener.h Definition of class used to listen for changes in theselected video sourceDemoTimestam

Looking at the Demo Adaptor1-9DemoAdaptor.hAfter viewing the exported functions, take a look at the definition of the DemoAdaptorclass in DemoAdaptor

How to Contact MathWorksLatest news:www.mathworks.comSales and services:www.mathworks.com/sales_and_servicesUser community:www.mathworks.com/matlabcen

1 Getting Started1-10MATLAB Command BreakpointcreateInstance()imaqhwinfo(obj) getDriverDescription()getDriverVersion()getMaxWidth()getMaxHeight()getFr

Looking at the Demo Adaptor1-11Note Because the toolbox caches adaptor information, you might need to reset thetoolbox, using imaqreset, before a new

1 Getting Started1-12Preview Windows Containing Demo Adaptor Data

2Setting Up Your Build EnvironmentThis chapter describes the libraries and include files you need to build an adaptor onWindows, Linux, or Macintosh s

2 Setting Up Your Build Environment2-2Setting up a Build Environment on Windows SystemsSetting up the build environment involves specifying the header

Setting up a Build Environment on Windows Systems2-3Header File andLibrariesLocationAdaptor kit headerfiles$(MATLAB)\toolbox\imaq\imaqadaptors\kit\in

2 Setting Up Your Build Environment2-4Creating an Adaptor Project Using Microsoft Visual C++As the first step toward building an adaptor, open Microso

Setting up a Build Environment on Windows Systems2-5Select Win32 Project.Select Win32.Specify name and locationof project.Click OK.• Click OK. Visual

2 Setting Up Your Build Environment2-6Select Empty Project. Click Finish.Select DLL.After you create the project, close the Start Page . Visual C++ di

Setting up a Build Environment on Windows Systems2-7New ProjectRecompiling with New Versions of the Image Acquisition Toolbox SoftwareAfter you have

Revision HistorySeptember 2005 PDF only New for Version 1.0 (Release 14SP3)March 2007 PDF only Revised for Version 1.0 (Release 2007a)September 2007 P

2 Setting Up Your Build Environment2-8where matlabroot represents your MATLAB installation folder.Specifying Header File LocationsBefore you can compi

Setting up a Build Environment on Windows Systems2-9Click OK.Select Include Directories and click Edit.Select VC++ Directories.4Add the locations of

2 Setting Up Your Build Environment2-10Specify header file locations.Click OK.5After specifying the header file folders, click OK.Specifying Libraries

Setting up a Build Environment on Windows Systems2-113Expand Configuration Properties and then expand Linker. Select General and,on this page, select

2 Setting Up Your Build Environment2-12on page 2-3. You must replace <ARCH> with the name of an architecture-specificfolder, such as, win32 or w

Setting up a Build Environment on Windows Systems2-13Select Additional Dependencies and click Edit.Select Input.Click OK.4Specify the names of the ad

2 Setting Up Your Build Environment2-14Specify library names.Click OK.5Click OK.Configuring Other Project ParametersIn addition to specifying the head

Setting up a Build Environment on Windows Systems2-15dAdd the new source file to your project. From the File menu, select MoveSource1.cpp into and se

2 Setting Up Your Build Environment2-16Select Code Generation.Set these properties.Click OK.4In the Property Pages dialog box, under C/C++, select Lan

Setting up a Build Environment on Windows Systems2-17Select Language.Set this property.Click OK.5In the Property Pages dialog box, under C/C++, selec

2 Setting Up Your Build Environment2-18Click OK.Select Command Line.Specify command line argument.Click OK.

Setting up a Build Environment on Linux and Macintosh Systems2-19Setting up a Build Environment on Linux and Macintosh SystemsIn this section...“Requ

2 Setting Up Your Build Environment2-20Creating a Makefile Based on the Demo Adaptor MakefileTo create a makefile to build your adaptor based on the d

Setting up a Build Environment on Linux and Macintosh Systems2-218Save the makefile.After you create your makefile, use it to build your adaptor, as

3Providing Hardware InformationThis chapter describes how an adaptor provides the toolbox engine with informationabout the image acquisition device (o

3 Providing Hardware Information3-2Using Adaptor Exported FunctionsThe Image Acquisition Toolbox engine requires that every adaptor export five functi

Using Adaptor Exported Functions3-3initializeAdaptor()MATLAB Toolbox Engine AdaptorEngine searches for adaptorDLLs and loads them.imaqhwinfoReturns l

3 Providing Hardware Information3-4Creating a Stub AdaptorThe easiest way to start building an adaptor is to create a stub implementation, compileand

Creating a Stub Adaptor3-5 const char* formatName, imaqkit::IPropFactory* deviceProp

vContentsGetting Started1Custom Adaptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1-2What Knowledge Is Required? . . .

3 Providing Hardware Information3-6Note: At this point in your adaptor development, the DeviceIDs field and theDeviceInfo fields are empty.imaqhwinfo(

Performing Adaptor and Device SDK Initialization3-7Performing Adaptor and Device SDK InitializationEvery adaptor must include an initializeAdaptor()

3 Providing Hardware Information3-8Specifying Device and Format InformationEvery adaptor must include a getAvailHW() function. In this function, you p

Specifying Device and Format Information3-9format supported by a device, you must create an IDeviceFormat object and then storethe object in the IDev

3 Providing Hardware Information3-10Your adaptor's getAvailHW() function must provide the engine with the followinginformation for each device:•

Specifying Device and Format Information3-11Suggested Algorithm for getAvailHW() FunctionStoring Device InformationYou store device information in an

3 Providing Hardware Information3-12You can specify any values for these arguments, but note that they are visible to toolboxusers in the structure re

Specifying Device and Format Information3-13Because the ID is not exposed to users, you can specify any convenient value. Forexample, if the device&a

3 Providing Hardware Information3-14Example: Providing Device and Format InformationThe following example presents a simple implementation of a getAva

Specifying Device and Format Information3-15dev = AdaptorDllName: 'C:\My_Adaptor\mydeviceimaq.dll' AdaptorDllVersion: '4.1 (

vi ContentsCreating a Makefile Based on the Demo Adaptor Makefile . 2-20Providing Hardware Information3Using Adaptor Exported Functions . . . . . . .

3 Providing Hardware Information3-16Field DescriptionDeviceID Numeric value that uniquely identifies a particular device. You definethis value when yo

Defining Classes to Hold Device-Specific Information3-17Defining Classes to Hold Device-Specific InformationYou might want to store more information

3 Providing Hardware Information3-18The demo adaptor provides an example, defining a class to hold additional formatinformation. This class, named Dem

Unloading Your Adaptor DLL3-19Unloading Your Adaptor DLLEvery adaptor must include an uninitializeAdaptor() function. The engine callsthis function w

3 Providing Hardware Information3-20Returning Warnings and Errors to the MATLAB Command LineTo return error or warning messages from your adaptor to t

4Defining Your Adaptor ClassThis chapter describes how to define your adaptor class and instantiate an objectof this class. Every adaptor must define

4 Defining Your Adaptor Class4-2Defining Your Adaptor ClassThe next four topics describe how to define your adaptor class and instantiate an objectof

Using IAdaptor Abstract Class Virtual Functions4-3Using IAdaptor Abstract Class Virtual FunctionsThe following table lists the pure virtual functions

4 Defining Your Adaptor Class4-4Pure Virtual Function Description with DeclarationgetNumberOfBands() Returns the number of bands used in the returned

Creating Stub Implementation of Your Adaptor Class4-5Creating Stub Implementation of Your Adaptor ClassTo create a stub implementation of your adapto

viiIdentifying Video Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9Suggested Algorithm . . . . . . . . . . . . . . . . . . . . .

4 Defining Your Adaptor Class4-63Add a C++ source file to the adaptor project. You can give the source file any name.This example names the file mydev

Creating Stub Implementation of Your Adaptor Class4-7Exported Functions” on page 3-2. This is needed because the createInstance()exported function in

4 Defining Your Adaptor Class4-8Note While you can create a video input object with your adaptor, you cannotuse it to acquire video from a device. You

Identifying Video Sources4-9Identifying Video SourcesThe toolbox defines a video source as one or more hardware inputs that are treatedas a single en

4 Defining Your Adaptor Class4-10Because the ID is not exposed to users, you can specify any convenient value. Forexample, if the device's SDK us

Instantiating an Adaptor Object4-11Instantiating an Adaptor ObjectEvery adaptor must include a createInstance() function. The engine calls thisfuncti

4 Defining Your Adaptor Class4-12Implementing Your Adaptor Class ConstructorBecause you write the code that calls your adaptor class constructor, you

Instantiating an Adaptor Object4-13imaqkit::IAdaptor* createInstance(imaqkit::IEngine* engine, imaqkit::IDeviceInfo* device

4 Defining Your Adaptor Class4-14}

5Acquiring Image DataThis chapter describes how to implement the adaptor member functions to performimage acquisition. After completing the tasks outl

viii ContentsUsing Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5-30Understanding Critical Sections . . . . . . . . .

5 Acquiring Image Data5-2Acquiring Image DataAfter completing chapters 3 and 4, you can see your adaptor included in the list ofadaptors returned by i

Acquiring Image Data5-3acquire data. With hardware triggers, you start the object and it waits until it receives asignal from an external device to s

5 Acquiring Image Data5-4open()openDevice()MATLAB Toolbox Engine AdaptorMake sure device is notalready logging.Start new threadof execution.Send messa

Specifying the Format of the Image Data5-5Specifying the Format of the Image DataBefore you can acquire data from your device, you must tell the engi

5 Acquiring Image Data5-6The engine calls these functions in your adaptor to get the resolution information that itdisplays in the VideoResolution pro

Specifying the Format of the Image Data5-7names specified in the example in “Specifying Device and Format Information” on page3-8.int MyDeviceAdaptor

5 Acquiring Image Data5-8Format Frame TypesSigned 16- and 32-bit formats; both little-endian and big-endian;in regular and flip formats.Floating-point

Specifying the Format of the Image Data5-9describe how the bytes of red, green, and blue data are arranged in memory. In packedformats, the red, gree

5 Acquiring Image Data5-10Opening and Closing Connection with a DeviceAdaptors typically open a connection with the device in their openDevice() funct

Opening and Closing Connection with a Device5-11HANDLE CreateThread( LPSECURITY_ATTRIBUTES lpThreadAttributes, SIZE_T dwStackSize, LPTHREAD_START_

ixSpecifying Help in an IMDF File . . . . . . . . . . . . . . . . . . . . . . . 7-5User Scenario: Viewing Property Help . . . . . . . . . . . . . . .

5 Acquiring Image Data5-12 return true; // Create the image acquistion thread. _acquireThread = CreateThread(NULL,

Opening and Closing Connection with a Device5-13private:// Declaration of acquisition thread functionstatic DWORD WINAPI acquireThread(void* param);/

5 Acquiring Image Data5-14 WaitForSingleObject(_acquireThread, 10000); // Close thread handle. CloseHandle(_acquireThread);

Starting and Stopping Image Acquisition5-15Starting and Stopping Image AcquisitionOnce openDevice() returns successfully, the engine calls your adapt

5 Acquiring Image Data5-16The PostThreadMessage() function accepts these parameters:BOOL PostThreadMessage( DWORD idThread, UIN

Starting and Stopping Image Acquisition5-17Suggested Algorithm for stopCapture()The stopcapture() function typically performs these tasks.1Checks whe

5 Acquiring Image Data5-18Implementing the Acquisition Thread FunctionThis section describes how to implement your adaptor's acquisition thread f

Implementing the Acquisition Thread Function5-19When it receives the appropriate message, the acquisition thread function entersthe frame acquisition

5 Acquiring Image Data5-20Frame Acquisition LoopThe frame acquisition loop is where your adaptor acquires frames from the device andsends them to the

Implementing the Acquisition Thread Function5-21dSend the packaged frame to the engine, using the IEngine member functionreceiveFrame().5Increment th