Imatest IT/.NET Instructions

How Imatest IT/.NET works

Imatest IT/.NET (Industrial Testing .NET) is a Microsoft .NET Framework library that allows developers to access Imatest‘s powerful image quality analysis tools via calls to methods residing in a .NET DLL library. The library methods perform the same calculations as the corresponding GUI-based Imatest Master modules.  Imatest IT/.NET is compatible with .NET Framework versions 4.5 and higher.  Fourteen modules are available: SFR   SFRplus   Star Colorcheck   Stepchart   Wedge Uniformity (Light Falloff)   Distortion   eSFR ISO Blemish   Dot Pattern   Multitest OIS   Random     Imatest IT/.NET is a complete package that includes the module libraries, support documentation including detailed method definitions, and sample code that interfaces with each of the modules. Although Imatest IT/.NET operates independently of Imatest Master, we strongly recommend that IT/.NET users have at least one Master installation on site. When Imatest IT/.NET is installed and referenced into a .NET project, you can call methods in the library to perform Imatest image quality analyses. Currently, Imatest IT/.NET requires separate image files and returns limited results directly, as well as writing out CSV and XML files, and images. The library DLL interface allows for the passing of raw image data into Imatest routines for analysis.

Referencing Imatest IT/.NET

The Imatest.IT wrapper DLL and Library Class

Imatest IT/.NET consists of a compiled DLL (Imatest.IT.dll) containing a single wrapper class (Library) which is instantiated once per session and used to call each of the Imatest modules. Module methods are of the form lib.<module>.JSON() and lib.<module>.JSONXML(), depending on the desired outputs (note: not all modules support xml pass/fail output). The included Imatest modules are:

