Imatest IT Instructions

In order for your application to interface with the Imatest IT C or C++ DLLs, your system needs to know where to find them.

There are two ways to make the Imatest IT C or C++ DLLs available to the system:

• Add the library’s directory to your system’s PATH or LD_LIBRARY_PATH variable (recommended).
• Copy the DLLs to the same directory as your application.

Adding to the PATH or LD_LIBRARY_PATH variable

Add the following directory to your system’s PATH (Windows) or LD_LIBRARY_PATH (Linux) variable, depending on which interface you will be using. For instructions on how to do this, see Editing System Environment Variables.

Note: Linux users may already have completed this step by following the Additional Installation Steps above, if you are using the C++ library.

Copying the Imatest IT DLLs

If you prefer not to change your PATH or LD_LIBRARY_PATH variables, you can also reference the Imatest IT DLLs by copying them to the same directory as your project’s executable.

Visual Studio users can automate this process by adding a Post-Build Event.

• In the Solution Explorer, right-click on the project and select Properties.
• Under Configuration Properties and Build Events, choose Post-Build Event.
• Add the following to the Command Line box:

  [shell]
  copy /Y "C:\Program Files\Imatest\v5.2\IT\libs\library\c\imatest_library.dll" ";$(TargetDir)"
  [/shell]

  [shell]
  copy /Y "C:\Program Files\Imatest\v5.2\IT\libs\library\cpp\imatest_library.dll" "$(TargetDir)"
  [/shell]

• Repeat these steps for each configuration in your project.

Now, the imatest_library.dll file will be copied to your project’s target directory automatically and will be able to be loaded by your application.

The Imatest IT Python Interface is shipped as a Python module. Before referencing it in your scripts, you will need to install it using Python’s package manager. This must be done on the command line, and requires Administrator access. If you don’t know how to open a Command Prompt with Administrator privileges in Windows, see this helpful article.

Note: Imatest IT only supports Python versions 2.7, 3.5, 3.6 and 3.7. 

First, navigate to the Imatest IT Python library directory.

Windows

[shell]
cd C:\Program Files\Imatest\v5.2\IT\libs\library\python\
[/shell]

Linux

[shell]
cd /usr/local/Imatest/v5.2/IT/libs/library/python
[/shell]

Next, run the following command to install the Imatest IT Python module:

Windows (assuming you are running Python 2.7 installed in C:\Python27\)

[shell]
C:\Python27\python.exe setup.py install
[/shell]

Linux

[shell]
sudo python setup.py install
[/shell]

You will now be able to reference Imatest IT in your Python scripts using the import statement.

There are no more additional installation steps required to use the Imatest IT .NET libraries.

To simplify calling the Imatest IT EXE programs from the command line or a script file, the Imatest IT bin directory should be part of your PATH environment variable.

Windows In Windows, this is done automatically during installation, but if you are getting errors like “sfr.exe is not recognized as an internal or external command, operable program or batch file” when trying to run the EXE programs, you may need to manually add the bin directory to your PATH environment variable.

Follow these instructions and add C:\Program Files\Imatest\v5.2\IT\bin to the system PATH variable. You will need to open a new command window for the change to take effect.

Linux On Linux systems, you will need to manually add $PATH:/usr/local/Imatest/v5.2/IT/bin to the PATH variable. See these instructions.

Windows (Visual Studio) Project Setup

First, you need to configure your project to be able to find the Imatest IT and Matlab MCR libraries. To do this, right click on the project and choose Properties. Add the following include directories in the sections under Configuration Properties:

Note: Imatest 5.2 and newer only supports 64-bit architectures. You must use the x64 platform configuration when using Imatest IT in your projects. You may need to manually add this platform configuration to your project first. For information on how to do this, see this article.

Initializing the Imatest IT Library

Now that your project references are set up, the next step is to include the imatest_library.h header file. Add this line to the top of your source file:

[cpp]
#include "imatest_library.h"
[/cpp]

Next, initialize the Matlab MCR application state by calling mclInitializeApplication(const char **options, int count). Most users can ignore the options and count parameters; just pass in NULL and 0, respectively. The function will return 0 if successful, allowing you to trap errors and handle them gracefully. This should only be called once during the life of your application.

[cpp]
#include "imatest_library.h"

int main()
{
if (!mclInitializeApplication(NULL,0))
{
printf("Error: could not initialize application properly.\n");
return -1001;
}

/// …
}
[/cpp]

The last initialization step is to call imatest_libraryInitialize(). This will prepare the Imatest IT library for use. The function also returns 0 if it is successful.

[cpp]
#include "imatest_library.h"

int main()
{
if (!mclInitializeApplication(NULL,0))
{
printf("Error: could not initialize the Matlab MCR properly.\n");
return -1001;
}

if(!imatest_libraryInitialize())
{
printf("Error: could not initialize the Imatest IT library properly.\n");
return -1002;
}

/// …
}
[/cpp]

Calling the Imatest IT C Library Interface

Now that the Matlab MCR and Imatest IT library are all ready to go, the next step is the prepare the arguments that will be passed into the IT module functions. Each of the IT modules has the same method signature (with the exception of OIS). In this example, we will use the sfr function. The signature for the SFR module function looks like this:

