Imatest IT 說明

using Imatest.IT;

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.

Imatest.IT.Library implements the IDisposable interface, and we recommend that you wrap your library instance inside of a using statement to ensure that the Dispose() method is called properly. The Dispose() method cleans up the Matlab Runtime, and also releases your floating license seat, if you are using a floating license.

using Imatest.IT;
class Program
{
    static void Main(string[] args)
    {
        using (Library itLib = new Library())
        {
            // ....
        }
    }
}

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:

string SFR.JSON(string rootDir, string inputFile, OperationMode opMode)
string SFR.JSON(string rootDir, IEnumerable<string> inputFiles, OperationMode opMode)
string SFR.JSON(string rootDir, string inputFile, OperationMode opMode, string iniFilePath)
string SFR.JSON(string rootDir, IEnumerable<string> inputFiles, OperationMode opMode, string iniFilePath)
string SFR.JSON(string rootDir, byte[] inputBytes, DirectReadOptions directReadOptions)
string SFR.JSON(string rootDir, byte[] inputBytes, DirectReadOptions directReadOptions, string iniFilePath)

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.

using Imatest.IT;
class Program
{
    static void Main(string[] args)
    {
        using (Library itLib = new Library())
        {
            try {
                string result = itLib.SFR.JSON(rootDir, inputFile, OperationMode.Separate, iniFilePath);
            } catch (Exception ex) {
                Console.Out.WriteLine(ex.Message);
            }
        }
    }
}

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 FilesImatestv26.1ITlibslibrary.NET.NET 4.8 for .NET Framework 4.8 and C:Program FilesImatestv26.1ITlibslibrary.NET.NET 9.0 for .NET 9.0), 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 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

At the top of your source code file, add an Imports statement for Imatest.IT:

Imports Imatest.IT

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.

Imatest.IT.Library implements the IDisposable interface, and we recommend that you wrap your library instance inside of a Using statement to ensure that the Dispose() method is called properly. The Dispose() method cleans up the Matlab Runtime, and also releases your floating license seat, if you are using a floating license.

Imports Imatest.IT
Module Program
    Sub Main()
        Using itLib = New Library()
            ' ...
        End Using
    End Sub
End Module

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:

SFR.JSON(String rootDir, String inputFile, OperationMode opMode) As String
SFR.JSON(String rootDir, IEnumerable(Of String) inputFiles, OperationMode opMode) As String
SFR.JSON(String rootDir, String inputFile, OperationMode opMode, String iniFilePath) As String
SFR.JSON(String rootDir, IEnumerable(Of String) inputFiles, OperationMode opMode, String iniFilePath) As String
SFR.JSON(String rootDir, Byte() inputBytes, DirectReadOptions directReadOptions) As String
SFR.JSON(String rootDir, Byte() inputBytes, DirectReadOptions directReadOptions, String iniFilePath) As String

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.

Imports Imatest.IT
Module Program
    Sub Main()
        Using itLib = New Library()
            Try
                Dim result = itLib.SFR.JSON(rootDir, imagePath, OperationMode.Separate, iniFilePath)
            Catch ex As Exception
                Console.Out.WriteLine(ex.Message)
            End Try
        End Using
    End Sub
End Module

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):

sfr.exe op-mode input-file bin-directory ini-file [result-directory] [other-images ...]

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).

sfr.exe "-1" "C:ImatestSamplessfr_example.jpg" "C:Program FilesImatestv26.1ITbin" "C:ImatestSamplesimatest-v2.ini" "C:ImatestSamplesResults"

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

Calling the Imatest IT EXE Interface

The Imatest IT EXE Library can be called using macOS or Linux Bash script files. We recommend making sure that the IT bin directory is in your PATH variable.  You may need to add to your path manually on macOS and 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):

./run_sfr.sh op-mode input-file bin-directory ini-file [result-directory] [other-images ...]

The Imatest IT EXE library parameters are listed here:

Calling Imatest IT Modules

Imatest IT EXE modules are called using the command line with the .sh files.

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

./run_sfr.sh "-1" "$HOME/ImatestSamples/sfr_example.jpg" "/Applications/Imatest/IT/v26.1/bin" "$HOME/ImatestSamples/imatest-v2.ini" "$HOME/ImatestSamples/Results"

When the module is finished running, the result files will be written to the result-directory folder (in this case, $HOME/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:

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: %dn", 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: %sn", errorNameStr);
                break;
        }
        mxDestroyArray(errorID);
        mxDestroyArray(errorName);
        retVal = errorCode;
    }
    else {
        printf("*** Unknown Error.n");
        retVal = -1005;
    }
}
else
{
   retVal = 0;
   ...
}

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:

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;
}

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 with Objective-C++:

- (void)postTest: (id)param
{
    @autoreleasepool {
        try{
            // Declare and initialize outputJSON, fileParam, pathParam, keysParam, modeParam, and varargin mwArray's
            NSLog(@"Running test.");
            sfrplus_shell(1, outputJSON, fileParam, pathParam, keysParam, modeParam, varargin);
            // Process JSON returned in outputJSON mwArray 
        } catch (mwException ex) {
            mwArray mwErrorID, mwErrorName;
            mwString mwErrorNameStr;
            getExceptionID(2, mwErrorID, mwErrorName);
            int err = (int)mwErrorID;
            switch (err)
            {
                case imatest::kImatestFileNotFoundException:
                    NSLog(@"*** File was not found. Check the file path.");
                    break;
                case imatest::kBadFramingException:
                    NSLog(@"*** Image is not framed correctly.");
                    break;
                default:
                    mwErrorNameStr = mwErrorName.Get(1,1).ToString();
                    NSLog(@"*** Unexpected Error: %s", (const char*)mwErrorNameStr);
                    break;
            }
            retVal = err;
        }
    }
}
- (void)runTest
{
     // Start a new thread to run sfrplus_shell()
     [NSThread detachNewThreadSelector:@selector(postTest:) toTarget:self withObject:nil];
}

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:

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, ))

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:

try
{
    string result = itLib.SFRplus.JSON(rootDir, imagePath, OperationMode.Separate, iniFile);
}
catch (Exception ex)
{
    ImatestException iex = lib.GetLastException();
    string errorName = lib.GetExceptionName();
    if (iex == ImatestException.FloatingLicenseException)
    {
        Console.Out.WriteLine("All floating license seats are in use.  Exit Imatest on another computer and try again.");
    }
    else if (iex == ImatestException.LicenseException)
    {
        Console.Out.WriteLine("License Exception: {0}: {1}", errorName, ex.Message);
    }
    else
    {
        Console.Out.WriteLine("An error has occurred:");
        Console.Out.WriteLine(ex.Message);
    }
}

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:

Try
    Dim result = itLib.SFR.JSON(rootDir, imagePath, OperationMode.Separate, iniFile)
Catch ex As Exception
    Dim iex As ImatestException = library.GetLastException()
    Dim errorName As String = library.GetExceptionName()
    If iex = ImatestException.FloatingLicenseException Then
        Console.Out.WriteLine("All floating license seats are in use.  Exit Imatest on another computer and try again.")
    ElseIf iex = ImatestException.LicenseException Then
        Console.Out.WriteLine("License Exception: {0}: {1}", errorName, ex.Message)
    Else
        Console.Out.WriteLine("An error has occurred:")
        Console.Out.WriteLine(ex.Message)
    End If
End Try

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:

sfr.exe "-1" "'C:ImatestSamplessfr_example.jpg'" "'C:Program FilesImatestv26.1ITbin'" "'C:ImatestSamplesimatest-v2.ini'" "'C:ImatestSamplesResults'"
if %ERRORLEVEL% neq 0 (
    echo '*** Error calling sfr. Check output for details.'
)

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:

