Imatest IT/.NET Acquisition Library

Introduction

The Imatest IT/.NET Acquisition Library is a .NET Dynamic Link Library (DLL) that enables developers to directly acquire images from supported devices. The images returned by the Acquisition Library can then be passed to the Imatest IT/.NET library for analysis by Imatest’s powerful image quality analysis routines. The Imatest IT/.NET Acquisition Library supports the same devices and interfaces as Imatest IS:

Referencing the Imatest IT/.NET Acquisition Library

Adding References to the Imatest.IT and Imatest.Acquisition DLLs

To use the Imatest IT/.NET Acquisition Library, first add references to Imatest.Acquisition.dll and Imatest.IT.dll to your .NET project. In the Solution Explorer of your project, right-click on the References folder and choose Add Reference…

This will open the Reference Manager. Click Browse on the left side of the window, then click the Browse… button at the bottom.

Navigate to C:\Program Files\Imatest\v4.5\IT\libs\library\.NET, select Imatest.IT.dll, and click Add (you do not need to add IT.dll to your project).

The Imatest.IT.dll has now been added as a reference to your project.

Repeat the same process again, navigating to C:\Program Files\Imatest\v4.5\IT\libs\acquisition\.NET and selecting Imatest.Acquisition.dll (you do not need to add “Acquisition.dll”).

Click OK to close the Reference Manager. You should now have two new references listed in the Solution Explorer, Imatest.Acquisition and Imatest.IT.

Activating Imatest IT/.NET

Before using Imatest IT/.NET, you need to activate your installation, even if you are using a trial version. To activate, run the Imatest IT License Manager, found at C:\Program Files\Imatest\v4.5\IT\bin\licensemanager.exe and follow the instructions here.

Using the Imatest IT/.NET Acquisition Library

The AcquisitionLibrary class

All of the functionality of the Imatest IT/.NET Acquisition Library is contained within the AcquisitionLibrary class. To use the library, you must first create an instance of the AcquisitionLibrary class. Although not required, we recommend wrapping the instance inside of a using() block, especially if you are using a floating license. The AcquisitionLibrary class implements IDisposable, and at the end of the using() block, the Dispose() method is called. This will release the current active seat back to the licensing server, allowing others to use it while the AcquisitionLibrary is not in use. If you choose not to use the using() block, then the Dispose() method will be called at the whim of the .NET garbage collector.

using (AcquisitionLibrary acqLib = new AcquisitionLibrary())
{
/// Use acqLib to acquire images...
...
} /// Here, Dispose() will be called

Constant and Dynamic Device Objects

The Imatest IT/.NET Acquisition Library acquires images using objects of type Device. There are two types of Device objects, “constant” and “dynamic”.

Each of the constant devices has its own matching specific AcquireImageFrom*() method and ImatestAcquireOptions class (see the Examples below).

Dynamic Devices and AcquisitionLibrary.ListDevices()

All other supported devices are discovered at runtime using the AcquisitionLibrary.ListDevices() method (these are “dynamic” devices). The ListDevices() method returns a List<Device> collection of all of devices currently connected to the computer. Any of these Device objects can then be passed into the AcquisitionLibrary.AcquireFromToolboxDevice() method (see the Examples below).

The below code snippet fetches all of the available dynamic devices and prints their names to the console, along with each of their default and supported image formats:

When acquiring from a dynamic device, you can supply any of the supported formats as the VideoFormat property of the ImatestAcquireToolboxDeviceOptions object, or use the Device.DefaultFormat property (see the Examples below).

Configuring Devices

Some devices may require additional configuration using the Imatest IS Device Manager (see here for more details). If you have configured a device and saved its settings to a JSON file (such as ImageAcqToolboxSettings.json), then this file must reside in the same directory as the INI file you are using.

Acquiring Images

Images are loaded using the AcquireFrom*() methods in the AcquisitionLibrary class. Constant devices have their own specific methods (AcquireFromEpiphan(), AcquireFromOmnivisionOVTA(), etc.), while dynamic devices share a single generic method (AcquireFromToolboxDevice()). Each AcquireFrom*() method accepts an ImatestAcquireOptions object specific to its device (ImatestAcquireEpiphanOptions, ImatestAcquireOmnivisionOVTAOptions, ImatestAcquireToolboxDeviceOptions, etc.). Each options object must have at least the Filename and Extension properties set, along with other device-specific options. Examples of populating the various ImatestAcquireOptions objects can be found below.

Calls to the AcquireFrom*() methods all return an ImatestAcquireResult object. The ImatestAcquireResult class contains a boolean Success property, which is true if there were no errors during the acquisition, and false otherwise. The ImatestAcquireResult.Image property is an ImatestImage object that can be passed directly to any of the Imatest IT/.NET image analysis module methods. For more information on using the Imatest IT/.NET analysis methods, see here.

Examples

Acquiring from a Dynamic Device

This example demonstrates loading an image from a dynamic device object and passing it to the Imatest IT/.NET Stepchart module for testing, then printing the results to the console.