[cpp]
bool mlfSfr_shell(int nargout, mxArray** nret, mxArray* inputFile, mxArray* rootDir, mxArray* inputKeys, mxArray* opMode, mxArray* varargin);
[/cpp]

The Imatest IT C library encapsulates all input and output arguments inside mxArray types. This is a generic pointer type that can represent any data type. See below for more information on using mxArrays.

The Imatest IT C library parameters are listed here:

Working with mxArrays

The Imatest IT C library receives and returns data via mxArray pointers. The Matlab MCR provides helper methods for allocating, interacting with, and deallocating mxArray structures.

Most of the Imatest IT C library input parameters (with the exception of varargin and raw image data passed in when using direct read mode) are strings (const char*) wrapped as mxArrays. You can create these mxArray pointers by using the mxCreateString(const char *str) function.

Before your program terminates, you must deallocate all of your mxArray pointers using the mxDestroyArray(mxArray *pm) function, and then set the pointers to NULL.

Here is an example of the typical lifecycle of an mxArray string parameter:

[cpp]
// Declare the pointer variable
mxArray *inputFile = NULL;

// Initialize the mxArray with a string
inputFile = mxCreateString("C:\\Program Files\\Imatest\\v5.2\\IT\\samples\\images\\sfr_example.jpg");

// Make calls to Imatest IT library

// …

// Destroy the mxArray
mxDestroyArray(inputFile);
inputFile = NULL;
[/cpp]

The varargin parameter is a Matlab Cell Array containing zero or more additional input parameters, depending on the op mode. To initialize this parameter, use the mxCreateCellMatrix(int rows, int columns) function. You should create the varargin cell array with the exact number of cells required for your op mode. The rows parameter should always be 1, and the columns parameter should be the number of parameters you will be supplying.

You can then set the individual cells using mxSetCell(mxArray *array, int index, mxArray *value), where array is the varargin pointer, index is a zero-based index, and value is an mxArray pointer to the value being added to the array.

The varargin parameter is deallocated in the same way as other mxArrays, and you should not deallocate the individual cells of the array.

[cpp]
mxArray *varargin = NULL, *iniFile = NULL, *inputFile2 = NULL;

iniFile = mxCreateString("C:\\Program Files\\Imatest\\v5.2\\IT\\samples\\cpp\\Imatest_INI\\imatest-v2.ini");
inputFile2 = mxCreateString("C:\\Program Files\\Imatest\\v5.2\\IT\\samples\\images\\sfr_example.jpg");

varargin = mxCreateCellMatrix(1, 2);

mxSetCell(varargin, 0, iniFile);
mxSetCell(varargin, 1, inputFile2);

// …

mxDestroyArray(varargin);
[/cpp]

Calling Imatest IT Modules

Now that the library is initialized, and all of the input parameters are set up, it is time to call the Imatest IT analysis function. This example uses the SFR module, but the same code can be used to call the rest of the Imatest modules (with the exception of OIS, which has different inputs).

The first parameter will always be 1, and the second is a reference to an mxArray* pointer that will contain the JSON output of the analysis. If the function returns false, it means an error has occurred. Check the stdout and stderr streams for details on what went wrong, and see the section Error Handling below for information on handling errors gracefully.

When the call is successful, the JSON output will reside inside the outputJSON pointer. You can extract the string using the mxArrayToString(const mxArray *array_ptr) function.

[cpp]
if (!mlfSfr_shell(1, &outputJSON, inputFile, rootDir, inputKeys, opMode, varargin))
{
printf("*** Error calling SFR. Check output messages for details. ***\n");
}
else
{
jsonOutput = mxArrayToString(outputJSON);
printf(jsonOutput);
}
[/cpp]

When you are finished making calls to the Imatest IT C library, you then need to make three more function calls to terminate the library and the Matlab MCR.

[cpp]
mlfIt_terminate();
imatest_libraryTerminate();
mclTerminateApplication();
[/cpp]

Windows (Visual Studio) Project Setup

First, you need to configure your project to be able to find the Imatest IT and Matlab MCR libraries. To do this, right click on the project and choose Properties. Add the following include directories in the sections under Configuration Properties:

Note: Imatest 5.2 and newer only supports 64-bit architectures. You must use the x64 platform configuration when using Imatest IT in your projects. You may need to manually add this platform configuration to your project first. For information on how to do this, see this article.

Initializing the Imatest IT Library

Now that your project references are set up, the next step is to include the imatest_library.h header file. Add this line to the top of your source file:

[cpp]
#include "imatest_library.h"
[/cpp]

Next, initialize the Matlab MCR application state by calling mclInitializeApplication(const char **options, int count). Most users can ignore the options and count parameters; just pass in NULL and 0, respectively. The function will return 0 if successful, allowing you to trap errors and handle them gracefully.

[cpp]
#include "imatest_library.h"

int main()
{
if (!mclInitializeApplication(NULL,0))
{
std::cerr << "Error: could not initialize the Matlab MCR properly." << std::endl;
return -1001;
}

/// …
}
[/cpp]