./run_sfr.sh "-1" "$HOME/ImatestSamples/sfr_example.jpg" "/Applications/Imatest/IT/v26.1/bin" "$HOME/ImatestSamples/imatest-v2.ini" "$HOME/ImatestSamples/Results"
if [ "$?" -ne "0" ]
    echo '*** Error calling sfr. Check output for details.'
fi

To redirect output text using the Imatest C or C++ libraries, you need to use the function imatest_libraryInitializeWithHandlers(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler) instead of imatest_libraryInitialize(), passing in two pointers to functions that will handle the "error" and "standard" outputs, respectively. The functions accept a const char* input, and return an int, which is the number of characters processed.

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))
{
   ...

To redirect output text using the Imatest C or C++ libraries, you need to use the function imatest_libraryInitializeWithHandlers(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler) instead of imatest_libraryInitialize(), passing in two pointers to functions that will handle the "error" and "standard" outputs, respectively. The functions accept a const char* input, and return an int, which is the number of characters processed.

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))
{
   ...

To redirect output text using the Imatest C++ libraries in Objective-C, you need to use the function libImatestInitializeWithHandlers(mclOutputHandlerFcn error_handler, mclOutputHandlerFcn print_handler) instead of libImatestInitialize(), passing in two pointers to functions that will handle the "error" and "standard" outputs, respectively. The functions accept a const char* input, and return an int, which is the number of characters processed.

int stdOutHandler(const char* str)
{
    // Record output
    ...
    return strlen(str);
}
int stdErrHandler(const char* str)
{
    // Record output
    ...
    return strlen(str);
}
if (!libImatestInitializeWithHandlers(stdErrHandler, stdOutHandler))
{
   ...

To redirect output text using the Imatest Python library, you need to pass in StringIO objects to the ImatestLibrary() constructor, as the stdout and stderr named parameters. You can extract the contents of these objects using the getvalue() method, and should call close() on them at the end of your script.

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()

To redirect output text using the Imatest .NET library, you need to use the Console.SetOut(TextWriter writer) and Console.SetError(TextWriter writer) methods. You must call these methods before creating the Imatest.IT.Library object.

StringWriter stdOut = new StringWriter();
StringWriter stdErr = new StringWriter();
Console.SetOut(stdOut);
Console.SetError(stdErr);
...
string stdOutText = stdOut.ToString();
string stdErrText = stdErr.ToString();
stdOut.Close();
stdErr.Close();

To redirect output text using the Imatest .NET library, you need to use the Console.SetOut(TextWriter writer) and Console.SetError(TextWriter writer) methods. You must call these methods before creating the Imatest.IT.Library object.

Dim stdOut As New StringWriter()
Dim stdErr As New StringWriter()
Console.SetOut(stdout)
Console.SetError(stderr)
...
Dim stdOutStr As String = stdOut.ToString()
Dim stdErrStr As String = stdErr.ToString()
stdOut.Close()
stdErr.Close()

To redirect output using the Imatest IT EXE interface, use the typical command line syntax you normally would use. For example,

sfr.exe "-1" "C:ImatestSamplessfr_example.jpg" "C:Program FilesImatestv26.1ITbin" "C:ImatestSamplesimatest-v2.ini" "C:ImatestSamplesResults" > "C:ImatestSamplesResultssfr_output.log" 2&>&1

will redirect stdout and stderr streams to "C:ImatestSamplesResultssfr_output.log".

To redirect output using the Imatest IT EXE interface, use the typical command line syntax you normally would use. For example,

./run_sfr.sh "-1" "$HOME/ImatestSamples/sfr_example.jpg" "/Applications/Imatest/IT/v26.1/bin" "$HOME/ImatestSamples/imatest-v2.ini" "$HOME/ImatestSamples/Results" > "$HOME/ImatestSamples/Results/sfr_output.log" 2&>&1

will redirect stdout and stderr streams to "$HOME/ImatestSamples/Results/sfr_output.log".

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 FilesImatestv26.1ITsamples.NETImatestITSampleProjectImatestITSampleProject.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:

protected void TestImage()
{
    using (Library lib = new Library())
    {
        string rootDir = @"C:ImatestSamples";
        string imagePath = @"C:ImatestSamplessfrplus_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 SFRplus module asynchronously:

protected async void TestImage()
{
    using (Library lib = new Library())
    {
        string rootDir = @"C:ImatestSamples";
        string imagePath = @"C:ImatestSamplessfrplus_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 Acquisition Library classes have 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.
    await itLib.SFRplus.JSONAsync(rootDir, inputFile, OperationMode.Separate); 
    /// At this point only the main thread is running
}

Coming soon...

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:

parallel_analyzer_shell(int nargout, mwArray& results, const mwArray& tasks, const mwArray& iniFileName, const mwArray& runParallel, const mwArray& numWorkers);

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>libslibrarycppImatest_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>samplescppparallel_analyzermain.cpp). In this example, the tasks array is created with

mwSize numRows = 4; // There are 4 images to test
 mwSize numCols = 1;
 int numFields = 3;
 const char* fieldNames[] = {"input", "analysisID", "jsonMetadata"};
 mwArray tasks(numRows, numCols, numFields, fieldNames);
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:

// 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);

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.

mwArray iniFileName("..\Imatest_INI\imatest-v2.ini");
mwArray runParallel(true);
mwArray numWorkers(2);

Lastly, we call parallel_analyzer_shell() with the inputs.

mwArray out;
parallel_analyzer_shell(1, out, tasks, iniFileName, runParallel, numWorkers);

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:

{
   "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": ""
}

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>samplescppCPP_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 parallel_analyzer_shell() C++ interface

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

parallel_analyzer_shell(int nargout, mwArray& results, const mwArray& tasks, const mwArray& iniFileName, const mwArray& runParallel, const mwArray& numWorkers);

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>samplescppparallel_analyzermain.cpp). In this example, the tasks array is created with

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

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:

// 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);

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.

mwArray iniFileName("..\Imatest_INI\imatest-v2.ini");
mwArray runParallel(true);
mwArray numWorkers(2);

Lastly, we call parallel_analyzer_shell() with the inputs.

mwArray out;
parallel_analyzer_shell(1, out, tasks, iniFileName, runParallel, numWorkers);

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:

{
   "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": ""
}

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.

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

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

The parallel_analyzer_exe interface

The signature of the parallel_analyze executable is as follows:

parallel_analyzer_exe taskFileName iniFileName runParallel numWorkers [-o|--output_filename <filename>]

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

cd %HOMEPATH%Documents
C:Program FilesImatestv26.1ITbinparallel_analyzer_exe.exe tasks.json imatest-v2.ini 1 2

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:

{
   "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": ""
}

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.

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

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

The parallel_analyzer_exe interface

The signature of the parallel_analyze executable is as follows:

./run_parallel_analyzer.sh taskFileName iniFileName runParallel numWorkers [-o|--output_filename FILENAME]

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 on macOS to run the two tasks in parallel on two processes would be

cd ~/Documents
/Applications/Imatest/IT/v26.1/bin/run_parallel_analyzer.sh ./tasks.json ./imatest-v2.ini 1 2

And on Linux the command would be

cd ~/Documents
/usr/local/Imatest/v26.1/IT/bin/run_parallel_analyzer.sh ./tasks.json ./imatest-v2.ini 1 2

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:

{
   "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": ""
}

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.

Imatest IT 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:

ImatestLibrary.new_parallel_task(image_files=None, image_data=None, analysis_type=None, image_data_meta_data=None)

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:

ini_file = r'C:imagesini_fileimatest-v2.ini'
tasks = []
tasks.append(library.new_parallel_task(image_files=r'C:imagessfrplus_0123.jpg', analysis_type=ImatestLibrary.SFRPLUS_ANALYSIS))
tasks.append(library.new_parallel_task(image_files=[r'C:imagesblemish_0001.jpg', r'C:imagesblemish_0002.jpg', r'C:imagesblemish_0003.jpg'], analysis_type=ImageLibrary.BLEMISH_ANALYSIS))
....
result = library.parallel_analyzer(tasks=tasks, ini_file=ini_file, run_parallel=True, num_workers=4)

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:

{
   "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": ""
}

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:

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

Imatest IT 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:

public static ImatestTask Create(string imageFilePath, ImatestModule module);
public static ImatestTask Create(IEnumerable<string> imageFilePaths, ImatestModule module);
public static ImatestTask Create(byte[] imageData, ImatestModule module, DirectReadOptions imageMetaData);
public static ImatestTask Create(UInt16[] imageData, ImatestModule module, DirectReadOptions imageMetaData);
public static ImatestTask Create(UInt32[] imageData, ImatestModule module, DirectReadOptions imageMetaData);

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:

string inFile = "C:\images\ini_file\imatest-v2.ini";
List<ImatestTask> lstTasks = new List<ImatestTask>();
lstTasks.Add(ImatestTask.Create("C:\images\sfrplus_0123.jpg", ImatestModule.SFRplus));
lstTasks.Add(ImatestTask.Create(new List<string>() { "C:\image\blemish_0001.jpg", "C:\images\blemish_0002.jpg", "C:\images\blemish_0003.jpg" }, ImatestModule.Blemish));
....
string result = library.ParallelAnalyzer.Execute(lstTasks, iniFile, true, 2);

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:

{
   "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": ""
}

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.

Imatest IT 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:

Public Shared Function Create(imageFilePath As String, [module] As ImatestModule) As ImatestTask
Public Shared Function Create(imageFilePaths As IEnumerable(Of String), [module] As ImatestModule) As ImatestTask
Public Shared Function Create(imageData() As Byte, [module] As ImatestModule, imageMetaData As DirectReadOptions) As ImatestTask
Public Shared Function Create(imageData() As UShort, [module] As ImatestModule, imageMetaData As DirectReadOptions) As ImatestTask
Public Shared Function Create(imageData() As UInteger, [module] As ImatestModule, imageMetaData As DirectReadOptions) As ImatestTask

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:

Dim iniFilePath As String
Dim lstTasks As New List(Of ImatestTask)()
Dim result As String
iniFilePath = "C:\images\ini_file\imatest-v2.ini"
lstTasks.Add(ImatestTask.Create("C:\images\sfrplus_0123.jpg", ImatestModule.SFRplus))
lstTasks.Add(ImatestTask.Create("C:\image\blemish_0001.jpg" ImatestModule.Blemish))
List<ImatestTask> lstTasks = new List<ImatestTask>();
lstTasks.Add(ImatestTask.Create("C:\images\sfrplus_0123.jpg", ImatestModule.SFRplus));
lstTasks.Add(ImatestTask.Create(new List<string>() { "C:\image\blemish_0001.jpg", "C:\images\blemish_0002.jpg", "C:\images\blemish_0003.jpg" }, ImatestModule.Blemish));
....
result = library.ParallelAnalyzer.Execute(lstTasks, iniFilePath, True, 4)

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:

{
   "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": ""
}

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.

Coming soon...

Coming soon...

The function prototype for Arbitrary Charts is

 arbitrary_charts_shell(int nargout, mwArray& output, const mwArray& inputData, const mwArray& chartFile, const mwArray& iniFile, const mwArray& averageMode, const mwArray& optionsJson)

where the parameters are defined in the following table:

nargoutintAlways set this to 1. This parameter indicates the number of desired outputs.

To begin, declare the iniFileParam and chartFileParam variables and supply the fully-qualified paths to INI and chart definition files.

- (void)runTest: (id)param
{
    @autoreleasepool {
        try{
            mwArray iniFileParam("/some/folder/imatest-v2.ini");
            mwArray chartFileParm("/some/folder/chart_definition.json");

Next the images need to be supplied either as one or more image files, or as image data arrays. If you want to supply more than one image file at a time you will need to first construct an mwArray of type mxCELL_CLASS. For example, if you had three images inputDataParam would be constructed as follows:

           mwArray inputDataParam(3, 1, mxCELL_CLASS);
           inputDataParam.Get(1, 1).Set(mwArray("/some/folder/image1.jpg"));
           inputDataParam.Get(1, 2).Set(mwArray("/some/folder/image2.jpg"));
           inputDataParam.Get(1, 3).Set(mwArray("/some/folder/image3.jpg"));

Alternatively, if you had only a single image file, you can construct inputDataParam by passing the image file path directly to the mwArray constructor

            mwArray inputDataParam("/some/folder/image.jpg");

If you are supplying more than one image, you can specify whether the images should be averaged (averageMode == 1) or analyzed separately (averageMode == 0) using the averageModeParam, which can be set to contain a numeric value or a string such as

The remaining parameter to construct is optionsJson. The JSON properties defined in the optionsJson parameter are defined in the table below.

In this example, image files are being supplied, so we are only required to supply the image encoding, for example:

           mwArray optionsJsonParam("{"encoding":"sRGB"}");

Lastly, we call arbitrary_charts_shell and supply the parameters that have been constructed

            // Call the library function
            mwArray output
            arbitrary_charts_shell(1, output, inputDataParam, chartFileParm, iniFileParam, averageModeParam, optionsJsonParam);
            // Extract the JSON-encoded string.
            // Note that the mwArray contains only UTF-16 strings, which we must load into an NSString
            auto numel = out.NumberOfElements();
            std::u16string buffer(numel+1, 0);
            out.GetCharData(&buffer[0], numel);
            char* data = (char*)buffer.data();
            unsigned long size = buffer.size()*sizeof(char16_t);
            NSString* jsonString =[[NSString alloc] initWithBytes:data length:size encoding:NSUTF16LittleEndianStringEncoding];
            // Process results            
        } catch (mwException ex){
            NSLog(@"Error");
            NSLog(@"%s", ex.what());
            ex.print_stack_trace();
        }
    }
}

The result will be a JSON-encoded string of this form:

{
    "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": {
...
    }
}

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

ImatestLibrary.get_arbitrary_charts_options(self, width=None, height=None, encoding=None, filename=None, extension=None, pixel_size=None)

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

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)

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:

{
    "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": {
     ...
    }
}

First, create an ArbitraryChartOptions object:

ArbitraryChartOptions arbChartOptions = new ArbitraryChartOptions();
arbChartOptions.Encoding = ImageEncoding.sRGB;
arbChartOptions.Width = 1296;
arbChartOptions.Height = 808;

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

public string Separate(string inputFile, string chartFile, string iniFile, ArbitraryChartOptions options);
public string Separate(IEnumerable<string> inputFiles, string chartFile, string iniFile, ArbitraryChartOptions options);
public string Separate(byte[] imageData, string chartFile, string iniFile, ArbitraryChartOptions options);
public string Separate(ushort[] imageData, string chartFile, string iniFile, ArbitraryChartOptions options);
public string Separate(uint[] imageData, string chartFile, string iniFile, ArbitraryChartOptions options);
public Task<string> SeparateAsync(string inputFile, string chartFile, string iniFile, ArbitraryChartOptions options);
public Task<string> SeparateAsync(IEnumerable<string> inputFiles, string chartFile, string iniFile, ArbitraryChartOptions options);
public Task<string>; SeparateAsync(byte[] imageData, string chartFile, string iniFile, ArbitraryChartOptions options);
public Task<string> SeparateAsync(ushort[] imageData, string chartFile, string iniFile, ArbitraryChartOptions options);
public Task<string> SeparateAsync(uint[] imageData, string chartFile, string iniFile, ArbitraryChartOptions options);
public string SignalAverage(IEnumerable<string> inputFiles, string chartFile, string iniFile, ArbitraryChartOptions options);
public Task<string> SignalAverageAsync(IEnumerable<string> inputFiles, string chartFile, string iniFile, ArbitraryChartOptions options);

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:

{
    "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": {
...
    }
}

First, create an ArbitraryChartOptions object:

Dim arbChartOptions As ArbitraryChartOptions
arbChartOptions = new ArbitraryChartOptions()
arbChartOptions.Encoding = ImageEncoding.sRGB
arbChartOptions.Width = 1296
arbChartOptions.Height = 808

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

Public Function Separate(inputFile As String, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As String
Public Function Separate(inputFiles As IEnumerable(Of String), chartFile As String, iniFile As String, options As ArbitraryChartOptions) As String
Public Function Separate(imageData() As Byte, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As String
Public Function Separate(imageData() As UShort, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As String
Public Function Separate(imageData() As UInteger, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As String
Public Function SeparateAsync(inputFile As String, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As Task(Of String)
Public Function SeparateAsync(inputFiles As IEnumerable(Of String), chartFile As String, iniFile As String, options As ArbitraryChartOptions) As Task(Of String)
Public Function SeparateAsync(imageData() As Byte, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As Task(Of String)
Public Function SeparateAsync(imageData() As UShort, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As Task(Of String)
Public Function SeparateAsync(imageData() As UInteger, chartFile As String, iniFile As String, options As ArbitraryChartOptions) As Task(Of String)
Public Function SignalAverage(inputFiles As IEnumerable(Of String), chartFile As String, iniFile As String, options As ArbitraryChartOptions) As String
Public Function SignalAverageAsync(inputFiles As IEnumerable(Of String), chartFile As String, iniFile As String, options As ArbitraryChartOptions) As Task(Of String)

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:

{
    "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": {
...
    }
}

The Arbitrary Charts IT/EXE module has the following command-line interface

Usage: user_defined_charts.exe inputData chartFile iniFile averageMode optionsJsonFile
Positional arguments:
    inputData   the image file path
    chartFile   the chart definition file path
    iniFile     the Imatest INI file path
    averageMode  specify whether if groups of files are averaged (averageMode == 1) or not (averageMode == 0).
    optionsJsonFile  the file path to a JSON-encoded file that specifies the allowed options (see below)
    

The optionsJsonFile input corresponds to a JSON-encoded file with the following object properties:

To run the Arbitrary Charts module on a single image, as an example we can analyze using the sample image and chart definition file included with the C++ Arbitrary Charts sample. The image that is used in the sample has an sRGB encode. So we produce a JSON file that we arbitrarily name "options.json" and add the following contents

{
  "encoding": "sRGB"
}

We then run user_defined_charts.exe with

user_defined_charts.exe "C:Program FilesImatestv26.1ITsamplescpparbitrary_chartsP1858_combination_chart_example.jpg" "C:Program FilesImatestv26.1ITsamplescpparbitrary_chartsP1858_combination_variant.json" "C:Program FilesImatestv26.1ITsamplescppImatest_INIimatest-v2.ini" "0" "options.json"

JSON results are saved to %HOMEDRIVE%%HOMEPATH%Results by default.

The Arbitrary Charts IT/EXE module has the following command-line interface

Usage: user_defined_charts inputData chartFile iniFile averageMode optionsJsonFile
Positional arguments:
    inputData   the image file path
    chartFile   the chart definition file path
    iniFile     the Imatest INI file path
    averageMode  specify whether if groups of files are averaged (averageMode == 1) or not (averageMode == 0).
    optionsJsonFile  the file path to a JSON-encoded file that specifies the allowed options (see below)

The optionsJsonFile input corresponds to a JSON-encoded file with the following object properties:

To run the Arbitrary Charts module on a single image, as an example we can analyze using the sample image and chart definition file included with the Objective-C Arbitrary Charts sample provided for macOS, or the C++ Arbitrary Charts sample for Linux. The image that is used in the sample has an sRGB encode. So we produce a JSON file that we arbitrarily name "options.json" and add the following contents

{
  "encoding": "sRGB"
}

We then execute run_user_defined_charts.sh with

./run_user_defined_charts.sh "/Applications/Imatest/IT/v26.1/samples/images/P1858_combination_chart_example.jpg" "/Applications/Imatest/IT/v26.1/samples/images/P1858_combo_variant.json" "/Applications/Imatest/IT/v26.1/samples/Objective-C/Imatest_INI/imatest-v2.ini" "0" "options.json" 

JSON results are saved to $HOME/Results by default.

Coming soon ...

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

concentric_rings_shell(int nargout, mwArray& jsonManifest, const mwArray& imagePaths, const mwArray& iniFile);

Single Image Example

For the case of a single image, it is simpler to assign the imagePaths to an mwArray of type mxCHAR_CLASS, like the following

// iniFilePath is the file path for the Imatest INI file
mwArray iniFilePath("..\Imatest_INI\imatest-v2.ini");
mwArray imagePaths(".\concentric_rings_example.png");
mwArray jsonManifestFileList;
concentric_rings_shell(1, jsonManifestFileList, imagePaths, iniFilePath);

Multiple Images Example

For multiple images to be analyzed as a batch of separate images, the imagePaths parameter needs to be an mwArray of type mxCELL_CLASS, like as follows:

// iniFilePath is the file path for the Imatest INI file
mwArray iniFilePath("..\Imatest_INI\imatest-v2.ini");
mwArray imagePaths(1, 2, mxCELL_CLASS);
// The mwArray::Get() accessor uses a 1-based index with a prototype of the form
 // Get(num_indices, index1, ...)
imagePaths.Get(1, 1).Set(mwArray(".\concentric_rings_example_1.png"));
imagePaths.Get(1, 2).Set(mwArray(".\concentric_rings_example_2.png"));
mwArray jsonManifestFileList;
concentric_rings_shell(1, jsonManifestFileList, imagePaths, iniFilePath);

JSON Output

The jsonManifestFileList variable in the examples above contains a JSON encoded object with the following fields

{
    "summaryFiles": [
         // A list of file paths to the summary files for this run, which contain the results and settings used
     ],
    "plotFiles": [
        // A list of file paths to plots saved for this run.
    ]
}

Each file in "summaryFiles" is a JSON encoded object that includes results information as well as details of the analysis execution. The JSON object is as follows with "..." used to omit details for the sake of brevity.

{
  "concentric_ring": {
    "imatest": {
      ...
      "ini_file": {
        "filename": ...,
        "md5": ..."
      },
      ...
    },
    "inputs": {
      "image_file": {
        "filename": ...,
        "md5": ...
      },
      "settings": {
        ...
        }
      }
    },
    "results": {
      "regmark_data": {
        ...
      },
      "summary": {
        "fov": {
          ...
        },
        "field_angle": {
          ...
        }
      },
      "raw_data": {
        ...
      }
    }
  }
}

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

concentric_rings_shell(int nargout, mwArray& jsonManifest, const mwArray& imagePaths, const mwArray& iniFile);

Single Image Example

For the case of a single image, it is simpler to assign the imagePaths to an mwArray of type mxCHAR_CLASS, like the following:

NSString* samplesRootPath = [[[[@__FILE__ stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByDeletingLastPathComponent];
NSString* imageFolderPath = [[samplesRootPath stringByDeletingLastPathComponent] stringByAppendingPathComponent:@"images"];
NSString* iniFolderPath = [samplesRootPath stringByAppendingPathComponent:@"Imatest_INI"];
NSString* iniFilePath = [iniFolderPath stringByAppendingPathComponent:@"imatest-v2.ini"];
NSString* imageFilePath = [imageFolderPath stringByAppendingPathComponent:@"concentric_rings_example.png"];
// iniFile is the file path for the Imatest INI file
mwArray iniFileParam([iniFilePath cStringUsingEncoding:NSASCIIStringEncoding]);
// In the next example, we utilize the fileListInput parameter instead
mwArray imagePathsInput([imageFilePath cStringUsingEncoding:NSASCIIStringEncoding]);
mwArray jsonManifest;
concentric_rings_shell(1, jsonManifest, imagePathsInput, iniFileParam);

Multiple Images Example

For multiple images to be analyzed as a batch of separate images, the imagePaths parameter needs to be an mwArray of type mxCELL_CLASS, like as follows:

NSString* samplesRootPath = [[[[@__FILE__ stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByDeletingLastPathComponent];
NSString* imageFolderPath = [[samplesRootPath stringByDeletingLastPathComponent] stringByAppendingPathComponent:@"images"];
NSString* iniFolderPath = [samplesRootPath stringByAppendingPathComponent:@"Imatest_INI"];
NSString* iniFilePath = [iniFolderPath stringByAppendingPathComponent:@"imatest-v2.ini"];
NSString* imageFilePath1 = [imageFolderPath stringByAppendingPathComponent:@"concentric_rings_example_1.png"];
NSString* imageFilePath2 = [imageFolderPath stringByAppendingPathComponent:@"concentric_rings_example_2.png"];
// iniFile is the file path for the Imatest INI file
mwArray iniFileParam([iniFilePath cStringUsingEncoding:NSASCIIStringEncoding]);
// In the next example, we utilize the imagePathsInput parameter instead
mwArray imagePathsInput(1, 2, mxCELL_CLASS);
// The mwArray::Get() accessor uses a 1-based index with a prototype of the form
// Get(num_indices, index1, ...)
imagePathsInput.Get(1, 1).Set(mwArray([imageFilePath1 cStringUsingEncoding:NSASCIIStringEncoding]));
imagePathsInput.Get(1, 2).Set(mwArray([imageFilePath2 cStringUsingEncoding:NSASCIIStringEncoding]));
mwArray jsonManifest;
concentric_rings_shell(1, jsonManifest, imagePathsInput, iniFileParam);

JSON Output

The jsonManifestFileList variable in the examples above contains a JSON encoded object with the following fields

{
    "summaryFiles": [
         // A list of file paths to the summary files for this run, which contain the results and settings used
     ],
    "plotFiles": [
        // A list of file paths to plots saved for this run.
    ]
}

Each file in "summaryFiles" is a JSON encoded object that includes results information as well as details of the analysis execution. The JSON object is as follows with "..." used to omit details for the sake of brevity.

{
  "concentric_ring": {
    "imatest": {
      ...
      "ini_file": {
        "filename": ...,
        "md5": ..."
      },
      ...
    },
    "inputs": {
      "image_file": {
        "filename": ...,
        "md5": ...
      },
      "settings": {
        ...
        }
      }
    },
    "results": {
      "regmark_data": {
        ...
      },
      "summary": {
        "fov": {
          ...
        },
        "field_angle": {
          ...
        }
      },
      "raw_data": {
        ...
      }
    }
  }
}

Concentric Ring analysis is accomplished using one of the following overloaded methods in Imatest.IT.Library.ConcentricRings:

string JSON(string iniFilePath, string[] imageFilePaths)
string JSON(string iniFilePath, string imageFilePath)
async Task<string> JSONAsync(string iniFilePath, string[] imageFilePaths)
async Task<string> JSONAsync(string iniFilePath, string imageFilePath)

Example

Below is an example Concentric Rings analysis with exception handling details omitted with "..." for the sake of brevity.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using Imatest.IT;
namespace Imatest.IT.Samples.ConcentricRings
{
    class Program
    {
        /*
        * This code will execute the Imatest Concentric Rings function on the file
        * 'concentric_rings_example.png' which should be a capture of a concentric rings test chart.
        *
        * */
        public const string EXAMPLE_IMAGE = "concentric_rings_example.png";
        static void Main(string[] args)
        {
            using (Library lib = new Library())
            {
                try
                {
                    DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());
                    string rootDir = currentDirectory.Parent.Parent.Parent.FullName;
                    string iniFilePath = Path.Combine(rootDir, "imatest-v2.ini");
                    // C:Program FilesImatestv26.1ITsamplesimages
                    string sampleImagesDir = Path.Combine(currentDirectory.Parent.Parent.Parent.Parent.Parent.Parent.FullName, "images");
                    List<string> imagePaths = new List<string> {
                        Path.Combine(sampleImagesDir, EXAMPLE_IMAGE),
                    };
                    // Call Imatest IT library with JSON output
                    string jsonManifestFileList = lib.ConcentricRings.JSON(iniFilePath, imagePaths.ToArray());
                    Console.Out.WriteLine(result);
                }
                catch (Exception ex)
                {
                    ...
                }
            }
            Console.Out.WriteLine("Press enter to exit...");
            Console.In.Read();
        }
    }
}

JSON Output

The jsonManifestFileList variable in the examples above contains a JSON encoded object with the following fields

{
    "summaryFiles": [
         // A list of file paths to the summary files for this run, which contain the results and settings used
     ],
    "plotFiles": [
        // A list of file paths to plots saved for this run.
    ]
}

Each file in "summaryFiles" is a JSON encoded object that includes results information as well as details of the analysis execution. The JSON object is as follows with "..." used to omit details for the sake of brevity.

{
  "concentric_ring": {
    "imatest": {
      ...
      "ini_file": {
        "filename": ...,
        "md5": ..."
      },
      ...
    },
    "inputs": {
      "image_file": {
        "filename": ...,
        "md5": ...
      },
      "settings": {
        ...
        }
      }
    },
    "results": {
      "regmark_data": {
        ...
      },
      "summary": {
        "fov": {
          ...
        },
        "field_angle": {
          ...
        }
      },
      "raw_data": {
        ...
      }
    }
  }
}

Concentric Ring analysis is accomplished using one of the following overloaded methods in Imatest.IT.Library.ConcentricRings:

JSON(iniFilePath as String, imageFilePaths as String()) as String
string JSON(iniFilePath as String, string imageFilePath as String) as String
<Awaitable> JSONAsync(iniFilePath as String, string[] imageFilePaths) as Task(Of String)
<Awaitable> JSONAsync(iniFilePath as String, imageFilePath as String) as Task(Of String)

Example

Below is an example Concentric Rings analysis with exception handling details omitted with "…" for the sake of brevity.

Imports System.IO
Imports Imatest.IT
Module Program
    ' In this example program, the image files should be located
    ' in the same directory as this example script, and the 'imatest-v2.ini' file
    ' should be located in the "ini_file" directory in the Python samples directory.
    '
    ' Certain diagnostic lines are written to standard out for diag.
    '
    Public Const EXAMPLE_IMAGE As String = "concentric_rings_example.png"
    Public Sub Main()
        Using library = New Library()
            Try
                Dim currentDirectory As DirectoryInfo
                Dim rootDir As String
                Dim iniFilePath As String
                Dim sampleImagesDir As String
                Dim jsonManifestFileList As String
                Dim imagePaths(1) As String
                currentDirectory = New DirectoryInfo(Directory.GetCurrentDirectory())
                rootDir = currentDirectory.Parent.Parent.Parent.FullName
                iniFilePath = Path.Combine(rootDir, "imatest-v2.ini")
                ' C:Program FilesImatestv26.1ITsamplesimages
                sampleImagesDir = Path.Combine(currentDirectory.Parent.Parent.Parent.Parent.Parent.Parent.FullName, "images")
                imagePaths(0) = Path.Combine(sampleImagesDir, EXAMPLE_IMAGE)
                ' Call Imatest IT library with JSON output
                jsonManifestFileList = library.ConcentricRings.JSON(iniFilePath, imagePaths)
                Console.Out.WriteLine(result)
            Catch ex As Exception
                ...
            End Try
        End Using
        Console.Out.WriteLine("Press enter to exit...")
        Console.In.Read()
    End Sub
End Module

JSON Output

The jsonManifestFileList variable in the examples above contains a JSON encoded object with the following fields

{
    "summaryFiles": [
         // A list of file paths to the summary files for this run, which contain the results and settings used
     ],
    "plotFiles": [
        // A list of file paths to plots saved for this run.
    ]
}

Each file in "summaryFiles" is a JSON encoded object that includes results information as well as details of the analysis execution. The JSON object is as follows with "..." used to omit details for the sake of brevity.

{
  "concentric_ring": {
    "imatest": {
      ...
      "ini_file": {
        "filename": ...,
        "md5": ..."
      },
      ...
    },
    "inputs": {
      "image_file": {
        "filename": ...,
        "md5": ...
      },
      "settings": {
        ...
        }
      }
    },
    "results": {
      "regmark_data": {
        ...
      },
      "summary": {
        "fov": {
          ...
        },
        "field_angle": {
          ...
        }
      },
      "raw_data": {
        ...
      }
    }
  }
}

Concentric Rings IT/EXE has the following command line interface:

Concentric Rings IT/EXE
Usage: concentric_rings_exe [OPTIONS] ini-file image-paths...
Positionals:
  ini-file TEXT REQUIRED      The path to the Imatest INI file.
  image-paths TEXT ... REQUIRED
                              One or more image file paths 
Options:
  -h,--help                   Print this help message and exit
  -v,--version                Display program version information and exit
  --echo-result-manifest      After a successful run, echo the result manifest json to stdout.

Example

concentric_rings_exe "pathtoimatest-v2.ini" "anotherpathmy_image.jpg"

Concentric Rings IT/EXE has the following command line interface:

Concentric Rings IT/EXE
Usage: concentric_rings_exe [OPTIONS] ini-file image-paths...
Positionals:
  ini-file TEXT REQUIRED      The path to the Imatest INI file.
  image-paths TEXT ... REQUIRED
                              One or more image file paths 
Options:
  -h,--help                   Print this help message and exit
  -v,--version                Display program version information and exit
  --echo-result-manifest      After a successful run, echo the result manifest json to stdout.

Example

./run_concentric_rings_exe.sh "path/to/imatest-v2.ini"  "another/path/to/my_image.jpg"

Coming soon…

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

stray_light_shell(int nargout, mwArray& jsonManifest, const mwArray& iniFilePath, const mwArray& configInput, const mwArray& fileListInput)

The stray_light_shell() function has two mutually exclusive use cases:

• • Input only a list of file paths via the fileListInput parameter, with configInput left an empty mwArray. This is a simplified interface that provides the bare-minimum information for analysis: the image files.

• • Construct an imatest::stray_light::Config object and pass it in through the configInput parameter, which provides a means to input source field angles and azimuth angles associated with each input image file.

File list input example

In the example below, we set up a Stray Light analysis and supply only a list of files (see the Stray Light C++ sample for more details). Each file is assumed to be of a separate capture condition in this analysis.

// In the next example, we utilize the fileListInput parameter instead (and leave the ConfigInput parameter empty).
// iniFilePath is the file path for the Imatest INI file
mwArray iniFilePath("..\Imatest_INI\imatest-v2.ini");
mwArray fileListInput(4, 1, mxCELL_CLASS);
// The mwArray::Get() accessor uses a 1-based index with a prototype of the form
// Get(num_indices, index1, ...)
fileListInput.Get(1, 1).Set(mwArray(".\cap031_Az_90_Fa_0.png"));
fileListInput.Get(1, 2).Set(mwArray(".\cap039_Az_90_Fa_8.png"));
fileListInput.Get(1, 3).Set(mwArray(".\cap058_Az_90_Fa_27.png"));
fileListInput.Get(1, 4).Set(mwArray(".\cap061_Az_90_Fa_30.png"));
// Call the library function
mwArray jsonManifest;
stray_light_shell(1, jsonManifest, iniFilePath, mwArray(), fileListInput);

When stray_light_shell() completes, the results are returned in the jsonManifest mwArray as a JSON-encoded string. By default, this JSON object is structured as follows:

{
    "masks": [
        // ... file paths to saved masks ...
    ],
    "metric_images" : [
        // ... file paths to saved metric images ...
    ],
    "plots" : [
        // ... file paths to saved plots ...
    ],
    "videos" : [
        // ... file paths to saved videos ...
    ],
    "results" : [
        // ... file paths to saved results files ...
    ]
}

where each field in the JSON object contains an array of path strings.

Config input example

The next example (also borrowed from the Stray Light C++ sample) make use of the Config and CaptureConfig defined in the imatest::stray_light namespace (see StrayLightConfig.h/.cpp and StrayLightCaptureConfig.h/.cpp included in <IT install root>/libs/library/cpp).

using imatest::stray_light::Config;
using imatest::stray_light::CaptureConfig;
// iniFilePath is the file path for the Imatest INI file
mwArray iniFilePath("..\Imatest_INI\imatest-v2.ini");
// First we construct a imatest::stray_light::Config.
// In this example we have 4 images taken with the following capture conditions:
// ".\cap031_Az_90_Fa_0.png":
//    source field angle: 0 degrees
//    source azimuth angle: 90 degrees
// ".\cap039_Az_90_Fa_8.png":
//    source field angle: 8 degrees
//    source azimuth angle: 90 degrees
// ".\cap058_Az_90_Fa_27.png":
//    source field angle: 27 degrees
//    source azimuth angle: 90 degrees
// ".\cap061_Az_90_Fa_30.png":
//    source field angle: 30 degrees
//    source azimuth angle: 90 degrees
Config config;
config.runName = "Test run";
config.comment = "Test run within the Imatest IT sample for Stray Light";
config.captures.emplace_back(CaptureConfig({ ".\cap031_Az_90_Fa_0.png" }, 0, 90, "On-Axis"));
config.captures.emplace_back(CaptureConfig({ ".\cap039_Az_90_Fa_8.png" }, 8, 90, "Mid-Field"));
config.captures.emplace_back(CaptureConfig({ ".\cap058_Az_90_Fa_27.png" }, 27, 90, "Edge Of FOV"));
config.captures.emplace_back(CaptureConfig({ ".\cap061_Az_90_Fa_30.png" }, 30, 90, "Out Of FOV"));
mwArray configInput(config);
// Call the library function
mwArray jsonManifest;
stray_light_shell(1, jsonManifest, iniFilePath, configInput, mwArray());

with the results returned as JSON encoded string within the jsonManifest mwArray, as before.

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

stray_light_shell(int nargout, mwArray& jsonManifest, const mwArray& iniFilePath, const mwArray& configInput, const mwArray& fileListInput)

The stray_light_shell() function has two mutually exclusive use cases:

• • Input only a list of file paths via the fileListInput parameter, with configInput left an empty mwArray. This is a simplified interface that provides the bare-minimum information for analysis: the image files.

• • Construct an imatest::stray_light::Config object and pass it in through the configInput parameter, which provides a means to input source field angles and azimuth angles associated with each input image file.

File list input example

In the example below, we set up a Stray Light analysis and supply only a list of files (see the Stray Light Objective-C sample for more details). Each file is assumed to be of a separate capture condition in this analysis.

// In the next example, we utilize the fileListInput parameter instead (and leave the ConfigInput parameter empty).
NSString* samplesRootPath = [[[@__FILE__ stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByDeletingLastPathComponent];
NSString* imageFolderPath = [[samplesRootPath stringByDeletingLastPathComponent] stringByAppendingPathComponent:@"images"];
NSString* iniFolderPath = [samplesRootPath stringByAppendingPathComponent:@"Imatest_INI"];
NSString* iniFilePath = [iniFolderPath stringByAppendingPathComponent:@"imatest-v2.ini"];
NSString* imageFilePath1 = [imageFolderPath stringByAppendingPathComponent:@"cap031_Az_90_Fa_0.png"];
NSString* imageFilePath2 = [imageFolderPath stringByAppendingPathComponent:@"cap039_Az_90_Fa_8.png"];
NSString* imageFilePath3 = [imageFolderPath stringByAppendingPathComponent:@"cap058_Az_90_Fa_27.png"];
NSString* imageFilePath4 = [imageFolderPath stringByAppendingPathComponent:@"cap061_Az_90_Fa_30.png"];
// iniFile is the file path for the Imatest INI file
mwArray iniFileParam([iniFilePath cStringUsingEncoding:NSASCIIStringEncoding]);
mwArray fileListInput(4, 1, mxCELL_CLASS);
// The mwArray::Get() accessor uses a 1-based index with a prototype of the form
// Get(num_indices, index1, ...)
fileListInput.Get(1, 1).Set(mwArray([imageFilePath1 cStringUsingEncoding:NSASCIIStringEncoding]));
fileListInput.Get(1, 2).Set(mwArray([imageFilePath2 cStringUsingEncoding:NSASCIIStringEncoding]));
fileListInput.Get(1, 3).Set(mwArray([imageFilePath3 cStringUsingEncoding:NSASCIIStringEncoding]));
fileListInput.Get(1, 4).Set(mwArray([imageFilePath4 cStringUsingEncoding:NSASCIIStringEncoding]));
// Call the library function
mwArray jsonManifest;
stray_light_shell(1, jsonManifest, iniFilePath, mwArray(), fileListInput);

When stray_light_shell() completes, the results are returned in the jsonManifest mwArray as a JSON-encoded string. By default, this JSON object is structured as follows:

{
    "masks": [
        // ... file paths to saved masks ...
    ],
    "metric_images" : [
        // ... file paths to saved metric images ...
    ],
    "plots" : [
        // ... file paths to saved plots ...
    ],
    "videos" : [
        // ... file paths to saved videos ...
    ],
    "results" : [
        // ... file paths to saved results files ...
    ]
}

where each field in the JSON object contains an array of path strings.

Config input example

The next example (also borrowed from the Stray Light C++ sample) make use of the Config and CaptureConfig defined in the imatest::stray_light namespace (see StrayLightConfig.h/.cpp and StrayLightCaptureConfig.h/.cpp included in <IT install root>/libs/library/cpp).

NSString* samplesRootPath = [[[@__FILE__ stringByDeletingLastPathComponent] stringByDeletingLastPathComponent] stringByDeletingLastPathComponent];
NSString* imageFolderPath = [[samplesRootPath stringByDeletingLastPathComponent] stringByAppendingPathComponent:@"images"];
NSString* iniFolderPath = [samplesRootPath stringByAppendingPathComponent:@"Imatest_INI"];
NSString* iniFilePath = [iniFolderPath stringByAppendingPathComponent:@"imatest-v2.ini"]; NSString* imageFilePath1 = [imageFolderPath stringByAppendingPathComponent:@"cap031_Az_90_Fa_0.png"];
NSString* imageFilePath2 = [imageFolderPath stringByAppendingPathComponent:@"cap039_Az_90_Fa_8.png"];
NSString* imageFilePath3 = [imageFolderPath stringByAppendingPathComponent:@"cap058_Az_90_Fa_27.png"];
NSString* imageFilePath4 = [imageFolderPath stringByAppendingPathComponent:@"cap061_Az_90_Fa_30.png"];
// iniFile is the file path for the Imatest INI file
mwArray iniFileParam([iniFilePath cStringUsingEncoding:NSASCIIStringEncoding]);
// First we construct a imatest::stray_light::Config.
// In this example we have 4 images taken with the following capture conditions:
// "cap031_Az_90_Fa_0.png":
//    source field angle: 0 degrees
//    source azimuth angle: 90 degrees
// "cap039_Az_90_Fa_8.png":
//    source field angle: 8 degrees
//    source azimuth angle: 90 degrees
// "cap058_Az_90_Fa_27.png":
//    source field angle: 27 degrees
//    source azimuth angle: 90 degrees
// "cap061_Az_90_Fa_30.png":
//    source field angle: 30 degrees
//    source azimuth angle: 90 degrees
imatest::stray_light::Config config;
config.runName = "Test run";
config.comment = "Test run within the Imatest IT sample for Stray Light";
config.captures.emplace_back(imatest::stray_light::CaptureConfig({ [imageFilePath1 cStringUsingEncoding:NSASCIIStringEncoding] }, 0, 90, "On-Axis")); 
config.captures.emplace_back(imatest::stray_light::CaptureConfig({ [imageFilePath2 cStringUsingEncoding:NSASCIIStringEncoding] }, 8, 90, "Mid-Field")); 
config.captures.emplace_back(imatest::stray_light::CaptureConfig({ [imageFilePath3 cStringUsingEncoding:NSASCIIStringEncoding] }, 27, 90, "Edge Of FOV")); 
config.captures.emplace_back(imatest::stray_light::CaptureConfig({ [imageFilePath4 cStringUsingEncoding:NSASCIIStringEncoding] }, 30, 90, "Out Of FOV")); 
mwArray configInputParam(config); // Call the library function 
mwArray jsonManifest; 
stray_light_shell(1, jsonManifest, iniFileParam, configInputParam, mwArray());

with the results returned as JSON encoded string within the jsonManifest mwArray, as before.

Stray light analysis can proceed a few different ways depending on what additional testing condition data is available.

• • Input only a list of file paths via the fileList input parameter. This is a simplified interface that provides the bare-minimum information for analysis: the image files.

• • Construct an StrayLightConfig object and pass it in through the config input parameter, which provides a means to input source field angles and azimuth angles associated with each input image file.

• • Provide a file path to a serialized StrayLightConfig (i.e. a JSON-encoded file with the extension *.slconf).

The StrayLightConfig class has the following properties:

, where the StrayLightCaptureConfig class has the properties

Depending on the input data source, analysis can then proceed via one of the overloaded methods in the Imatest.IT.Library.StrayLight library methods:

string Batch(string iniFilePath, StrayLightConfig config)
async Task<string> BatchAsync(string iniFilePath, StrayLightConfig config)
string Batch(string iniFilePath, string configFilePath)
async Task<string> BatchAsync(string iniFilePath, string configFilePath)
string Batch(string iniFilePath, String[] fileList)
async Task<string> BatchAsync(string iniFilePath, String[] fileList)

To demonstrate the functionality, below we walk through an example (which is largely identical to the example installed at <IT install root>/samples/.NET/C#/StrayLight, but with details omitted with ... for brevity). To set up the analysis we initiate an Imatest.IT.Library instance and define the Imatest INI and image file paths.

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.IO;
using System.Runtime.Serialization.Json;
using System.Threading.Tasks;
using MathWorks.MATLAB.NET.Arrays;
using Imatest.IT;
class Program
{
    public const string EXAMPLE_IMAGE_1 = "cap031_Az_90_Fa_0.png";
    public const string EXAMPLE_IMAGE_2 = "cap039_Az_90_Fa_8.png";
    public const string EXAMPLE_IMAGE_3 = "cap058_Az_90_Fa_27.png";
    public const string EXAMPLE_IMAGE_4 = "cap061_Az_90_Fa_30.png";
    static void Main(string[] args)
    {
        using (Library lib = new Library())
        {
            try
            {
                DirectoryInfo currentDirectory = new DirectoryInfo(Directory.GetCurrentDirectory());
                string rootDir = ... ;
                string iniFilePath = Path.Combine(rootDir, "imatest-v2.ini");
                string sampleImagesDir = ... ;
                List<string> imagePaths = new List<string> {
                    Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_1),
                    Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_2),
                    Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_3),
                    Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_4)
                };

next we construct a List<StrayLightCaptureConfig> from the image file paths

                List<StrayLightCaptureConfig> captureConfigs = new List<StrayLightCaptureConfig>();
                foreach (string imagePath in imagePaths) {
                    captureConfigs.Add(new StrayLightCaptureConfig(new List<string> { imagePath }));
                } 

and then construct a StrayLightConfig instance from the List<StrayLightCaptureConfig>.

                StrayLightConfig config = new StrayLightConfig(captureConfigs);  

Lastly we supply the StrayLightConfig instance and the INI file path to Imatest.IT.StrayLight.Batch() and execute

                // Call Imatest IT library with JSON output
                string result = lib.StrayLight.Batch(iniFilePath, config);
                Console.Out.WriteLine(result);
            }
            catch (Exception ex)
            {
                ...
            }
        }
       }
}

Imatest.IT.StrayLight.Batch() will return a JSON-encoded string of the form

{
    "masks": [
        // ... file paths to saved masks ...
    ],
    "metric_images" : [
        // ... file paths to saved metric images ...
    ],
    "plots" : [
        // ... file paths to saved plots ...
    ],
    "videos" : [
        // ... file paths to saved videos ...
    ],
    "results" : [
        // ... file paths to saved results files ...
    ]
}

which lists the file paths of any file produced by the analysis.

Stray light analysis can proceed a few different ways depending on what additional testing condition data is available.

• • Input only a list of file paths via the fileList input parameter. This is a simplified interface that provides the bare-minimum information for analysis: the image files.

• • Construct an StrayLightConfig object and pass it in through the config input parameter, which provides a means to input source field angles and azimuth angles associated with each input image file.

• • Provide a file path to a serialized StrayLightConfig (i.e. a JSON-encoded file with the extension *.slconf).

The StrayLightConfig class has the following properties:

, where the StrayLightCaptureConfig class has the properties

Depending on the input data source, analysis can then proceed via one of the overloaded methods in the Imatest.IT.Library.StrayLight library methods:

Public Function Batch(iniFilePath as String, config as StrayLightConfig) as  String
Public Function BatchAsync(iniFilePath as String, config as StrayLightConfig) As Task(Of String) 
Public Function Batch(iniFilePath as String, configFilePath as String) as String
Public Function BatchAsync(iniFilePath as String, configFilePath as String) As Task(Of String)
Public Function Batch(string iniFilePath, fileList as String()) as String
Public Function BatchAsync(iniFilePath as String, fileList as String()) As Task(Of String)

To demonstrate the functionality, below we walk through an example (which is largely identical to the example installed at <IT install root>/samples/.NET/VB.NET/StrayLight, but with details omitted with ... for brevity). To set up the analysis we initiate an Imatest.IT.Library instance, declare needed variables, and define the Imatest INI and image file paths.

Imports System.IO
Imports Imatest.IT
Module Program
    Public Const EXAMPLE_IMAGE_1 As String = "cap031_Az_90_Fa_0.png"
    Public Const EXAMPLE_IMAGE_2 As String = "cap039_Az_90_Fa_8.png"
    Public Const EXAMPLE_IMAGE_3 As String = "cap058_Az_90_Fa_27.png"
    Public Const EXAMPLE_IMAGE_4 As String = "cap061_Az_90_Fa_30.png"
    Public Sub Main()
        Using library = New Library()
            Try
                Dim currentDirectory As DirectoryInfo
                Dim rootDir As String
                Dim iniFilePath As String
                Dim sampleImagesDir As String
                Dim result As String
                Dim captureConfigs(3) As StrayLightCaptureConfig
                Dim captureConfig As StrayLightConfig
                rootDir = ...
                iniFilePath = Path.Combine(rootDir, "imatest-v2.ini")
                sampleImagesDir = ...

next we construct the StrayLightCaptureConfig array from the image file paths

                captureConfigs(0) = New StrayLightCaptureConfig(New String() {Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_1)})
                captureConfigs(1) = New StrayLightCaptureConfig(New String() {Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_2)})
                captureConfigs(2) = New StrayLightCaptureConfig(New String() {Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_3)})
                captureConfigs(3) = New StrayLightCaptureConfig(New String() {Path.Combine(sampleImagesDir, EXAMPLE_IMAGE_4)})

and then construct a StrayLightConfig instance from the List<StrayLightCaptureConfig>.

                captureConfig = New StrayLightConfig(captureConfigs)

Lastly we supply the StrayLightConfig instance and the INI file path to Imatest.IT.StrayLight.Batch() and execute

                ' Call Imatest IT library with JSON output without Stray Light Config values
                result = library.StrayLight.Batch(iniFilePath, captureConfig)
            Catch ex As Exception
                ...
            End Try
        End Using
    End Sub
End Module

Imatest.IT.StrayLight.Batch() will return a JSON-encoded string of the form

{
    "masks": [
        // ... file paths to saved masks ...
    ],
    "metric_images" : [
        // ... file paths to saved metric images ...
    ],
    "plots" : [
        // ... file paths to saved plots ...
    ],
    "videos" : [
        // ... file paths to saved videos ...
    ],
    "results" : [
        // ... file paths to saved results files ...
    ]
}

which lists the file paths of any file produced by the analysis.

The Stray Light IT/EXE module has the following command-line interface

 stray_light_exe --help
Usage: stray_light_exe [--echo-result-manifest] [--help] iniFilePath [configFilePath] [imageFileList] 
Analyze stray light images via the stray light module
Positional arguments:
	iniFilePath   		The full path to the INI file.
	configFilePath		The full path to the analysis config file.
	imageFileList 		The full path to all image files to analyze.
Options:
	--echo-result-manifest		After a successful run, echo the result manifest json to stdout.
	-h, --help            		Display this help information.

The Stray Light IT/EXE interface has two mutually exclusive use cases:

• • Input only a list of file paths via the imageFileList parameter, with configFilePath left an empty string. This is a simplified interface that provides the bare-minimum information for analysis: the image files.

• • Supply a file path to an *.slconf file, which provides a means to input source field angles and azimuth angles associated with each input image file. *.slconf are a JSON encoded file that can be generated from a StrayLightConfig object in the IT/Python interface, or the equivalent class in the C++, C# or VB.NET interfaces. This *.slconf file provides more information to the Stray Light module and thus a richer analysis.

To execute stray_light_shell.exe, supply the require filed paths as below

stray_light_exe.exe "imatest-v2.ini" "my_capture.slconf"

The Stray Light IT/EXE module has the following command-line interface

 stray_light_exe --help
Usage: stray_light_exe [--echo-result-manifest] [--help] iniFilePath [configFilePath] [imageFileList] 
Analyze stray light images via the stray light module
Positional arguments:
	iniFilePath   		The full path to the INI file.
	configFilePath		The full path to the analysis config file.
	imageFileList 		The full path to all image files to analyze.
Options:
	--echo-result-manifest		After a successful run, echo the result manifest json to stdout.
	-h, --help            		Display this help information.

The Stray Light IT/EXE interface has two mutually exclusive use cases:

• • Input only a list of file paths via the imageFileList parameter, with configFilePath left an empty string. This is a simplified interface that provides the bare-minimum information for analysis: the image files.

• • Supply a file path to an *.slconf file, which provides a means to input source field angles and azimuth angles associated with each input image file. *.slconf are a JSON encoded file that can be generated from a StrayLightConfig object in the IT/Python interface, or the equivalent class in the C++, C# or VB.NET interfaces. This *.slconf file provides more information to the Stray Light module and thus a richer analysis.

To execute stray_light_shell.exe, supply the require filed paths as below

./run_stray_light_exe.sh "imatest-v2.ini" "my_capture.slconf"