Image Acquisition Toolbox™ Adaptor Kit 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™ Adaptor Kit User's Guide © COPYRIGHT 2005–2015 by The MathWorks, Inc. The software described in this document is furnished under a license agreement.
Revision History September 2005 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 PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only PDF only New for Version 1.0 (Release 14SP3) Revised for Version 1.0 (Release 2007a) Revised for Version 1.
Contents 1 2 Getting Started Custom Adaptors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . What Knowledge Is Required? . . . . . . . . . . . . . . . . . . . . . . . 1-2 1-3 Creating an Adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Staged Development Model . . . . . . . . . . . . . . . . . . . . . . . . . . 1-4 1-4 Looking at the Demo Adaptor . . . . . . . . . . . . . . . . . . . . . . . . . Finding the Demo Adaptor Source Files . . . . . . . . . .
Creating a Makefile Based on the Demo Adaptor Makefile . 3 4 vi Contents 2-20 Providing Hardware Information Using Adaptor Exported Functions . . . . . . . . . . . . . . . . . . . . . 3-2 Creating a Stub Adaptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-4 Performing Adaptor and Device SDK Initialization . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3-7 3-7 Specifying Device and Format Information . . . . . . . . . . . . .
5 Identifying Video Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . Suggested Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4-9 4-9 Instantiating an Adaptor Object . . . . . . . . . . . . . . . . . . . . . . Suggested Algorithm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Implementing Your Adaptor Class Constructor . . . . . . . . . . Implementing Your Adaptor Class Destructor . . . . . . . . . . .
6 Using Critical Sections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Understanding Critical Sections . . . . . . . . . . . . . . . . . . . . . Example: Using a Critical Section . . . . . . . . . . . . . . . . . . . . 5-30 5-30 5-31 Specifying Device Driver Identification Information . . . . . User Scenario . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
8 Specifying Help in an IMDF File . . . . . . . . . . . . . . . . . . . . . . . User Scenario: Viewing Property Help . . . . . . . . . . . . . . . . . Creating AdaptorHelp Nodes . . . . . . . . . . . . . . . . . . . . . . . . 7-5 7-6 7-8 Specifying Device Information . . . . . . . . . . . . . . . . . . . . . . . Example: Device Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7-10 7-11 Specifying Property Information . . . . . . . . . . . . . . . . . . . . . .
Test Suite Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .
1 Getting Started This section introduces the Image Acquisition Toolbox™ Adaptor Kit.
1 Getting Started Custom Adaptors The Image Acquisition Toolbox Adaptor Kit is a C++ framework that you can use to create an adaptor. A C++ framework is a set of classes that work together to create a particular application. In a framework, the design of the software is already defined. With the adaptor framework, you subclass the framework classes and implement the required member functions to flesh out the design to support your particular hardware.
Custom Adaptors MATLAB code files (MATLAB commands) Image Acquisition Toolbox engine Adaptor DLL Vendor Interface Hardware Relationship of Adaptor to Toolbox Components What Knowledge Is Required? To build an adaptor, you should have a working knowledge of • C++ • The functionality of your hardware device, and its associated application programming interface (API) • Image Acquisition Toolbox concepts, functionality, and terminology as described in the Image Acquisition Toolbox User's Guide document
1 Getting Started Creating an Adaptor To create an adaptor, you must implement the C++ routines and the classes required by the adaptor framework. The following outlines one way to develop an adaptor that divides the task into several smaller tasks, called stages. This staged development model has been shown to be an effective way to create an adaptor.
Creating an Adaptor Stage 3: Provide Hardware Information In this stage, you start development by creating a stub implementation of your adaptor. Every adaptor must provide the toolbox with information about the device (or devices) it makes available to users. As a first step, you define the labels you want to use to identify the devices available through your adaptor and the formats they support, and you implement the adaptor functions that return this information to users.
1 Getting Started an alternative, you can define device-specific properties in an image device definition file (IMDF). For more information, see “Defining Device-Specific Properties” on page 6-2.
Looking at the Demo Adaptor Looking at the Demo Adaptor A good way to get a quick introduction to adaptors and adaptor development is by looking at the demo adaptor that is included with the Image Acquisition Toolbox Adaptor Kit. The demo adaptor is a functioning adaptor that does not require any hardware. You can build the demo adaptor and run it to get familiar with how an adaptor works.
1 Getting Started Source File Description DemoSourceListener.h Definition of class used to listen for changes in the selected video source DemoTimestampGetFcn.cpp Implementation of class that provides a custom get function for the timestamp properties. DemoTimestampGetFcn.h Definition of class that provides a custom get function for the timestamp properties. mwdemoimaq.cpp Implementation of the five functions that every adaptor must export. mwdemoimaq.dll Demo adaptor library.
Looking at the Demo Adaptor DemoAdaptor.h After viewing the exported functions, take a look at the definition of the DemoAdaptor class in DemoAdaptor.h. The adaptor class is a subclass of the IAdaptor class, which defines the virtual functions an adaptor must implement. This header file contains comments that explain the purpose of each member function. DemoAdaptor.cpp After seeing the definition of the adaptor class, look at the implementation of the class in the DemoAdaptor.cpp file.
1 Getting Started MATLAB Command Breakpoint createInstance() imaqhwinfo(obj) getDriverDescription() getDriverVersion() getMaxWidth() getMaxHeight() getFrameType() videoinput getNumberOfBands() start openDevice() start or trigger, if manual trigger startCapture() stop stopCapture() closeDevice() Building the Demo Adaptor After familiarizing yourself with the demo adaptor source files, build the demo adaptor.
Looking at the Demo Adaptor Note Because the toolbox caches adaptor information, you might need to reset the toolbox, using imaqreset, before a newly registered adaptor appears in the imaqhwinfo listing. For example, the following code registers the demo adaptor with the toolbox using the imaqregister function, where represents the name of the directory where you created the demo adaptor. imaqregister('\mwdemoimaq.
1 Getting Started Preview Windows Containing Demo Adaptor Data 1-12
2 Setting Up Your Build Environment This chapter describes the libraries and include files you need to build an adaptor on Windows, Linux, or Macintosh systems. The chapter also provides details about setting up the build environment in Microsoft Visual C++.
2 Setting Up Your Build Environment Setting up a Build Environment on Windows Systems Setting up the build environment involves specifying the header files and libraries that you need to create an adaptor. For those familiar with their IDE environment, see the following sections for lists of these required include files and libraries. This section also describes how to create an environment variable that you can use to specify the MATLAB installation folder.
Setting up a Build Environment on Windows Systems Header File and Libraries Location Adaptor kit header files $(MATLAB)\toolbox\imaq\imaqadaptors\kit\includea Image Acquisition Toolbox engine library $(MATLAB)\toolbox\imaq\imaqadaptors\kit\lib\\release \imaqmex.lib a. MATLAB is an environment variable that contains the name of your MATLAB installation folder. • For information about defining environment variables, see “Using Environment Variables” on page 2-3.
2 Setting Up Your Build Environment Creating an Adaptor Project Using Microsoft Visual C++ As the first step toward building an adaptor, open Microsoft Visual C++ and create a new project. Note It is strongly recommended that you use a version of Microsoft Visual Studio®. For information on supported versions, see http://www.mathworks.com/support/compilers/ current_release. 1 Set up any required environment variables—see “Using Environment Variables” on page 2-3. 2 Start Microsoft Visual C++ 2010.
Setting up a Build Environment on Windows Systems Select Win32. Select Win32 Project. Specify name and location of project. Click OK. • Click OK. Visual C++ opens the Win32 Application Wizard. 5 In the Win32 Application Wizard, click Application Settings. 6 On the Application Settings page, select DLL from the list of application types and select Empty project from the Additional options section. Click Finish to create the project.
2 Setting Up Your Build Environment Select DLL. Select Empty Project. Click Finish. After you create the project, close the Start Page . Visual C++ displays the project in its Solution Explorer, with separate folders for source files, header files, and other project resources, as shown in the following figure.
Setting up a Build Environment on Windows Systems New Project Recompiling with New Versions of the Image Acquisition Toolbox Software After you have created an adaptor, you generally only need to recompile it for use with new major versions of the Image Acquisition Toolbox software. Adaptor writers should recompile when a major update is released, such as Image Acquisition Toolbox Version 4.0.
2 Setting Up Your Build Environment where matlabroot represents your MATLAB installation folder. Specifying Header File Locations Before you can compile your adaptor, you must specify the locations of the header files required by the adaptor kit and by your device's SDK. For a list of the header files required by the adaptor kit, see “Setting up a Build Environment on Windows Systems” on page 2-2.
Setting up a Build Environment on Windows Systems Select VC++ Directories. Select Include Directories and click Edit. Click OK. 4 Add the locations of adaptor kit header files and the header files required by your device's SDK to the list of folders displayed, each on a separate line. $(MATLAB)\toolbox\imaq\imaqadaptors\kit\include In this example, $(MATLAB) dereferences the environment variable MATLAB, which is set to the name of your installation folder.
2 Setting Up Your Build Environment Specify header file locations. Click OK. 5 After specifying the header file folders, click OK. Specifying Libraries and Library Paths Before you can create your adaptor DLL, you must specify the libraries required by the adaptor kit and by your device's SDK. For a list of required libraries, see “Setting up a Build Environment on Windows Systems” on page 2-2. The following sections describes how to specify these libraries and library paths in Microsoft Visual C++.
Setting up a Build Environment on Windows Systems 3 Expand Configuration Properties and then expand Linker. Select General and, on this page, select Additional Library Directories and click Edit from the menu associated with that row. Select General. Select Additional Library Directories and click Edit. Specify location of library files. Click OK. 4 Add the locations of adaptor kit libraries and the libraries required by your device's SDK in the Additional Library Directories field.
2 Setting Up Your Build Environment on page 2-3. You must replace with the name of an architecture-specific folder, such as, win32 or win64. Specify location of library files. Click OK. Specifying Library Names in Microsoft Visual C++ 2010 To specify the library names, follow this procedure. 2-12 1 Open the Property Pages dialog box (if you do not already have it open): Projects > Properties. 2 Change the Configuration setting (at the top of the dialog box) to All Configurations.
Setting up a Build Environment on Windows Systems Select Input. Select Additional Dependencies and click Edit. Click OK. 4 Specify the names of the adaptor kit libraries and the names of the libraries required by your device's SDK. Use spaces to separate the names of the libraries. The following shows the adaptor kit libraries. imaqmex.
2 Setting Up Your Build Environment Specify library names. Click OK. 5 Click OK. Configuring Other Project Parameters In addition to specifying the header files and libraries, an adaptor project requires these additional settings. If you do not set these parameters, your adaptor might encounter run-time problems. 1 2-14 Add an empty source file to your project. To set the values of these additional properties, your project must contain files.
Setting up a Build Environment on Windows Systems d Add the new source file to your project. From the File menu, select Move Source1.cpp into and select the name of your project. Accept the default file name for now; you can always change it later. 2 Open the Property Pages for your project by right-clicking on your project in the Solution Explorer and choosing Properties, or by selecting Properties from the Project menu. 3 In the Property Pages dialog box, open C/C++ and select Code Generation.
2 Setting Up Your Build Environment Select Code Generation. Set these properties. Click OK. 4 2-16 In the Property Pages dialog box, under C/C++, select Language. On the Language page, set the Enable Run-time Type Information field to Yes (/GR).
Setting up a Build Environment on Windows Systems Select Language. Set this property. Click OK. 5 In the Property Pages dialog box, under C/C++, select Command Line and specify the following compiler flag. Click OK to close the Property Pages dialog box.
2 Setting Up Your Build Environment Select Command Line. Click OK. Specify command line argument. 2-18 Click OK.
Setting up a Build Environment on Linux and Macintosh Systems Setting up a Build Environment on Linux and Macintosh Systems In this section... “Required Libraries and Include Files for Adaptor Development” on page 2-19 “Creating a Makefile Based on the Demo Adaptor Makefile” on page 2-20 Setting up the build environment on Linux and Macintosh systems involves specifying the include file paths, library path, and libraries to link against to create an adaptor.
2 Setting Up Your Build Environment Creating a Makefile Based on the Demo Adaptor Makefile To create a makefile to build your adaptor based on the demo adaptor makefile, follow these instructions. 1 Make a copy of the adaptor kit demo makefile and put it in your adaptor development folder.
Setting up a Build Environment on Linux and Macintosh Systems 8 Save the makefile.
3 Providing Hardware Information This chapter describes how an adaptor provides the toolbox engine with information about the image acquisition device (or devices) available on a user's system. After completing the tasks outlined in this chapter, you will be able to create your adaptor DLL, register it with the toolbox, and see it included in the list of available adaptors returned by imaqhwinfo.
3 Providing Hardware Information Using Adaptor Exported Functions The Image Acquisition Toolbox engine requires that every adaptor export five functions. The toolbox calls these functions to communicate with the device and acquire data. One of your primary tasks as an adaptor writer is to provide implementations of these functions. The following table lists these five exported functions with pointers to sections that provide more detail about how to implement the function.
Using Adaptor Exported Functions MATLAB imaqhwinfo Toolbox Engine Adaptor Engine searches for adaptor DLLs and loads them. initializeAdaptor() Returns list of available adaptors. imaqhwinfo(’adaptor’) Engine queries adaptor to find all devices available through it. getAvailHW() Adds device information to IHardwareInfo object. Returns list of devices and supported formats. videoinput(’adaptor’) Engine queries adaptor for device-specific property information.
3 Providing Hardware Information Creating a Stub Adaptor The easiest way to start building an adaptor is to create a stub implementation, compile and link it, and then test your work. This method can be effective because it provides immediate results and lets you verify that your build environment is setup properly. This section shows a stub implementations of an adaptor that you can copy and paste into a file in your adaptor Microsoft Visual C++ project.
Creating a Stub Adaptor const char* formatName, imaqkit::IPropFactory* devicePropFact, imaqkit::IVideoSourceInfo* sourceContainer, imaqkit::ITriggerInfo* hwTriggerInfo){ // Create a video source sourceContainer->addAdaptorSource("MyDeviceSource", 1); } imaqkit::IAdaptor* createInstance(imaqkit::IEngine* engine, const imaqkit::IDeviceInfo* deviceInfo, const char* formatName){ imaqkit::IAdaptor* adaptor = NULL; return adaptor; } void uninitializeAdaptor(){ } 3 Build the adaptor DLL.
3 Providing Hardware Information Note: At this point in your adaptor development, the DeviceIDs field and the DeviceInfo fields are empty. imaqhwinfo('mydeviceimaq') ans = AdaptorDllName: AdaptorDllVersion: AdaptorName: DeviceIDs: DeviceInfo: 3-6 'C\My_Adaptor\mydeviceimaq.dll' '4.
Performing Adaptor and Device SDK Initialization Performing Adaptor and Device SDK Initialization Every adaptor must include an initializeAdaptor() function. In this function, you should perform any initialization required by your adaptor or your device's SDK. Check the documentation that came with your device to find out what, if any, initialization the SDK requires. For example, some device SDKs provide a function that loads required DLLs into memory.
3 Providing Hardware Information Specifying Device and Format Information Every adaptor must include a getAvailHW() function. In this function, you provide the toolbox with information about the device (or devices) that are currently connected to the user's system. An adaptor can represent one particular device, multiple devices supported by a particular vendor, or a class of devices.
Specifying Device and Format Information format supported by a device, you must create an IDeviceFormat object and then store the object in the IDeviceInfo object. The following figure shows the relationship of these adaptor kit objects. The figure shows the IHardwareInfo object containing two IDeviceInfo objects, but it can contain more. Similarly, each IDeviceInfo object is shown containing two IDeviceFormat objects, but it can also contain more.
3 Providing Hardware Information Your adaptor's getAvailHW() function must provide the engine with the following information for each device: • Device ID • Device name • Formats supported by the device, including the default format • Whether or not the device supports device configuration files (also known as camera files) Note You can optionally store additional device-specific information in the adaptor data of an IDeviceInfo object or an IDeviceFormat object.
Specifying Device and Format Information Suggested Algorithm for getAvailHW() Function Storing Device Information You store device information in an IDeviceInfo object.
3 Providing Hardware Information You can specify any values for these arguments, but note that they are visible to toolbox users in the structure returned by imaqhwinfo. For device name, specify a text string that easily identifies the device. For example, you might use the manufacturer's model number. The ID you specify for the device must be unique because it identifies the device for the adaptor. Because MATLAB indexing starts at 1, start the numbering of device IDs at 1, not zero.
Specifying Device and Format Information Because the ID is not exposed to users, you can specify any convenient value. For example, if the device's SDK uses numerical identifiers to indicate a format, use these values for your format IDs. You can use IDeviceFormat member functions to perform many tasks, such as, retrieving the format name and format ID, and determining whether the format is the default format.
3 Providing Hardware Information Example: Providing Device and Format Information The following example presents a simple implementation of a getAvailHW() function that specifies information for one device with two formats. The intent of this example is to show how you create the objects necessary to store device and format information. If you add this code to the mydeviceimaq adaptor, you can run imaqhwinfo('mydeviceimaq') to view the device information.
Specifying Device and Format Information dev = AdaptorDllName: AdaptorDllVersion: AdaptorName: DeviceIDs: DeviceInfo: 'C:\My_Adaptor\mydeviceimaq.dll' '4.1 (R2011a)' 'mydeviceimaq' {[1]} [1x1 struct] To view detailed information about the device, view the structure in the DeviceInfo field. The DeviceInfo field is an array of structures, where each structure provides detailed information about a particular device. dev_info = dev.
3 Providing Hardware Information Field Description DeviceID Numeric value that uniquely identifies a particular device. You define this value when you create the IDeviceInfo object; see “Storing Device Information” on page 3-11. ObjectConstructor Text string that contains the videoinput function syntax required to create an object instance for this device. The toolbox engine creates this string. SupportedFormats Cell array of strings that identifies the formats this device supports.
Defining Classes to Hold Device-Specific Information Defining Classes to Hold Device-Specific Information You might want to store more information about a device or format than the IDeviceInfo and IDeviceFormat objects allow. One way to do this is to define a new class that contains this additional information. Then, in your adaptor, instantiate an object of this class and store it in the adaptor data of the IDeviceInfo or IDeviceFormat objects.
3 Providing Hardware Information The demo adaptor provides an example, defining a class to hold additional format information. This class, named DemoDeviceFormat, stores format information such as width, height, and color space. The following example, taken from the demo adaptor, shows how to instantiate an object of this derived class, assign values to the data members of the class, and then store the object in the adaptor data of the IDeviceFormat object.
Unloading Your Adaptor DLL Unloading Your Adaptor DLL Every adaptor must include an uninitializeAdaptor() function. The engine calls this function when a user resets the toolbox, by calling the imaqreset function, or exits the MATLAB software. Your adaptor's implementation of this function depends upon the requirements of your hardware. Every adaptor must include the uninitializeAdaptor() function, even if it is an empty implementation.
3 Providing Hardware Information Returning Warnings and Errors to the MATLAB Command Line To return error or warning messages from your adaptor to the MATLAB command line, use the adaptorError() and adaptorWarning() functions. These functions implement an interface similar to the MATLAB error and warning functions. Using these functions, you can display a text message at the MATLAB command line.
4 Defining Your Adaptor Class This chapter describes how to define your adaptor class and instantiate an object of this class. Every adaptor must define a class that is a subclass of the adaptor kit IAdaptor abstract class. This abstract class defines several virtual functions that your adaptor class must implement. This chapter gets you started with an adaptor class implementation by creating a stub implementation.
4 Defining Your Adaptor Class Defining Your Adaptor Class The next four topics describe how to define your adaptor class and instantiate an object of this class. Every adaptor must define a class that is a subclass of the adaptor kit IAdaptor abstract class. This abstract class defines several virtual functions that your adaptor class must implement. The next four topics get you started with an adaptor class implementation by creating a stub implementation.
Using IAdaptor Abstract Class Virtual Functions Using IAdaptor Abstract Class Virtual Functions The following table lists the pure virtual functions defined by the IAdaptor abstract class, in alphabetical order. The Demo adaptor included with the Image Acquisition Toolbox software contains sample implementations of these functions in the file DemoAdaptor.cpp.
4 Defining Your Adaptor Class Pure Virtual Function Description with Declaration getNumberOfBands() Returns the number of bands used in the returned image data — see “Specifying Image Dimensions” on page 5-5. virtual int getNumberOfBands() const; openDevice() Opens a connection with the device, preparing it for use — see “Opening and Closing Connection with a Device” on page 5-10.
Creating Stub Implementation of Your Adaptor Class Creating Stub Implementation of Your Adaptor Class To create a stub implementation of your adaptor class, follow this procedure: 1 Add a C++ header file to the adaptor C++ project. This header file will hold the definition of your adaptor class. You can give your class any name. This example uses the following naming convention: vendor_name + adaptor For this example, the header file that contains the adaptor class definition is named MyDeviceAdaptor.h.
4 Defining Your Adaptor Class 3 Add a C++ source file to the adaptor project. You can give the source file any name. This example names the file mydeviceadaptor.cpp. 4 Copy the following stub implementations of all the adaptor virtual functions into the C++ source file. #include "MyDeviceAdaptor.h" #include "mwadaptorimaq.
Creating Stub Implementation of Your Adaptor Class Exported Functions” on page 3-2. This is needed because the createInstance() exported function instantiates an object of this class. #include "MyDeviceAdaptor.h" 6 Edit the stub implementations of the createInstance() function, also in the exported functions source file, mydevice_exported_fcns.cpp. Make the function instantiate an object of your adaptor class, highlighted in italics below. (In the stub, it returns NULL.
4 Defining Your Adaptor Class Note While you can create a video input object with your adaptor, you cannot use it to acquire video from a device. You must implement the adaptor class acquisition functions to do that. See “Acquiring Image Data” on page 5-2 for more information. vid = videoinput('mydeviceimaq',1) Summary of Video Input Object Using 'MyDevice'. Acquisition Source(s): MyDeviceSource is available. Acquisition Parameters: 'MyDeviceSource' is the current selected source.
Identifying Video Sources Identifying Video Sources The toolbox defines a video source as one or more hardware inputs that are treated as a single entity. For example, an image acquisition device might support an RGB source that is made up of three physical connections. The toolbox would treat the three connections as a single video source. Read the documentation that came with your device to determine the video sources it supports.
4 Defining Your Adaptor Class Because the ID is not exposed to users, you can specify any convenient value. For example, if the device's SDK uses numerical identifiers to indicate a video source, use these values for your source IDs. For example, this code specifies a video source. sourceContainer->addAdaptorSource("MyDeviceSource",1) You can use IVideoSourceInfo member functions to perform many tasks, such as determining the currently selected source.
Instantiating an Adaptor Object Instantiating an Adaptor Object Every adaptor must include a createInstance() function. The engine calls this function to instantiate an object of your adaptor's class.
4 Defining Your Adaptor Class Implementing Your Adaptor Class Constructor Because you write the code that calls your adaptor class constructor, you can define the arguments accepted by your adaptor class constructor. At a minimum, adaptor constructors must accept a handle to an IEngine object that represents the connection between the engine and your adaptor. This is defined by the IAdaptor superclass.
Instantiating an Adaptor Object imaqkit::IAdaptor* createInstance(imaqkit::IEngine* engine, imaqkit::IDeviceInfo* deviceInfo, char* formatName) { // Instantiate an object of your IAdaptor-derived class imaqkit::IAdaptor* adaptor = new MyDeviceAdaptor(engine,deviceInfo,formatName); return adaptor; } Implementing Your Adaptor Class Destructor This destructor is invoked whenever the associated video input object in the MATLAB software is deleted.
4 Defining Your Adaptor Class } 4-14
5 Acquiring Image Data This chapter describes how to implement the adaptor member functions to perform image acquisition. After completing the tasks outlined in this chapter, you will be able to create a video input object, start it, and trigger an acquisition.
5 Acquiring Image Data Acquiring Image Data After completing chapters 3 and 4, you can see your adaptor included in the list of adaptors returned by imaqhwinfo and you can create a video input object using the videoinput function. Now it's time to acquire data from your device. In this chapter, you flesh out the stub implementations of the adaptor class virtual functions that work together to acquire data.
Acquiring Image Data acquire data. With hardware triggers, you start the object and it waits until it receives a signal from an external device to start acquiring data. The toolbox handles immediate and manual triggering automatically; you do not have to include any special processing in your adaptor. Supporting hardware triggers, requires some adaptor development work. For more information, see “Supporting Hardware Triggers” on page 5-27.
5 Acquiring Image Data MATLAB Toolbox Engine start(vid) Make sure device is not already logging. Adaptor open() Start new thread of execution. Start the acquisition. openDevice() startCapture() Send message to thread to begin capturing frames. Get a Frame object from engine. makeFrame() Engine enters loop, buffering frames it receives from the adaptor Loop, acquiring frames, until acquisition is complete. Return handle to Frame object.
Specifying the Format of the Image Data Specifying the Format of the Image Data Before you can acquire data from your device, you must tell the engine the format of the data it can expect to receive from your device. Without this information, the engine does not know how to interpret the data.
5 Acquiring Image Data The engine calls these functions in your adaptor to get the resolution information that it displays in the VideoResolution property of the video input object. vid = videoinput('mydeviceimaq'); get(vid,'VideoResolution') ans = 640 480 Your adaptor also call these functions when it creates the IAdaptorFrame object to receive image data. See “Implementing the Acquisition Thread Function” on page 5-18 for more information.
Specifying the Format of the Image Data names specified in the example in “Specifying Device and Format Information” on page 3-8.
5 Acquiring Image Data Format Frame Types Signed 16- and 32-bit formats; both little-endian and big-endian; in regular and flip formats. Floating-point and double formats; both little-endian and bigendian formats; in regular and flip formats. Color 8-, 24-, 32-, and 48-bit RGB formats; both little-endian and bigendian; regular and flip; packed and planar (see “Understanding Packed and Planar Formats” on page 5-8).
Specifying the Format of the Image Data describe how the bytes of red, green, and blue data are arranged in memory. In packed formats, the red, green, and blue triplets are grouped together. In nonpacked formats, all the red data is stored together, followed by all the green data, followed by all the blue data. The following figure illustrates this distinction. Packed and Planar Formats To get more information about video formats, go to the fourcc.org Web site.
5 Acquiring Image Data Opening and Closing Connection with a Device Adaptors typically open a connection with the device in their openDevice() function and close the connection in their closeDevice() function. For most devices, opening a connection to the device reserves it for exclusive use. Closing the device releases the device.
Opening and Closing Connection with a Device HANDLE CreateThread( LPSECURITY_ATTRIBUTES lpThreadAttributes, SIZE_T dwStackSize, LPTHREAD_START_ROUTINE lpStartAddress, LPVOID lpParameter, DWORD dwCreationFlags, LPDWORD lpThreadId ); For an adaptor, the following table lists the parameters you must set. For complete information about creating a thread, see the documentation at the Microsoft Developer Network Web site (msdn.microsoft.com).
5 Acquiring Image Data return true; // Create the image acquistion thread. _acquireThread = CreateThread(NULL, 0, acquireThread, this, 0, &_acquireThreadID); if (_acquireThread == NULL) { closeDevice(); return false; } // Wait for thread to create message queue. while(PostThreadMessage(_acquireThreadID,WM_USER+1,0,0) == 0) Sleep(1); return true; } 2 To be able to compile and link your adaptor, you must create a stub implementation of your acquireThread() function and add it to your adaptor.
Opening and Closing Connection with a Device private: // Declaration of acquisition thread function static DWORD WINAPI acquireThread(void* param); // Thread variable HANDLE _acquireThread; // Thread ID returned by Windows. DWORD _acquireThreadID; 4 Compile and link your adaptor. You should be able to create a video input object. When you call the start function, verify that your adaptor successfully created the acquisition thread.
5 Acquiring Image Data WaitForSingleObject(_acquireThread, 10000); // Close thread handle.
Starting and Stopping Image Acquisition Starting and Stopping Image Acquisition Once openDevice() returns successfully, the engine calls your adaptor's startCapture() function to start acquiring data. The engine calls your adaptor's stopCapture() function when a user calls the stop or closepreview function on a video input object, or when the specified number of frames has been acquired and the acquisition is complete.
5 Acquiring Image Data The PostThreadMessage() function accepts these parameters: BOOL PostThreadMessage( DWORD idThread, UINT Msg, WPARAM wParam, LPARAM lParam ); The following table describes how to set these parameters for an adaptor. For more information about sending thread messages, see the documentation at the Microsoft Developer Network Web site (msdn.microsoft.com). Parameter Description idThread Identifier of the thread to which the message is to be posted, returned by CreateThread().
Starting and Stopping Image Acquisition Suggested Algorithm for stopCapture() The stopcapture() function typically performs these tasks. 1 Checks whether the adaptor is already stopped by calling the isAcquiring() function. If the device is not currently acquiring data, return true. 2 Stops the frame acquisition loop and stops the device, if necessary Note It is important not to exit the stopCapture() function while the acquisition thread function is still acquiring frames.
5 Acquiring Image Data Implementing the Acquisition Thread Function This section describes how to implement your adaptor's acquisition thread function. In a threaded adaptor design, the acquisition thread function performs the actual acquisition of frames from the device. When you create the thread (“Opening and Closing Connection with a Device” on page 5-10), you specify the name of this acquisition thread function as the starting address for the new thread.
Implementing the Acquisition Thread Function When it receives the appropriate message, the acquisition thread function enters the frame acquisition loop. The following figure illustrates this interaction between your adaptor functions and the acquisition thread. For information about the frame acquisition loop, see “Frame Acquisition Loop” on page 5-20. Acquisition thread openDevice() startCapture() Start acquisition thread.
5 Acquiring Image Data Frame Acquisition Loop The frame acquisition loop is where your adaptor acquires frames from the device and sends them to the engine. This process involves the following steps: 1 Check whether the specified number of frames has been acquired. The frame acquisition loop acquires frames from the device until the specified number of frames has been acquired. Use the IAdaptor member function isAcquisitionNotComplete() to determine if more frames are needed.
Implementing the Acquisition Thread Function d Send the packaged frame to the engine, using the IEngine member function receiveFrame(). 5 Increment the frame count using the IAdaptor member function incrementFrameCount(). Whether you need to send a frame or not, you must always increment the frame count whenever you acquire a frame. 6 Return to the top of the frame acquisition loop. The following figure illustrates the frame acquisition loop.
5 Acquiring Image Data Your thread function must accept a single parameter, which is defined as a pointer to the object itself, i.e., the this pointer. The thread function returns a value that indicates success or failure. For more information, see the documentation at the Microsoft Developer Network Web site (msdn.microsoft.com). The following is an acquisition thread function that you can use with the example MyDeviceAdaptor.
Implementing the Acquisition Thread Function } // while(isAcquisitionNotComplete() break; } //switch-case WM_USER } //while message is not WM_QUIT return 0; } 5-23
5 Acquiring Image Data Supporting ROIs The toolbox supports the specification of regions of interest (ROIs) in both software and hardware. The following sections provide more information. In this section... “Implementing Software ROI” on page 5-24 “Implementing Hardware ROI” on page 5-26 Implementing Software ROI When using a software ROI, a toolbox user sets the dimensions of the ROI in the ROIPosition property. The device returns the entire image frame.
Supporting ROIs Note You use the ROI width and height when you create the frame but you use the full image width and height when you copy the image data from the buffer into the frame object. Example The following is a version of the isSendFrame() loop in the acquisition thread function that checks the ROI. Note that you call the getROI() function to get the ROI values, and then use the width and height values in the call to makeFrame() and the offsets from the origin in the call to setImage().
5 Acquiring Image Data } // if isSendFrame() Implementing Hardware ROI For hardware ROI, the user defines the ROI on the device. The device returns only the data in the specified ROI. To implement hardware ROI, you must overload both the IAdaptor's getROI() and setROI() member functions in your implementation of your adaptor class. By default, if the IAdaptor object's getROI() member function is not overloaded, ROI configurations will be handled in software by imaqkit::IEngine.
Supporting Hardware Triggers Supporting Hardware Triggers The toolbox supports three types of triggers: • Immediate — Trigger fires when video input object is started. • Manual — Trigger fires when user calls trigger function. • Hardware — Trigger fires when externally defined conditions are met The engine provides automatic support for immediate and manual triggers.
5 Acquiring Image Data Main Acquisition Loop with Test for Hardware Trigger Example The following is an acquisition thread function that includes a call to check for hardware trigger.
Supporting Hardware Triggers // Add code here to configure the image // acquisition device for hardware // triggering. } if (adaptor->isSendFrame()) { // see acquistion thread } // if isSendFrame() // Increment the frame count.
5 Acquiring Image Data Using Critical Sections This section describes how to use critical sections to protect portions of your adaptor code. The section describes the adaptor kit's main critical section class, ICriticalSection, and the ancillary class, IAutoCriticalSection, that you use to manage critical sections.
Using Critical Sections The auto critical section object ensures that you always exit a critical section. However, you must also ensure that the auto critical section itself gets deleted. To do this, the adaptor kit recommends managing the handle to the IAutoCriticalSection object, returned by createAutoCriticalSection(), as an auto_ptr using the std::auto_ptr<> template class from the Standard Template Library. The auto_ptr helps ensure that the IAutoCriticalSection handle is deleted.
5 Acquiring Image Data done. Insert this code just before the acquisition thread function breaks out of the frame acquisition loop — see “Implementing the Acquisition Thread Function” on page 5-18. You can use the IAutoCriticaSection::leave() function but this is not necessary. The IAutoCriticalSection leaves the critical section automatically when the code section goes out of scope.
Specifying Device Driver Identification Information Specifying Device Driver Identification Information Two of the virtual functions you must implement return identification information about the device driver used to communicate with your device. This information can be useful for debugging purposes. • getDriverDescription() — Returns a text string that identifies the device. • getDriverVersion() — Returns a text string that specifies the version of the device driver.
5 Acquiring Image Data const char* MyDeviceAdaptor::getDriverVersion() const { return "1.0.
6 Defining Device-Specific Properties This chapter describes how to define the properties that toolbox users can use to configure various attributes of a device. These properties can control aspects of the image acquired, such as brightness, behavior of the device, such as shutter speed, and other device-specific characteristics.
6 Defining Device-Specific Properties Defining Device-Specific Properties You define which properties of your image acquisition device you want to expose to toolbox users. You make this determination by reading the device SDK documentation, determining its capabilities, and deciding which capabilities toolbox users will expect to configure.
Defining Device-Specific Properties Device Specific Properties: Brightness = -10 Contrast = 266 Exposure = 1024 ExposureMode = auto Hue = 0 Saturation = 340 Sharpness = 40 Suggested Algorithm When a user calls the videoinput function, the engine calls the getDeviceAttributes() function to set up any device-specific properties you have defined for the device.
6 Defining Device-Specific Properties 1 Determine the device the user wants to establish a connection with, specified by device ID. 2 Determine the format the user wants to use with the device, specified by format name (or the path of a camera file). To get format information, retrieve the IDeviceFormat object associated with the format from the IDeviceInfo object. 3 Create any device-specific properties.
Creating Device Properties Creating Device Properties To define properties for a device, follow this procedure: 1 Create the property using the appropriate IPropFactory member function for the data type. The engine passes in a handle to a IPropFactory object to the getDeviceAttributes() function. For example, to create a property of type double, use the createDoubleProperty() method of the IPropFactory object, specifying the property name and default value as arguments.
6 Defining Device-Specific Properties For example, use the createDoubleProperty() function to create a property whose value is of type double. hprop = devicePropFact->createDoubleProperty("MyDoubleProp",2.5) For the int and double types, you can also specify properties that have pairs of values or values within a defined range. For example, this code creates an integer property with upper and lower bounds.
Creating Device Properties // Create a property of type double with a default value hProp = devicePropFact->createDoubleProperty("MyDoubleProp",2.5); // Specify when the property value can be modified. devicePropFact->setPropReadOnly(hProp, imaqkit::imaqengine::READONLY_ALWAYS); // Add the property to the device-specific property container.
6 Defining Device-Specific Properties Type = videosource Device Specific Properties: MyDoubleProp = 2.
Defining Hardware Trigger Configurations Defining Hardware Trigger Configurations To define hardware trigger configurations, use the addConfiguration() function of the ITriggerInfo object. The engine passes a handle to an ITriggerInfo object to your adaptor's getDeviceAttributes() function.
6 Defining Device-Specific Properties Implementing Get and Set Support for Device-Specific Properties After connecting to a device through your adaptor, users might want to view or modify values of the properties of the device. For example, a user might adjust the value of the Brightness property or retrieve the current value of the Temperature property. (For information about how to define the properties you want to expose to users, see “Creating Device Properties” on page 6-5.
Implementing Get and Set Support for Device-Specific Properties In this example, the constructor accepts a handle to an IAdaptor object. Because the toolbox establishes listeners on a per-instance basis, passing this handle can be helpful, but it is not a requirement. The IPropCustomGetFcn class defines one virtual function: the getValue() member function. In this function, you define how your adaptor responds when a user requests the current value of a property.
6 Defining Device-Specific Properties IPropInfo functions you can retrieve the property name, its storage type and its default value. This information is useful if you have a generic listener class that handles multiple properties. • value is a pointer to the location in memory where your adaptor stores the requested property value.—The engine passes this value as a void*. Your getValue() function must cast the value to the appropriate C++ data type.
Implementing Get and Set Support for Device-Specific Properties Example This example shows an implementation of a getValue() function for integer types: void MyDevicePropGetListener::getValue(IPropInfo* propertyInfo, void* value) { // Get property name from the IPropInfo object. const char* propname = propertyInfo->getPropertyName(); // Get the value using whatever facility your device's SDK provides. *reinterpret_cast(value) = sdk_function_get(); // For debug purposes only.
6 Defining Device-Specific Properties The following example iterates through all properties in the adaptor property container, associating a get listener object with each one. void MyDeviceAdaptor::MyDeviceAdaptor() { // get a handle to the property container IPropContainer* propContainer = getEngine()->getAdaptorPropContainer(); // Determine the number of properties in the container.
Implementing Get and Set Support for Device-Specific Properties Defining a Set Listener Class Create a set listener class, deriving it from the abstract class IPropPostSetListener, as shown in the following example. (The name of the class includes the word Post because the toolbox notifies listeners after it updates the property value stored in the container.) In this example, the constructor accepts a handle to an IAdaptor object.
6 Defining Device-Specific Properties // The new value for double properties. double _lastDoubleValue; // The new value for string properties. char* _lastStrValue; }; Creating the notify() Function for Your Class When a user calls the set command to change the value of a property, the engine calls the notify() function of the set listener class associated with the property.
Implementing Get and Set Support for Device-Specific Properties Alternatively, you could define a separate set listener class for each property or each property storage type. Then, the engine calls the specific listener for the property specified. You also can define set listener classes that fit the way the SDK organizes property configuration. For example, if an SDK provides one function to configure all device properties, you can define a set listener class for these properties.
6 Defining Device-Specific Properties getEngine()->getAdaptorPropContainer(); 2 Add a set listener to a property in the container, using the IPropContainer object's addListener() function. As arguments, specify the property name and a handle to the listener object. Note Because the toolbox deletes each instance of a listener object when a user deletes the video input object, associate a new instance of a listener object with each property.
Implementing Get and Set Support for Device-Specific Properties delete [] devicePropNames; } 6-19
7 Storing Adaptor Information in an IMDF File This chapter describes how to store information about adaptor properties in an Image Device File (IMDF) in an XML based format.
7 Storing Adaptor Information in an IMDF File Using the IMDF Markup Language This chapter describes how to use an XML-based markup language to specify source, property, and hardware trigger information in an Imaging Device File (IMDF). Note Creating an IMDF is required. Using an IMDF file can simplify the coding of your adaptor's getDeviceAttributes() function. In addition, it is the only convenient way to make help text available for the device-specific properties your adaptor creates.
Using the IMDF Markup Language Hierarchy of IMDF Elements 7-3
7 Storing Adaptor Information in an IMDF File Creating an IMDF File: Toplevel Elements The ImageAcquisitionInfo element must be the root node of all IMDF files. Your IMDF file must begin with the ImageAcquisitionInfo node and end with the corresponding ImageAcquisitionInfo terminator, as in this example. . . . The following table lists the toplevel IMDF elements that you can specify as children of the ImageAcquisitionInfo element.
Specifying Help in an IMDF File Specifying Help in an IMDF File To define help text for adaptor properties in an IMDF file, use the Help element. You can include only one Help node in an IMDF file and it must be a child of the root node. As children of the Help node, you create AdaptorHelp nodes that contain the help text for a particular property. You use the name attribute of the AdaptorHelp element to specify which property the help is associated with.
7 Storing Adaptor Information in an IMDF File Element Description Attributes Defines the help section in an None IMDF file. Must be child of the ImageAcquisitionInfo node. Defines the online help for a property. The Help node can contain one or more AdaptorHelp nodes. property=name, where name is a text string specifying the property name Specifies device-specific text in property help. This element is optional.
Specifying Help in an IMDF File The items in this list correspond to the numbered elements above. 1 Device-specific properties are properties of the video source object. The example creates the video input object and then uses the getselectedsource function to get a handle to the video source object. 2 The example uses the get function to display a list of device-specific properties. 3 Use the imaqhelp function to display help for one of the properties of the video source object.
7 Storing Adaptor Information in an IMDF File 4 The first line of the help lists the name of the property with its constraints, such as range and permission. 5 The text of the help appears exactly as you enter it in the IMDF file. You include the text after the AdaptorHelp tag. 6 The See Also line is created by the SeeAlso node. Creating AdaptorHelp Nodes This section describes how to create help text for a property using the set of help tags defined by the IMDF DTD.
Specifying Help in an IMDF File Upon enabling the strobe output, it will start detection of triggers and generate output as appropriate. Consult your hardware manual for a detailed description of the strobe output. See also StrobeMode, StrobeDuration, StrobeDelay, StrobePolarity, StrobeAlignOnHs. See also StrobeMode, StrobeDelay, StrobePolarity.
7 Storing Adaptor Information in an IMDF File Specifying Device Information To specify information about a particular device in an IMDF file, use the Device element. You can include as many Device nodes in an IMDF file as you want but they must all be children of the root node. In a Device node, you specify the name of the device as an attribute. The name is typically a text string defined by the device's SDK.
Specifying Device Information The following table summarizes the elements that can be children of a Device node, in the order they must be specified. For an example, see “Example: Device Node” on page 7-11. Element Description Attributes Specifies information about a video format. This is an optional element. A Device node can contain multiple VideoFormat nodes.
7 Storing Adaptor Information in an IMDF File PAGE 145Specifying Property Information Specifying Property Information To specify property information in an IMDF file, use the Property element. You can include as many Property nodes in an IMDF file as you want. Property nodes can be children of the root node, a Device node, or a Videoformat node. Property nodes can also be children of Section nodes. Note Property nodes that are children of the root node affect all devices accessed through the adaptor.
7 Storing Adaptor Information in an IMDF File Specifying Property Element Attributes The following table lists the attributes of a Property node in alphabetical order. The table gives a brief description of the property and lists which properties are required and which are optional. Attribute Description Required constraint Specifies the constraints on the property — Required see “Specifying Values for the Constraint Attribute” on page 7-14. default Default value for the property.
Specifying Property Information Constraint Value Description bounded Property has both a minimum and maximum value. If you set the constraint attribute to bounded, you must assign values to the min and max attributes. enum Property is an enumerated value. If set, the Property node must contain one or more EnumConstraintValue nodes. See “Specifying Enumerated Values” on page 7-15.
7 Storing Adaptor Information in an IMDF File Specifying Format Information To specify the video formats supported by a particular device in an IMDF file, use the VideoFormat element. VideoFormat nodes must be children of Device nodes. In the VideoFormat node, you specify the name of the format as the value of an attribute of the element. You can also specify format-specific property and trigger information, if necessary. A VideoFormat node can have Property and TriggerInfo nodes as children.
Specifying Format Information Element Description Attributes This is an optional element. A identifies a particular Section VideoFormat node can contain node multiple Include nodes. Groups one or more nodes into a Section node. This is an optional element. A VideoFormat node can contain multiple Section nodes. Describes the properties See “Specifying Property of a video format. This is Information” on page 7-13. an optional element.
7 Storing Adaptor Information in an IMDF File Specifying Hardware Trigger Information To specify hardware trigger information in an IMDF file, use the TriggerInfo node. A TriggerInfo node can be the child of the ImageAcquisitionInfo, Device, VideoFormat, and Section nodes. You specify the source of the hardware trigger in a TriggerSource node that is the child of the TriggerInfo node.
Specifying Hardware Trigger Information Element Description Attributes can contain zero or more TriggerCondition nodes. Specifying Trigger Sources When you define a hardware trigger, you must define the source (or sources) of the hardware trigger in one or more TriggerSource nodes. In a TriggerSource node, you specify values for two attributes: name and id. The value of the name attribute is visible to users of the toolbox in the display returned by the toolbox triggerinfo function.
7 Storing Adaptor Information in an IMDF File Specifying Video Sources To specify the video source in an IMDF file, use the Source element. A Source node can only be the child of the IMDF root element and it cannot have any child nodes of its own. When you create a Source node, you must specify values for two attributes: name and id. In the name attribute, you specify the name of the source as it appears in the video source object's Name property.
Defining and Including Sections Defining and Including Sections You can gather one or more Property or TriggernInfo nodes into a group by using the Section element. A Section node can contain one or more Property nodes or a single TriggerInfo node or another Section node. A Section node can be the child of a Device, or VideoFormat node. Using the Include element, a Section node can be indirectly be a child of the root node, Device, VideoFormat, Section, or TriggerInfo nodes.
8 Test Suite for Adaptor Writers • “Testing Adaptors or Hardware” on page 8-2 • “Creating a Stub Adaptor Test Procedure” on page 8-3 • “Specifying Format of Image Data Test Procedure” on page 8-6 • “Implementing the Acquisition Thread Function Test Procedure” on page 8-7 • “Supporting ROIs Test Procedure” on page 8-8 • “Specifying Device Driver Identification Information Test Procedure” on page 8-9 • “Using the Test Suite Functions and Properties” on page 8-11
8 Test Suite for Adaptor Writers Testing Adaptors or Hardware As part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and automated tests for third-party adaptor developers and camera vendors to test adaptors and hardware against the toolbox. • Third-party adaptor writers can use this test suite to verify their adaptors. • Camera vendors can use the automated tests to test their cameras against the Image Acquisition Toolbox.
Creating a Stub Adaptor Test Procedure Creating a Stub Adaptor Test Procedure As part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and automated tests for third-party adaptor developers and camera vendors to test adaptors and hardware against the toolbox. This test procedure is part of that suite. For more information, see “Testing Adaptors or Hardware” on page 8-2.
8 Test Suite for Adaptor Writers Test Procedures Expected Results devInfo(:).DeviceInfo DefaultFormat: '640x480' DeviceFileSupported: 0 DeviceName: 'MyDevice' DeviceID: 1 ObjectConstructor: 'videoinput ('mydeviceimaq', 1)' SupportedFormats: {'640x480' '320x240'} where, DefaultFormat is the format for which the second argument to addDeviceFormat is set to true. DeviceFileSupported is true (1) if the device supports device files. DeviceName is the name of the device as defined in createDeviceInfo.
Creating a Stub Adaptor Test Procedure Test Procedures vidObj = videoinput ('AdaptorName') Expected Results format without any error and its details should be displayed at the MATLAB command prompt. This will not work if only device files are supported. The details should be similar to: Summary of Video Input Object Using 'MyDevice'. Acquisition Source(s): MyDeviceSource is available. Acquisition Parameters: 'MyDeviceSource' is the current selected source. 10 frames per trigger using the selected source.
8 Test Suite for Adaptor Writers Specifying Format of Image Data Test Procedure As part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and automated tests for third-party adaptor developers and camera vendors to test adaptors and hardware against the toolbox. This test procedure is part of that suite. For more information, see “Testing Adaptors or Hardware” on page 8-2.
Implementing the Acquisition Thread Function Test Procedure Implementing the Acquisition Thread Function Test Procedure As part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and automated tests for third-party adaptor developers and camera vendors to test adaptors and hardware against the toolbox. This test procedure is part of that suite. For more information, see “Testing Adaptors or Hardware” on page 8-2.
8 Test Suite for Adaptor Writers Supporting ROIs Test Procedure As part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and automated tests for third-party adaptor developers and camera vendors to test adaptors and hardware against the toolbox. This test procedure is part of that suite. For more information, see “Testing Adaptors or Hardware” on page 8-2.
Specifying Device Driver Identification Information Test Procedure Specifying Device Driver Identification Information Test Procedure As part of the Image Acquisition Toolbox Adaptor Kit, we now offer a test procedure and automated tests for third-party adaptor developers and camera vendors to test adaptors and hardware against the toolbox. This test procedure is part of that suite. For more information, see “Testing Adaptors or Hardware” on page 8-2.
8 Test Suite for Adaptor Writers Test Procedures Expected Results SourceName = input1 Tag = Type = videosource Device-specific Properties: Brightness = -10 Contrast = 266 Exposure = 1024 ExposureMode = auto Hue = 0 Saturation = 340 Sharpness = 40 The actual property names will be based on the information provided by the adaptor. To clean up after this step, delete and clear the object. Run the following command: vidObj = videoinput ('AdaptorName'); preview(vidObj); src = getselectedsource(vidObj); src.
Using the Test Suite Functions and Properties Using the Test Suite Functions and Properties In this section... “Test Suite Properties” on page 8-11 “Test Suite Functions” on page 8-12 “Test Suite Example” on page 8-16 Test Suite Properties The following properties can be used in the imaqkit.AdaptorTest functions. Property Description AdaptorName Name of the Image Acquisition Toolbox adaptor you are creating, as defined by the constructor.
8 Test Suite for Adaptor Writers Property Description • current test name • current test details/information • any applicable information on how to interpret the results • test condition under test • test results Test Suite Functions You can use these functions with the imaqkit.AdaptorTest class. The imaqkit.AdaptorTest class is used to create an Image Acquisition Toolbox Adaptor Test object and to test Image Acquisition Toolbox connectivity with cameras/framegrabbers.
Using the Test Suite Functions and Properties Function runAllAutomatedTests Purpose For automated testing, run all automated tests. This runs all test points. For an imaqkit.AdaptorTest object called testObj, use this syntax: testObj.runAllAutomatedTests runAutomatedObjectCreation AndPreviewTest For automated testing, run automated object creation and preview test. This test creates an object with the specified parameters and then previews it.
8 Test Suite for Adaptor Writers Function runAutomatedRepeated AcquisitionTest Purpose For automated testing, run automated repeated acquisition test. This test does 25 acquisitions from the same device. For an imaqkit.AdaptorTest object called testObj, use this syntax: testObj.runAutomatedRepeatedAcquisitionTest runAutomatedImmediate TriggerTest For automated testing, run automated trigger test for immediate triggering. This test checks acquiring images in Immediate trigger mode.
Using the Test Suite Functions and Properties Function runAutomatedHardware TriggerTest Purpose For automated testing, run automated trigger test for hardware triggering. This test checks the imaqkit.AdaptorTest object in hardware trigger mode. It checks that frames are not acquired when the object is waiting for a trigger. To test triggering using hardware trigger, refer to Image Acquisition Toolbox documentation. For an imaqkit.AdaptorTest object called testObj, use this syntax: testObj.
8 Test Suite for Adaptor Writers Function Purpose methods Get the list of tests that can be run. For an imaqkit.
Using the Test Suite Functions and Properties This example shows the basic workflow of creating and running a test using some of the functions outlined in the previous section. Get installed hardware information recognizable using the winvideo adaptor. info = imaqhwinfo('winvideo'); Identify the Device IDs. info.DeviceIDs Get information about available formats for the camera under test identified in the last step. If it is the first camera, use DeviceId of 1. info.DeviceInfo(1).