The last initialization step is to call imatest_libraryInitialize(). This will prepare the Imatest IT library for use. The function also returns 0 if it is successful.

[cpp]
#include "imatest_library.h’

int main()
{
if (!mclInitializeApplication(NULL,0))
{
std::cerr << "Error: could not initialize the Matlab MCR properly." << std::endl;
return -1001;
}

if(!imatest_libraryInitialize())
{
std::cerr << "Error: could not initialize the Imatest IT library properly." << std::endl;
return -1002;
}

/// …
}
[/cpp]

Calling the Imatest IT C++ Library Interface

Now that the Matlab MCR and Imatest IT library are all ready to go, the next step is the prepare the arguments that will be passed into the IT module functions. Each of the IT modules has the same method signature (with the exception of OIS). In this example, we will use the sfr function. The signature for the SFR module function looks like this:

[cpp]
void sfr_shell(int nargout, mwArray& nret, const mwArray& inputFile, const mwArray& rootDir, const mwArray& inputKeys, const mwArray& opMode, const mwArray& varargin);
[/cpp]

The Imatest IT C++ library encapsulates all input and output arguments inside mwArray objects. This is a generic wrapper class that can represent any data type. See below for more information on using mwArrays.

The Imatest IT C++ library parameters are listed here:

Working with mwArrays

The Imatest IT C++ library receives and returns data via mwArray objects. Unlike the C library, the C++ library’s mwArray class is object-oriented, and also takes care of allocating and deallocating automatically. There is no need to manually destroy the mwArray objects.

Most of the Imatest IT C++ library input parameters (with the exception of varargin and raw image data passed in when using direct read mode) are strings (const char*) wrapped as mwArray objects. You can create these mwArray pointers by passing a const char* into the constructor.

[cpp]
mwArray opMode("-5");
[/cpp]

The varargin parameter is a Matlab Cell Array containing zero or more additional input parameters, depending on the opMode. To initialize this parameter, use the mwArray(int num_rows, int num_cols, mxClassID mxID) constructor, passing 1 for num_rows, the number of extra arguments required as num_cols, and the constant mxCELL_CLASS as mxID. The num_cols value should be the exact number of cells required for your op mode. See this article for more information on populating the varargin parameter.

You can then set the individual cells using the mwArray object’s Get(int row, int column) and Set(const mwArray& arr) methods. Note that the row and column parameters are 1-based indexes.

[cpp]
/// Set the first cell of varargin to be the iniFilePath
varargin.Get(1,1).Set(iniFilePath);
[/cpp]

Calling Imatest IT Modules

Now that the library is initialized, and all of the input parameters are set up, it is time to call the Imatest IT analysis function. This example uses the SFR module, but the same code can be used to call the rest of the Imatest modules (with the exception of OIS, which has different inputs).

The first parameter will always be 1, and the second is a reference to an uninitialized mwArray variable that will contain the JSON output of the analysis. If the function throw an exception, it means an error has occurred. Check the exception messages and stdout and stderr streams for details on what went wrong. See the section on Error Handling below for more information on catching and handling exceptions gracefully.

When the call is successful, the JSON output will reside inside the outputJSON pointer. You can extract the string by calling the mwArray.ToString() method, then converting that result to a const char*. Note that you must declare the mwString variable separately for this to work.

[cpp]
sfr_shell(1, outputJSON, inputFile, rootDir, inputKeys, opMode, varargin)
mwString mwStr = outputJSON.ToString();
const char* strOutputJSON = (const char*)mwStr;

std::cout << strOutputJSON << std::endl;
[/cpp]

When you are finished making calls to the Imatest IT C++ library, you then need to make three more function calls to terminate the library and the Matlab Runtime.

[cpp]
it_terminate();
imatest_libraryTerminate();
mclTerminateApplication();
[/cpp]

Note: Imatest 5.2 and newer only supports 64-bit architectures. You must use the 64-bit version of Python when using Imatest IT.

Calling the Imatest IT Python Interface

At the top of your script file, include this line to import the ImatestLibrary class from the imatest.it module:

[python]
from imatest.it import ImatestLibrary
[/python]

Next, create an instance of the ImatestLibrary class. Behind the scenes, the ImatestLibrary constructor will start up the Matlab MCR Runtime and load all the IT libraries into memory. This will take a few seconds the first time you run it, but should be faster on subsequent runs, especially if you have set your system’s environment variables to the recommended values as described above.

[python]
from imatest.it import ImatestLibrary

imatestLib = ImatestLibrary()
[/python]

Now that the Matlab MCR and Imatest IT library are all ready to go, the next step is the prepare the arguments that will be passed into the IT module functions. Each of the IT modules has the same method signature (with the exception of OIS). In this example, we will use the sfr function. The signature for the SFR module function looks like this:

[python]
sfr(input_file=None, root_dir=None, op_mode=None, ini_file=None, raw_data=None, json_args=None)
[/python]

The Imatest IT Python library parameters are listed here:

Calling Imatest IT Modules