Referencing the Imatest.IT DLL (Windows Visual Studio 2012 C# Example):

After installing the main Imatest IT application, you can then reference the Imatest.IT DLL in your projects.  The DLL can be found here (assuming the default installation location):

Setting up IT/.NET and using Imatest Master to configure the imatest.ini file

Before running any Imatest IT modules, you must first configure the settings used by Imatest for analyzing images (though you may still use the included example .INI files located in the samples directory).

For information on specifying your own control parameters to Imatest Libraries, see the sections below.

To setup your testing environment using Imatest Master:

Set up the test system (lights, camera, etc.) and photograph a test chart lighted and framed as it would be in the actual tests.

Save the image in a standard file format. It should have the same pixel count as the actual test images.

Analyze the image using (GUI-based) Imatest Master.

When the settings are correct — when the ROI (region of interest), the calculation details, and the output files and folder locations are what you need for production — press Save settings... (or Settings, Save Settings...) in the Imatest main window. This allows you to save the control information for Imatest IT/.NET in a named .INI file, which can be viewed and edited with any standard text editor. Be sure to save it in a convenient, accessible folder. The contents of .ini files are largely self-explanatory. Here is a sample:

[sfr]
nht_save = 2052
nroi = 2
nwid_save = 3076
roi_mult = 1606 931 1735 1149;334 1693 466 1912
aper =
CA = Min
camera =
cyclesper = Max
cyclesper_value = 1
foclth =
gamma = 0.5

The INI file is divided into sections that start with a bracketed name. [sfr], [colorcheck], [distortion], [uniformity] are examples of the sections used by individual Imatest IT modules. Of the remaining sections, only [api] (described below) affects IT/.NET operation.

INI file: more detail

The settings described below are listed in the Imatest INI Reference.

General settings Press Settings, IT & Pass/Fail Settings in the Imatest Master main window to open a dialog box that sets options that only affect IT programs — they do not affect regular Imatest operation. These options are written into the [api] section of imatest.ini. See the [api] section of the INI File reference.

Imatest IT (Industrial Testing) settings

Checking Suppress all figures (for all IT modules) makes sure no figure are ever displayed, no matter what the other settings indicate.

Checking Suppress wait bars and progress bars (doesn't affect interactive runs) disables these graphic displays.

Checking Always close figures after save makes sure all figures are closed at the end of the run, no matter what the other settings indicate.

These settings affect the contents of the following lines in the INI file.

These lines can be edited using any text editor or the INI File Editor; the IT Options box is merely a convenience. Certain other options in the [imatest] section may be of interest to IT users.

Figures The INI control determines which figures are generated and saved. Any figures that aren't needed should be turned off for speed. Most are set to either Min (figure off) or Max (figure on), but some (noted in the table below), are set to 0 (figure off) or a number >= 1 (figure on, depending on conditions). These parameters can be set using a text editor, but it's usually more convenient to uncheck the appropriate boxes in the Imatest Master input dialog box prior to saving the INI file.

The rightmost column in the above table is the index of array save_file_list, which is included in each module's section ([sfr], [sfrplus], [q13], [colorcheck], [distortion], [uniformity], [blemish], and [dot]). This index indicates which output figures and files to save. It is generated by the Save dialog box (shown on the right for SFR; Note that the order of the indices may differ from the figure.) For example,

[sfr] ...
save_file_list = 1 0 0 0 0 1 0 0

directs the SFR module to save the MTF plot in cycles/(pixel or distance) and the CSV output file that contains detailed results.

Another important variable that appears in the sections for the five modules is closefigs. If closefigs = 1, figures will be deleted after being saved.

Some specific settings

[sfr]

roi_mult contains the coordinates of the region(s) of interest, four entries per region: Left, Top, Right, Bottom (L T R B, with the number of regions specified by nroi). Units are in pixels from the top-left of the image. Note that this is different from the order displayed on the SFR Edge/MTF figure: L R T B.

Imatest.IT Library module methods

Wrapper methods and return values

Imatest IT/.NET modules are initiated by calling their wrapper methods from an instance of the Imatest.IT.Library class (see "Instantiating the Library object" below). Each module's method has an identical signature (with the exception of OIS), and many have both a "<module>.JSON()" and "<module>.JSONXML()" version.

<module>.JSON(): Will return a string containing the important results of the run from the CSV files in JSON format. Strongly recommended when a single file is analyzed. (Though use caution when multiple files are analyzed; only results from the last file will be returned.) The resulting JSON string is easily parsed into a JSON object by third-party JSON libraries (such as JSON.NET), or by using the System.Json namespace in .NET Framework 4.5 or higher. [JSONlab license notice]

<module>.JSONXML(): Will return an instance of the ImatestResult object, where the JSON property contains the JSON result mentioned above, and the XML property is a string in XML format containing the Pass/Fail results. The same caveat applies about single vs. multiple file runs. The resulting XML string is easily parsed into an XML object using classes in the System.Xml.Linq namespace (see the example projects), or other XML libraries.

Instantiating and using the Library object

All calls to Imatest modules are made using an instance of the Library class. If possible, this class should be instantiated only once per session and shared between processes, to reduce the overhead of initializing the Matlab libraries.  The Library class implements the IDisposable interface - we recommend encapsulating the variable within a using block. It is crucial that the Dispose() method is called once you are finished using the library. The life-cycle of an Library object is simple and outlined in the sample C# code below:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;

using Imatest.IT;

namespace Imatest.IT.Example
{
    class Program
    {
        static void Main(string[] args)
        {
            try
            {
                // Instantiate the Imatest Library - This may take a few seconds while the Matlab MCR is initialized 
                using (Library lib = new Library())
                {
                    // Make calls to Imatest modules here using the lib object
                }
            }
            catch (Exception ex)
            {
                // Handle exception
            }
        }
    }
}

Wrapper method parameters

The module JSON() and JSONXML() methods are overloaded with different parameter signatures to fit different situations and inputs.  The parameters for the various methods are listed below:

Setting Up DirectReadOptions

When using the "direct read" methods (those that accept byte[], UInt16[], or UInt32[] inputs), in addition to the inputBytes parameter, you must also include an instance of the Imatest.IT.DirectReadOptions class containing details about Imatest should interpret the raw image data.

The DirectReadOption class is a simple class containing getter and setter properties for the various raw data attributes. See the example below for usage:

/*
 * RAW FILE INPUT SETTINGS 
 * Width 
 * Height
 * Number of Colors
 * File Extension (see below)
 * Test Filename (optional)
 * Serial Number
 * Part Number
 * Crop Borders - Pixels to cut off { L, R, T, B }
 * Ensure that the File Extension matches the RAW extensions configured in Imatest
 * In Imatest Master, Under the Utility menu select "Read Raw"
 * In the Imatest INI, this relates to the [rdraw] section, raw conversion settings should be set here
 * See: https://www.imatest.com/docs/raw/#readraw for more on raw settings
 */
DirectReadOptions directReadOptions = new DirectReadOptions();
directReadOptions.Width = 1296;
directReadOptions.Height = 808;
directReadOptions.Extension = "raw";
directReadOptions.Filename = "blemish.raw";
directReadOptions.PartNumber = "720Pcam";
directReadOptions.SerialNumber = "CAMX40500-46589-78854";
directReadOptions.CropBorders = new int[] { 0, 0, 0, 0 };

Returning results with JSON

JSON objects are a convenient and easy-to-implement means of passing Imatest IT/.NET results back to the calling program. In most programming languages (what, no FORTRAN?) a single call is available to convert a JSON object to a data structure or vice-versa. Here is a portion of the JSON object returned by sfr (with skipped or shortened lines indicated by ... ). For the most part, names in the object (and hence in the corresponding data structure) are self-explanatory. JSON output files are being added to Imatest Master modules (in addition to CSV and XML). [JSONlab license notice]

{
  “sfrResults”: {
  “dateRun”: “26-Dec-2011 16:34:18”,
  “roi_mult”: [
    [1706,1327,1898,1605],
    [3685,374,3978,542] 
  ],
  “mtfPeak”: [1.316749102,1.125382339],
  “mtf50”: [0.4023813085,0.3236112599],
  “mtf50p”: [0.3663296738,0.3100313299],
  …,
  “mtf10”: [0.5373973791,0.4691161373],
  “mtf10p”: [0.5228006564,0.4591916907],
  “edgeRoughSTD”: [
    [0.09443263439,0.1002447785],
    [0.0423559873,0.04494066213],
    [0.06807294473,0.1000587208],
    [0.04869192922,0.05593847561]
  ],
  “CA_crossPxls”: [0.1156214328,0.1508858711], 
  …,
  “MTFfreq”: [0,0.025,0.05,0.075,0.1,0.125,0.15,0.175,0.2,0.225,0.25,0.275,0.3,0.325, …],
  “MTFinterp1”: [1,0.9557716778,0.9434756776,0.9619840588,1.017016935,1.040196171, …],
  …,
  “MTFinterp4”: [1,0.9621111279,0.969935489,1.007033219,1.069689419,1.107938549, …]
  }
}

roi_mult is the [Left,Top,Right,Bottom] pixel locations of the Regions of Interest (ROIs). MTFfreq are frequencies in cycles/pixel of interpolated MTF results. MTFinterp1 and MTFinterp4 are the interpolated MTFs of the Red and Luminance (Y) channels, respectively (with 2 for Green and 3 for Blue skipped).

Please contact us if you would like additional results added.

Using the Imatest IT/.NET Acquisition Library

Beginning in Imatest IT 4.5, you can now use the Imatest IT/.NET Acquisition Library to load images directly from supported devices and pass them in to Imatest IT/.NET processing modules.  For more information, see the instructions here.

Passing images directly

Images (processed RGB or RAW) can be passed directly from the calling program to the IT/.NET methods using the method versions that contain byte[], UInt16[], or UInt32[] parameters. Passing images directly is generally much faster than reading them from files, and strongly recommended for speed-critical high-volume testing.

For direct image passing, inputBytes contains the image (passed as a binary stream, 8 or 16 bits per pixel), and directReadOptions is a DirectReadOptions object with information needed to decode (or reconstruct) the image.

Processed (RGB or monochrome) Images

For RGB images, the DirectReadOptions object must contain the image width, height, number of colors, and extension indicator ('rgb1' below), as shown in the following Matlab test case, which reads an image (to test IT/.NET), prepares it to be passed as a binary data stream (reshape), then calls

im_orig = imread(rdfname); % Read a processed RGB image. For test example-only.
disp(['Read ' num2str(numel(im_orig)) ' byte image.']);
sz_orig = size(im_orig);
jstr.height = sz_orig(1); % Number of rows (image height in pixels).
jstr.width = sz_orig(2); % Number of columns (image width).
if length(sz_orig)>=3 jstr.ncolors = sz_orig(3); % Number of colors for this file.
else jstr.ncolors = 1;
end
jstr.extension = 'rgb1'; % MUST be RGBn or correspond to Read Raw extension!
jstr.fileroot = rdfname; % Root file name for saving CSV, JSON, etc. output files
jsonObj = savejson('',jstr,[]); % Convert structure into JSON object.
im_orig = reshape(im_orig,1,numel(im_orig)); % Reshape to one-dimension.
disp(char({'';'DIRECT READ: SINGLE PROCESSED IMAGE, NO PLOTS'}));
iniFile = 'C:\Imatest\matlab\trunk\API\it_samples\stepchartcontrol_file.ini';
output = stepchart_shell('', 'C:\Imatest\matlab\trunk\API\it_samples\stepchart', ...
'JSON', '-17', iniFile,im_orig,jsonObj); % Output contains results in a JSON object.

Notes

• File extension indicator indicator 'rgb1' indicates a standard RGB or monochrome image in the default Matlab order. We will add additional types upon user request.

Raw images

Raw images with properties described in Generalized Read Raw can be passed directly to Imatest modules. Note that this does not refer to commercial raw files (NEF, CR2, etc.), which contain metadata and are typically packed (to minimize file size — pixels often straddle bytes). To pass raw files directly you need to set up parameters for interpreting (decoding) them using Generalized Read Raw.

• Save the raw image as a simple binary stream, one or two bytes per pixel (as required). Give the saved file a unique extension (up to 4 characters), which should not be a recognized image file extension (JPG, TIF, PNG, GIF, PPM, etc. — see the Mathworks imread documentation) or a commercial raw image file extension recognized by dcraw (NEF, CR2, etc.— many are listed in the rawphoto.c GIMP plugin). 'raw' is acceptable, but something less generic is recommended.
  In Matlab you would save the image with a statements of the form,
  fileID = fopen('filename.raw3','w');
  fwrite(fileID, imageArray, precision),
  where precision might be 'uint8' or 'uint16'.
• Following instructions in Generalized Read Raw, set up decoding parameters for this extension. Test them by pressing Convert / Test, then opening the saved raw image file. A few iterations may be required to get the settings right. They are saved in the [rdraw] section of imatest.ini (in the standard location for saved settings), which should be copied to a named file location (inifile in the example below) by clicking Settings, Save settings...

Here is a Matlab test case, showing the key settings for reading a raw image.

jstr.extension = 'raw3'; % MUST correspond to Read Raw extension!
jstr.fileroot = rdfname; % Read a raw image. For test example-only.
jsonObj = savejson('',jstr,[]); % Convert structure into JSON object.
endian_str = 'ieee-be'; precision = 'uint16=>uint16';
fd = fopen('filename.raw3', 'r', endian_str) ; % Open the image test file for reading.
[ im_orig count ] = fread(fd, inf, precision) ; % Test file.
output = stepchart_shell('', 'C:\Imatest\matlab\trunk\API\it_samples\stepchart', ...
'JSON', '-17', inifile, im_orig, jsonObj); % Output contains results in a JSON object.

Here is a simple example demonstrating how to pass an image directly after reading a file:

public const string EXAMPLE_IMAGE = "blemish.raw"; 
static void Main(string[] args) 
{ 
    try
    {
        using (Library lib = new Library()) 
        { 
            DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory()); 
            string rootDir = currentDirectory.Parent.Parent.Parent.FullName; 
            string imagePath = Path.Combine(rootDir, EXAMPLE_IMAGE); 
            byte[] imageBytes = File.ReadAllBytes(imagePath); 
            DirectReadOptions directReadOptions = new DirectReadOptions(); 
            directReadOptions.Width = 1296; 
            directReadOptions.Height = 808; 
            directReadOptions.Extension = "raw"; 
            directReadOptions.Filename = "blemish.raw"; 
            directReadOptions.PartNumber = "720Pcam"; 
            directReadOptions.SerialNumber = "CAMX40500-46589-78854"; 
            directReadOptions.CropBorders = new int[] { 0, 0, 0, 0 }; 

            string result = lib.Blemish.JSON(rootDir, imageBytes, directReadOptions); 
            Console.Out.WriteLine(result); 
        } 
    } 
    catch (Exception ex) 
    { 
        Console.Out.WriteLine("An error has occurred:"); 
        Console.Out.WriteLine(ex.Message); 
    } 
}

Asynchronous Programming with Imatest IT/.NET

Beginning in Imatest IT 4.5, you can now easily use Imatest IT/.NET asynchronously in your custom applications using the .NET Framework's async and await keywords along with Imatest IT/.NET's new JSONAsync() and JSONXMLAsync() methods.

Making these simple changes can have dramatic effect on the responsiveness of applications, especially if they are GUI-based. To see the difference in action, run the Imatest IT .NET Sample Application found at C:\Program Files\Imatest\v4.5\IT\samples\.NET\ImatestITSampleProject\ImatestITSampleProject.exe and try both the "Run" and "Run Async" buttons. You will notice the application appears to freeze when using the non-async version, but is fully responsive when using the async methods.

Altering Existing Imatest IT/.NET Code to be Asynchronous

There are only three changes that need to be made to convert single-threaded code into asynchronous code using Imatest IT/.NET:

• Add an async modifier to the signature in which the asynchronous code will be called.
• Add the await in front of the Imatest IT/.NET method call.
• Change the Imatest IT/.NET method call to use the new Async version.

Below is a code snippet of synchronous code making a simple call to an Imatest IT/.NET method:

protected void TestImage()
{
    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());
        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;
        string imagePath = @"C:\Program Files\Imatest\v4.5\IT\samples\images\sfrplus_example.jpg";

        // Call Imatest IT library with JSON output
        string result = lib.SFRplus.JSON(rootDir, imagePath, OperationMode.Separate);

        Console.Out.WriteLine(result);
    }
}

