Imatest IT/.NET Acquisition Library

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 a reference 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\v2021.1\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.

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\v2021\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 (Library lib = new Library())
{
                
    /// Use lib 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”.

Constant Devices

Constant devices already exist as static objects within the Device class, and represent specific imaging devices or interfaces:

Imatest.Acquisition.Device.Epiphan // Epiphan frame grabbers
Imatest.Acquisition.Device.OmnivisionOVTA // Omnivision OVTA devices
Imatest.Acquisition.Device.ToshibaImaTuning // Toshiba ImaTuning devices
Imatest.Acquisition.Device.STMConduit // STM Conduit devices
Imatest.Acquisition.Device.GraphinEasyLab // Graphin EasyLab devices
Imatest.Acquisition.Device.ONSemiDevWare // ON Semi DevWare devices
Imatest.Acquisition.Device.AndroidCameraInterface // Android Camera Interface

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

Dynamic Devices and Library.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:

var otherDevices = lib.ListDevices();
                
foreach(Imatest.Acquisition.Device device in otherDevices)
{
    Console.Out.WriteLine(device.DeviceName);
    Console.Out.WriteLine(string.Format("Default Format: {0}", device.DefaultFormat));
    Console.Out.WriteLine("Supported Formats:");

    foreach(string format in device.SupportedFormats)
    {
        Console.Out.WriteLine(string.Format("    {0}", format));
    }
}

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

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        var otherDevices = lib.ListDevices();

        Device device = otherDevices[0];

        ImatestAcquireToolboxDeviceOptions toolboxDeviceOptions = new ImatestAcquireToolboxDeviceOptions();

        toolboxDeviceOptions.Extension = "bmp";
        toolboxDeviceOptions.Filename = "test_image.bmp";
        toolboxDeviceOptions.VideoFormat = device.DefaultFormat;

        ImatestAcquireResult acqResult = lib.AcquireFromToolboxDevice(device, toolboxDeviceOptions);
        
        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.Stepchart.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring using an Epiphan Device

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

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireEpiphanOptions epiphanOptions = new ImatestAcquireEpiphanOptions();

        epiphanOptions.EpiphanChannel = 0;
        epiphanOptions.Extension = "bmp";
        epiphanOptions.Filename = "test_image.bmp";

        ImatestAcquireResult acqResult = lib.AcquireFromEpiphan(epiphanOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.Colorcheck.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from an Omnivision OVTA Device

This example demonstrates loading an image from an Omnivision OVTA device and passing it to the Imatest IT/.NET SFRplus module for testing, then printing the results to the console.

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireOmnivisionOVTAOptions omnivisionOptions = new ImatestAcquireOmnivisionOVTAOptions();

        omnivisionOptions.Extension = "bmp";
        omnivisionOptions.Filename = "test_image.bmp";
        omnivisionOptions.IniFilePath = Path.Combine(rootDir, "imatest-v2.ini");

        ImatestAcquireResult acqResult = lib.AcquireFromOmnivisionOVTA(omnivisionOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.SFRplus.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from a Toshiba ImaTuning Device

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

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireToshibaImaTuningOptions toshibaOptions = new ImatestAcquireToshibaImaTuningOptions();

        toshibaOptions.Extension = "bmp";
        toshibaOptions.Filename = "test_image.bmp";

        ImatestAcquireResult acqResult = lib.AcquireFromToshibaImaTuning(toshibaOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.Blemish.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from an STM Conduit Device

This example demonstrates loading an image from an STM Conduit device and passing it to the Imatest IT/.NET Wedge module for testing, then printing the results to the console.

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireSTMConduitOptions stmConduitOptions = new ImatestAcquireSTMConduitOptions();

        stmConduitOptions.Extension = "bmp";
        stmConduitOptions.Filename = "test_image.bmp";

        ImatestAcquireResult acqResult = lib.AcquireFromSTMConduit(stmConduitOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.Wedge.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from a Graphin EasyLab Device

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

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireGraphinEasyLabOptions graphinEasyLabOptions = new ImatestAcquireGraphinEasyLabOptions();

        graphinEasyLabOptions.Extension = "bmp";
        graphinEasyLabOptions.Filename = "test_image.bmp";

        ImatestAcquireResult acqResult = lib.AcquireFromGraphinEasyLab(graphinEasyLabOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.SFRreg.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from an ON Semi DevWare Device

This example demonstrates loading an image from an ON Semi DevWare device and passing it to the Imatest IT/.NET eSFRISO module for testing, then printing the results to the console.

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireONSemiDevWareOptions onSemiDevWareOptions = new ImatestAcquireONSemiDevWareOptions();

        onSemiDevWareOptions.Extension = "bmp";
        onSemiDevWareOptions.Filename = "test_image.bmp";

        ImatestAcquireResult acqResult = lib.AcquireFromONSemiDevWare(onSemiDevWareOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.eSFRISO.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from an Android Camera Interface Device

This example demonstrates loading an image from an Android Camera Interface device and passing it to the Imatest IT/.NET Random module for testing, then printing the results to the console.

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireAndroidCameraInterfaceOptions androidOptions = new ImatestAcquireAndroidCameraInterfaceOptions();

        androidOptions.Extension = "bmp";
        androidOptions.Filename = "test_image.bmp";

        ImatestAcquireResult acqResult = lib.AcquireFromAndroidCameraInterface(androidOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.Random.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Acquiring from a File

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

    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());

        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;

        ImatestAcquireFromFileOptions fromFileOptions = new ImatestAcquireFromFileOptions();

        fromFileOptions.Extension = "bmp";
        fromFileOptions.Filename = "test_image.bmp";
        fromFileOptions.ImageFilePath = @"C:\Program Files\Imatest\v4.5\IT\samples\images\stepchart_example.jpg";
        fromFileOptions.IniFilePath = Path.Combine(rootDir, "imatest-v2.ini");

        ImatestAcquireResult acqResult = lib.AcquireFromFile(fromFileOptions);

        if (acqResult.Success)
        {
            ImatestImage img = acqResult.Image;

            string jsonResult = lib.Stepchart.JSON(rootDir, img);

            Console.Out.Write(jsonResult);
        }
        else
        {
            throw new Exception("Could not acquire image from device.");
        }
    }

Notes

• The devices must be properly initialized by their respective control software before calling their AcquireFrom*() method.
• If the device requires settings that were saved by the Imatest IS Device Manager, then the corresponding device settings JSON file needs to included with the Imatest INI file.