Now that the library is initialized, and all of the input parameters are set up, it is time to call the Imatest IT analysis function. This example uses the SFR module, but the same code can be used to call the rest of the Imatest modules (with the exception of OIS, which has different inputs).

It’s easiest to call the sfr using named parameters, as shown below. An exception will be thrown if something goes wrong – you should catch it and handle it gracefully. Check the exception message and stdout and stderr streams for details on what went wrong, and see the Error Handling section below for more information on gracefully handling exceptions.

When the call is successful, the function will return a string containing JSON-encoded output.

[python]
from imatest.it import ImatestLibrary
import json

imatestLib = ImatestLibrary()

result = imatestLib.sfr(input_file=input_file,
root_dir=root_dir,
op_mode=ImatestLibrary.OP_MODE_SEPARATE,
ini_file=ini_file)
print(result)
[/python]

When you are finished making calls to the Imatest IT Python library, you then need to call terminate_library() to unload the library and the Matlab Runtime.

[python]
imatestLib.terminate_library();
[/python]

Windows (Visual Studio) Project Setup

To use the Imatest IT .NET libraries in your Visual Studio project, first you need to add a reference to the library DLL in your project.

Once your project is created in Visual Studio, right click on the References section of the Solution Explorer and choose Add Reference….

In the Reference Manager window, choose Browse on the left-hand side, then click the Browse… button at the bottom.

Navigate to the .NET library directory of your Imatest IT installation (by default, C:\Program Files\Imatest\v5.2\IT\libs\library\.NET\), choose Imatest.IT.dll, and click the Add button.

Note: You do not need to add the IT.dll reference to your project.

Click OK to close the Reference Manager window.

Note: Imatest 5.2 and newer only supports 64-bit architectures. You must use the x64 platform when running .NET applications. The Any CPU platform will throw runtime errors.

Calling the Imatest IT .NET Interface

Next, create an instance of the Imatest.IT.Library class. Behind the scenes, the Imatest.IT.Library constructor will start up the Matlab MCR Runtime and load all the IT libraries into memory. This will take a few seconds the first time you run it, but should be faster on subsequent runs, especially if you have set your system’s environment variables to the recommended values as described above.

Now that the Matlab MCR and Imatest IT library are all ready to go, the next step is the prepare the arguments that will be passed into the IT module functions. Each of the IT modules has the same overloaded method signatures (with the exception of OIS). In this example, we will use the SFR.JSON methods. The signatures for the SFR module function looks like this:

The Imatest IT .NET library parameters are listed here:

Calling Imatest IT Modules

Now that the library is initialized, and all of the input parameters are set up, it is time to call the Imatest IT analysis function. This example uses the SFR module, but the same code can be used to call the rest of the Imatest modules (with the exception of OIS, which has different inputs).

We recommend always wrapping your Imatest IT calls in try/catch blocks. If anything goes wrong, an Exception will be thrown. You should handle these exceptions gracefully. Check the exception message for details on what went wrong, and see the section on Error Handling below for more information.

When the call is successful, the function will return a string containing JSON-encoded output.

Calling the Imatest IT EXE Interface

The Imatest IT EXE Library can be called using Windows or Linux script files. We recommend making sure that the IT bin directory is in your PATH variable. On Windows, this should already happen when Imatest IT is installed. You may need to add to your path manually on Linux. For more information on viewing and editing system environment variables, see this article.

All Imatest IT EXE executables accept the following arguments (except for OIS, which uses different inputs):

[sourcecode language="plain"]
sfr.exe op-mode input-file bin-directory ini-file [result-directory] [other-images ...]
[/sourcecode]

The Imatest IT EXE library parameters are listed here:

Calling Imatest IT Modules

Imatest IT EXE modules are called using the command line, or in .bat files.

Note: You should not include a trailing ‘\’ when passing in directory names, otherwise you may get an error (see here).

[shell]
sfr.exe "-1" "C:\ImatestSamples\sfr_example.jpg" "C:\Program Files\Imatest\v5.2\IT\bin" "C:\ImatestSamples\imatest-v2.ini" "C:\ImatestSamples\Results"
[/shell]

When the module is finished running, the result files will be written to the result-directory folder (in this case, C:\ImatestSamples\Results).

In the Imatest C library, if an error occurs within one of the analysis module functions, a false result will be returned. You can then use the mlfGetExceptionID(int nargout, mxArray** errID, mxArray** errName) function to extract an Error ID and Error Name, which map into the Imatest IT Exception Hierarchy.

To make handling these exceptions easier, Imatest IT includes an optional header file, imatest_exception_IDs.h, which maps each of the Error IDs to an enum. To include this header file, add #include “imatest_exception_ids.h” to your source file. You can read more about the Exception Hierarchy here.

Here is an example of how you can catch and gracefully handle exceptions using the Imatest IT C Library:

[cpp]
int retVal;
mxArray *errorID = NULL, *errorName = NULL;
enum ImatestExceptionIDs errorCode;
const char* errorNameStr;

…