Below is the same code that has been converted to call the Imatest IT/.NET SFRplus module asynchronously:

protected async void TestImage()
{
    using (Library lib = new Library())
    {
        DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());
        string rootDir = currentDirectory.Parent.Parent.Parent.FullName;
        string imagePath = @"C:\Program Files\Imatest\v4.5\IT\samples\images\sfrplus_example.jpg";

        // Call Imatest IT library with JSON output
        string result = await lib.SFRplus.JSONAsync(rootDir, imagePath, OperationMode.Separate);

        // Continue other operations that do not rely on the result value of the test
        
        Console.Out.WriteLine(result);
    }
}

Initializing the Imatest IT/.NET Libraries Asynchronously

The Imatest IT/.NET and Imatest IT/.NET Acquisition Library wrapper classes now ship with static CreateAsync() methods that can be called using the await keyword:

public async void InitializeApplication()
{
    /// Inside application initialization code
    
    /// The await keyword will automatically start a new thread to initialize the library, 
    /// while code in the main thread continues to execute until the itLib object is 
    /// actually used.
    Library itLib = await Library.CreateAsync();
    
    /// Continue initializing the rest of the application while the background thread
    /// initializes the rest of the application
    
    ...
    
    /// The main thread will wait here until the secondary thread is completed and the 
    /// Library.CreateAsync() method has returned a Library object.
    itLib.SFRplus.JSON(rootDir, inputFile, OperationMode.Separate); 
    
    /// At this point only the main thread is running
}