if (!mlfSfr_shell(nargout, &outputJSON, inputFile, rootDir, inputKeys, opMode, varargin))
{
if (mlfGetExceptionID(2, &errorID, &errorName))
{
errorCode = (enum ImatestExceptionIDs)mxGetScalar(errorID);
printf("*** Error ID: %d\n", errorCode);

switch (errorCode)
{
case kImatestFileNotFoundException:
printf("File not found exception.\n");
break;
case kBadFramingException:
printf("Bad framing exception.\n");
break;
default:
errorNameStr = mxArrayToString(mxGetCell(errorName, 0));
printf("*** Unexpected Error: %s\n", errorNameStr);
break;
}

mxDestroyArray(errorID);
mxDestroyArray(errorName);
retVal = errorCode;
}
else {
printf("*** Unknown Error.\n");
retVal = -1005;
}
}
else
{
retVal = 0;
…
}
[/cpp]

In the Imatest C++ library, if an error occurs within one of the analysis module functions, an mwException will be thrown. If you catch the exception, then you can use the getExceptionID(int nargout, mwArray& errID, mwArray& errName) function to extract an Error ID and Error Name, which map into the Imatest IT Exception Hierarchy.

To make handling these exceptions easier, Imatest IT includes an optional header file, imatest_exception_IDs.h, which maps each of the Error IDs to an enum. To include this header file, add #include “imatest_exception_ids.h” to your source file. You can read more about the Exception Hierarchy here.

Here is an example of how you can catch and gracefully handle exceptions using the Imatest IT C++ Library:

[cpp]
try
{
sfr_shell(1, outputJSON, inputFile, rootDir, inputKeys, opMode, varargin)
}
catch (const mwException& e)
{
mwArray mwErrorID, mwErrorName;
mwString mwErrorNameStr;
getExceptionID(2, mwErrorID, mwErrorName);
int err = (int)mwErrorID;

switch (err)
{
case imatest::kImatestFileNotFoundException:
std::cerr << "*** File was not found. Check the file path." << std::endl;
break;
case imatest::kBadFramingException:
std::cerr << "*** Image is not framed correctly." << std::endl;
break;
default:
mwErrorNameStr = mwErrorName.Get(1,1).ToString();
std::cerr << "*** Unexpected Error: " << mwErrorNameStr << std::endl;
break;
}

retVal = err;
}
[/cpp]

In the Imatest Python library, if an error occurs within one of the analysis module functions, an ImatestException will be thrown. If you catch the exception, then you can get more information about using the error_id, error_name, and message properties.

Here is an example of how you can catch and gracefully handle exceptions using the Imatest IT Python Library. You can use the constants on the ImatestException class to handle certain error types in different ways. In this example, an ImatestException will be thrown because all floating license seats are currently being used:

[python]
from imatest.it import ImatestLibrary, ImatestException
…
try:
result = imatestLib.sfr(input_file=input_file,
root_dir=root_dir,
op_mode=ImatestLibrary.OP_MODE_SEPARATE,
ini_file=ini_file)
except ImatestException as ex:
if iex.error_id == ImatestException.FloatingLicenseException:
print("All floating license seats are in use. Exit Imatest on another computer and try again.")
elif iex.error_id == ImatestException.LicenseException:
print("License Exception: " + iex.message)
else:
print("*** Error calling sfr: %s" % (iex.message, ))
[/python]

In the Imatest .NET library, if an error occurs within one of the analysis module functions, an Exception will be thrown. If you catch the exception, then you can get more information about it by calling the ImatestLibrary.GetLastException() and ImatestLibrary.GetExceptionName() methods.

Here is an example of how you can catch and gracefully handle exceptions using the Imatest IT .NET Library:

In the Imatest EXE library, if an error occurs within one of the analysis module functions, the return code from the executable will be -1 instead of 0. If you are calling the executable from a batch script, you can check what the return code was to determine if an exception occurred or not.

Here is an example of how you can test for an exception using the Imatest IT EXE Library:

[shell]
sfr.exe "-1" "’C:\ImatestSamples\sfr_example.jpg’" "’C:\Program Files\Imatest\v5.2\IT\bin’" "’C:\ImatestSamples\imatest-v2.ini’" "’C:\ImatestSamples\Results’"
if %ERRORLEVEL% neq 0 (
echo ‘*** Error calling sfr. Check output for details.’
)
[/shell]

[cpp]
int stdOutHandler(const char* str)
{
// Record output
…
return strlen(str);
}

int stdErrHandler(const char* str)
{
// Record output
…
return strlen(str);
}