Examples

Imatest IT/.NET Example Projects

The easiest way to see Imatest IT/.NET in action is to look at the example projects located here:

Each module has its own directory containing a sample C# project calling the Imatest library in one or more different scenarios, demonstrating the various ways the module methods can be called.

Note: Because the example programs will write result files, you may need to change the permissions of the directories within the samples directory, or copy them to another location with proper permissions first.

To run an example program, be sure that you have followed the setup requirements above, including activation.

Error handling

Imatest IT/.NET methods will throw exceptions if they encounter an error. It is best practice to trap these errors inside a try/catch block. Your application can catch the exceptions and query them to get the error message.

For information about the exception hierarchy that is new in Imatest IT 4.2, please read Imatest IT Exception hierarchy.

If an error is detected, a message is

• appended to the error log file, which has the name of the form module.log (sfr.log, colorcheck.log, stepchart.log, distortion.log, uniformity.log, ...), and is located in %APPDATA%\Imatest.
• written to the CSV and/or XML file that would otherwise contain the results of the run. For the example above,
  if a CSV output file were called for, it would be C:\Program Files\Imatest\v4.5\IT\Results\Stepchart_DR_Canon_G2_summary.csv ;
  if an XML output file were called for, it would be C:\Program Files\Imatest\v4.5\IT\Results\Stepchart_DR_Canon_G2.xml .