if (!imatest_libraryInitializeWithHandlers(stdErrHandler, stdOutHandler))
{
…
[/cpp]

[python]
import StringIO

std_out = StringIO.StringIO()
std_err = StringIO.StringIO()

libImatest = ImatestLibrary(stdout=out_file, stderr=err_file)
# Call library methods …
print std_out.getvalue()
print std_err.getvalue()
std_out.close()
std_err.close()
[/python]

Advanced: Asynchronous Programming with Imatest IT .NET

With the Imatest IT .NET library, you can easily use write asynchronous module calls in your custom applications using the .NET Framework’s async and await keywords along with Imatest IT .NET’s JSONAsync() 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\v5.2\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.:

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

Below is a code snippet of synchronous code making a simple call to the SFRPlus module:

[csharp]
protected void TestImage()
{
using (Library lib = new Library())
{
string rootDir = @"C:\ImatestSamples\";
string imagePath = @"C:\ImatestSamples\sfrplus_example.jpg";

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

Console.Out.WriteLine(result);
}
}
[/csharp]

Below is the same code that has been converted to call the SFRplus module asynchronously:

[csharp]
protected async void TestImage()
{
using (Library lib = new Library())
{
string rootDir = @"C:\ImatestSamples\";
string imagePath = @"C:\ImatestSamples\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);
}
}
[/csharp]

Initializing the Imatest IT .NET Libraries Asynchronously

The Imatest IT .NET and Imatest Acquisition Library classes have static CreateAsync() methods that can be called using the await keyword:

[csharp]
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.
await itLib.SFRplus.JSONAsync(rootDir, inputFile, OperationMode.Separate);

/// At this point only the main thread is running
}
[/csharp]

To use the parallel_analyzer, first create a list of analysis tasks that need to be run. Each task will be assigned to a different parallel process. The number of available concurrent processes depends on how many cores your machine has, though you can tell Imatest IT to use fewer cores if you need.

The parallel_analyzer_shell() C++ interface

The signature of the parallel_analyzer_shell() function is as follows:

[cpp]
parallel_analyzer_shell(int nargout, mwArray& results, const mwArray& tasks, const mwArray& iniFileName, const mwArray& runParallel, const mwArray& numWorkers);
[/cpp]

The tasks array is a mwArray of ClassID mxSTRUCT_CLASS. This data type has named fields, as with C++ structs. Each element of the task array has these fields:

input – The supplied image in the form of file path(s) or numeric array(s)
analysisID – An integer that tells IT which module to run. The allowed values are defined in the ImatestAnalysisIDs enum (see <IT installation root>\libs\library\cpp\Imatest_analysis_ids.h):
imatest::BLEMISH_ANALYSIS_ID
imatest::CHECKERBOARD_ANALYSIS_ID
imatest::COLORCHECK_ANALYSIS_ID
imatest::DISTORTION_ANALYSIS_ID
imatest::DOTPATTERN_ANALYSIS_ID
imatest::ESFRISO_ANALYSIS_ID
imatest::MULTITEST_ANALYSIS_ID
imatest::RANDOM_ANALYSIS_ID
imatest::SFR_ANALYSIS_ID
imatest::SFRPLUS_ANALYSIS_ID
imatest::SFRREG_ANALYSIS_ID
imatest::STAR_ANALYSIS_ID
imatest::UNIFORMITY_ANALYSIS_ID
imatest::WEDGE_ANALYSIS_ID
jsonMetaData – Image meta data in the form of serialized JSON object string. This field only needs to be filled when numeric arrays are being supplied.

An example of the creation of the tasks array for four image files is available in the parallel_analyzer sample project (<IT installation root>\samples\cpp\parallel_analyzer\main.cpp). In this example, the tasks array is created with

[cpp]
mwSize numRows = 4; // There are 4 images to test
mwSize numCols = 1;
int numFields = 3;
const char* fieldNames[] = {"input\0", "analysisID\0", "jsonMetadata\0"};

mwArray tasks(numRows, numCols, numFields, fieldNames);
[/cpp]

To supply values to the individual tasks, we make use of the Get(const char* fieldName, int numIndices, int index1, …) accessor for mxSTRUCT_CLASS mwArrays:

[cpp]
// define the first task
tasks.Get("input", 1, 1).Set(mwArray(".\\sfrplus_example.jpg"));
tasks.Get("analysisID", 1, 1).Set(sfrplusID);

// define the second task
tasks.Get("input", 1, 2).Set(mwArray(".\\blemish_example.jpg"));
tasks.Get("analysisID", 1, 2).Set(blemishID);

//define the third task
tasks.Get("input", 1, 3).Set(mwArray(".\\colorcheck_example.jpg"));
tasks.Get("analysisID", 1, 3).Set(colorcheckID);

//define the fourth task
tasks.Get("input", 1, 4).Set(mwArray(".\\esfriso_example.jpg"));
tasks.Get("analysisID", 1, 4).Set(esfrisoID);
[/cpp]

It is important to note that this array is 1-indexed.

Creation of the remaining inputs is simpler; we use the mwArray contructors for scalar numeric values and strings.

[cpp]
mwArray iniFileName("..\\Imatest_INI\\imatest-v2.ini");

mwArray runParallel(true);

mwArray numWorkers(2);
[/cpp]

Lastly, we call parallel_analyzer_shell() with the inputs.

[cpp]
mwArray out;
parallel_analyzer_shell(1, out, tasks, iniFileName, runParallel, numWorkers);
[/cpp]

The results will be returned in the out mwArray, which contains a JSON encoded string that can be parsed into an object array with one result object per task. Each result object has this form:

[plain]
{
"data": {
"dateRun": "18-Sep-2017 10:26:59",
"ini_file_name": "C:\\images\\ini_file\\imatest-v2.ini",
"ini_time_size": "18-Sep-2017 10:26:45 21822B MD5 = ac109f86b635bd5b4344d252969e64a7",
"version": "Imatest 5.0.0 SFRplus",
"title": "sfrplus_0123.jpg",
"image_path_name": "C:\\images\\sfrplus_0123.jpg",

…
},
"errorID": "",
"errorMessage": "",
"errorReport": ""
}

[/plain]

If any exceptions occurred during processing, they will be reported in the errorID, errorMessage, and errorReport properties. While handling your results, you should always check whether the errorID property is empty or not before working with the data property.

In addition to the parallel_analyzer sample, IT also includes a C++ sample project that implements parallel processing using the Boost.Interprocess Library (<IT installation root>\samples\cpp\CPP_parallel_test_project). More information can be found in this article.

To use the parallel_analyzer, first create a list of analysis tasks that need to be run. Each task will be assigned to a different parallel process. The number of available concurrent processes depends on how many cores your machine has, though you can tell Imatest IT to use fewer cores if you need.

The task file

In the stand-alone executable version of parallel_analyzer, the list of tasks is supplied in the form of a JSON encoded file. In this JSON file, the list of tasks is represented by a JSON object array, where each individual task is an object within that array. For each task the following fields need to be defined:

input – The supplied image in the form of file path(s) or numeric array(s)
analysisID – An integer that tells IT which module to run. The allowed values are defined below:

 jsonMetaData – Image meta data in the form of serialized JSON object. This field only needs to be filled when numeric arrays are being supplied.

As an example, suppose that there are two files named blemish_example.jpg and sfrplus_example.jpg in the current working directory that need to be analyzed by the Blemish and SFRplus modules, respectively. The contents of this tasks file is then

[plain]
[
{
"input": "blemish_example.jpg",
"analysisID": 1,
"jsonMetadata": ""
},
{
"input": "sfrplus_example.jpg",
"analysisID": 10,
"jsonMetadata": ""
}
]
[/plain]

The parallel_analyzer_exe interface 

The signature of the parallel_analyze executable is as follows:

[plain]
parallel_analyzer_exe taskFileName iniFileName runParallel numWorkers [-o|–output_filename &amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;lt;filename&amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;amp;gt;]
[/plain]

The required inputs are
taskFileName: The path to the JSON task file (see the Task File section below).

iniFileName: The path to the Imatest INI file

runParallel: A boolean value that is 1 if the user wants parallel processing and 0 if serial processing is desired.

numWorkers: An integer value indicating the number of child processes to invoke for analysis. The maximum value is the number of physical cores.

with remaining optional input
-o|–output_filename <filename>: Supply the full file path for the file into which the results are saved. Note that either ‘-o’ or ‘–output_filename’ can be used. If this optional input is not supplied, the results are saved to a file named ‘results_<current date and time>.json’.

Continuing the above example, suppose that the task file (tasks.json) from above is in our Documents folder with the two image files and our INI file (imatest-v2.ini). The call to run the two tasks in parallel on two processes would be

[shell]
cd %HOMEPATH%\Documents
C:\Program Files\Imatest\v5.0\IT\bin\parallel_analyzer_exe.exe tasks.json imatest-v2.ini 1 2
[/shell]

And on Linux the command would be

[shell]
cd ~/Documents
/usr/local/Imatest/v5.0.0/IT/bin/parallel_analyzer_exe ./tasks.json ./imatest-v2.ini 1 2
[/shell]

The results will be saved to a JSON encoded file in the form of a JSON object array with one result object per task. Each result object has this form:

[plain]
{
"data": {
"dateRun": "18-Sep-2017 10:26:59",
"ini_file_name": "C:\\images\\ini_file\\imatest-v2.ini",
"ini_time_size": "18-Sep-2017 10:26:45 21822B MD5 = ac109f86b635bd5b4344d252969e64a7",
"version": "Imatest 5.0.0 SFRplus",
"title": "sfrplus_0123.jpg",
"image_path_name": "C:\\images\\sfrplus_0123.jpg",

…
},
"errorID": "",
"errorMessage": "",
"errorReport": ""
}

[/plain]

If any exceptions occurred during processing, they will be reported in the errorID, errorMessage, and errorReport properties. While handling your results, you should always check whether the errorID property is empty or not before working with the data property.

Starting with version 5.0, Imatest IT now allows you to analyze several different images in parallel, using the new parallel_analyzer function.

To use the parallel_analyzer, first create a list of analysis tasks that need to be run. Each task will be assigned to a different parallel process. The number of available concurrent processes depends on how many cores your machine has, though you can tell Imatest IT to use fewer cores if you need.

To create an analysis task, use the new_parallel_task function:

[python]
ImatestLibrary.new_parallel_task(image_files=None, image_data=None, analysis_type=None, image_data_meta_data=None)
[/python]

add each of your tasks to a list, then call ImatestLibrary.parallel_analyser, passing in the path to your INI file, True for run_parallel, and the number of worker processes you’d like to use:

[python]
ini_file = r’C:\images\ini_file\imatest-v2.ini’