APPDATA is a DOS environment variable whose value can be found by opening a DOS (CMD) window (you can double-click start-dos.bat in the Imatest folder), and typing

set APPDATA (Returns the folder name corresponding to APPDATA)
--or--
dir "%APPDATA%\Imatest"

APPDATA has values of the form

• C:\Users\your name\AppData\Roaming in Windows Vista/7.
• C:\Documents and Settings\your name\Application Data in Windows XP.

Lines in the log file have the format,

[Date Time], file_name, error_message

Example:

[05-May-2007 23:34:08], c:\Imatest\data_distortion\distgrid101.jpg, Inconsistent Vert lines 17 det.; 18 avg. Incomplete line?

We are constantly working to improve the robustness of Imatest algorithms to minimize the occurrences of errors, which are typically caused by poor region (ROI) selections or poor quality images.

Troubleshooting

Below is a list of some common error messages, and their solutions

Error Message: not registered – Run the License Manager to activate your license or trial
Solution: Your copy of Imatest IT is not activated. Follow the activation instructions here, then try again.

Error Message: An unhandled exception of type 'System.BadImageFormatException' occurred in mscorlib.dll  Additional information: Could not load file or assembly 'Imatest.IT, Version=1.0.0.0, Culture=neutral, PublicKeyToken=null' or one of its dependencies. An attempt was made to load a program with an incorrect format.
Solution: This is caused by trying to run a 64-bit Imatest IT installation using a an x86 configuration in Visual Studio. Be sure the configuration is set correctly for the version of Imatest you have installed.  Note, because Matlab DLLs are compiled for a specific architecture, the "Any CPU" option may not work properly. It is best to use the configuration specific to your Imatest version ("x64" for 64-bit and "x86" for 32-bit).

Error Message: Exception: Could not find .ini file at "C:\Program Files\Imatest\v4.5\IT\samples\.NET\C#\Blemish\..\ini_file\imatest-v2.ini".
Solution: Imatest IT could not find the specified INI file. Be sure the file exists, the path is correct, and the permissions are valid.