tasks = []
tasks.append(library.new_parallel_task(image_files=r’C:\images\sfrplus_0123.jpg’, analysis_type=ImatestLibrary.SFRPLUS_ANALYSIS))
tasks.append(library.new_parallel_task(image_files=[r’C:\images\blemish_0001.jpg’, r’C:\images\blemish_0002.jpg’, r’C:\images\blemish_0003.jpg’], analysis_type=ImageLibrary.BLEMISH_ANALYSIS))
….

result = library.parallel_analyzer(tasks=tasks, ini_file=ini_file, run_parallel=True, num_workers=4)
[/python]

The result will be a JSON encoded string that can be parsed into an array of result objects using json.loads(result). Each result object has this form:

[plain]
{
"data": {
"dateRun": "18-Sep-2017 10:26:59",
"ini_file_name": "C:\\images\\ini_file\\imatest-v2.ini",
"ini_time_size": "18-Sep-2017 10:26:45 21822B MD5 = ac109f86b635bd5b4344d252969e64a7",
"version": "Imatest 5.0.0 SFRplus",
"title": "sfrplus_0123.jpg",
"image_path_name": "C:\\images\\sfrplus_0123.jpg",

…
},
"errorID": "",
"errorMessage": "",
"errorReport": ""
}
[/plain]

If any exceptions occurred during processing, they will be reported in the errorID, errorMessage, and errorReport properties. While handling your results, you should always check whether the errorID property is empty or not before working with the data property:

[python]
resultArr = json.loads(result)

for task_result in result_arr:
if task_result[‘errorID’]:
# Gracefully handle the error
else:
result_data = task_result[‘data’]
# Process the results in the result_data dictionary
[/python]

Starting with version 5.0, Imatest IT now allows you to analyze several different images in parallel, using the new ParallelAnalyzer.Execute() method.

To use the ParallelAnalyzer, first create a List of ImatestTasks objects that contain images to be analyzed. Each task will be assigned to a different parallel process. The number of available concurrent worker processes depends on how many cores your machine has, though you can tell Imatest IT to use fewer workers if you need.

To create an ImatestTask, use one of the overloaded ImatestTask.Create() methods:

Add each of your tasks to a collection of type ImatestTask, then call Library.ParallelAnalyzer.Execute(), passing in the path to your INI file for iniFilePath, true for runInParallel, and the number of worker processes you’d like to use:

The result will be a JSON encoded string that can be parsed into an array of result objects using any .NET JSON library. Each result object has this form:

[plain]
{
"data": {
"dateRun": "18-Sep-2017 10:26:59",
"ini_file_name": "C:\\images\\ini_file\\imatest-v2.ini",
"ini_time_size": "18-Sep-2017 10:26:45 21822B MD5 = ac109f86b635bd5b4344d252969e64a7",
"version": "Imatest 5.0.0 SFRplus",
"title": "sfrplus_0123.jpg",
"image_path_name": "C:\\images\\sfrplus_0123.jpg",

…
},
"errorID": "",
"errorMessage": "",
"errorReport": ""
}
[/plain]

If any exceptions occurred during processing, they will be reported in the errorID, errorMessage, and errorReport properties. While handling your results, you should always check whether the errorID property is empty or not before working with the data property.

First, create an image options dictionary by calling ImatestLibrary.get_arbitrary_charts_options():

[python]
ImatestLibrary.get_arbitrary_charts_options(self, width=None, height=None, encoding=None, filename=None, extension=None, pixel_size=None)
[/python]

Once you have the options object, you can then call the one of the arbitrary_charts functions:

[python]
ImatestLibrary.arbitrary_charts_separate(self, image_files=None, image_data=None, chart_file=None, ini_file=None, options=None)
ImatestLibrary.arbitrary_charts_signal_average(self, image_files=None, image_data=None, chart_file=None, ini_file=None, options=None)
[/python]

The arbitrary_charts_separate function will analyze multiple inputs separately, while the arbitrary_charts_signal_average function will combine two images’ results into a single signal averaged result.

The result will be a JSON-encoded string, which can be converted to a dict using json.loads(), of this form:

[plain]
{
"Info": {
"Timestamp": "04-Oct-2017 09:09:08",
"Version": "Imatest 5.1.0.25883 Alpha ",
"Build": "2017-10-03",
"Calculation_time_seconds": [44.36107732]
},
"Results_array_sources": "C:\\images\\P1858_combination_chart_example.jpg",
"Results": {
…
}
}
[/plain]

First, create an ArbitraryChartOptions object:

Once you have the ArbitraryChartOptions object, you can then call the one of the ArbitraryCharts methods:

The ArbitraryCharts.Separate methods will analyze multiple inputs separately, while the ArbitraryCharts.SignalAverage method will combine two images’ results into a single signal averaged result.

The result will be a JSON-encoded string, which can be parsed using any .NET JSON library, of this form:

[plain]
{
"Info": {
"Timestamp": "04-Oct-2017 09:09:08",
"Version": "Imatest 5.1.0.25883 Alpha ",
"Build": "2017-10-03",
"Calculation_time_seconds": [44.36107732]
},
"Results_array_sources": "C:\\images\\P1858_combination_chart_example.jpg",
"Results": {
…
}
}
[/plain]