Imatest Push Interface

The Imatest Push Interface is a library that allows developers to access the image quality analysis routines available in Imatest via function calls that push images to various modules within Imatest. This library is made available in the form of a C++ Dynamic Link Library (DLL) that is available in Imatest Master. With functions in this library, the developer can start up the GUI of Imatest and push images to modules of their choosing and then Imatest will launch the corresponding module dialogs to begin analysis. In essence, the end-user will see the same GUI as if they had started Imatest themselves, but the developer will have the control to initiate tests programmatically.

With the Push Interface, the developer can push single images at a time to Imatest and have the same analysis modules display, and the same calculations, as in the stand-alone version of Imatest. The following modules can be addressed by the Push Interface:

The Imatest Push Interface is included in the installation of Imatest Master 5.0 and IS 4.0-5.0. The relevant files for the Push Interface are located in the /push_interface sub-folder within the Imatest installation folder. Included in the /push_interface folder are the library and header files, a sample Visual Studio 2008 C++ sample project, and documentation of the library function and enumerated data-type definitions.

Features

• Interface layer has only simple data-types as input parameters
• Shares the same *.ini configuration file as the stand-alone executable
• Can push individual planar, RGB images to Imatest for analysis by any module
• Can refresh an image in an existing module, which bypasses region selection
• Can open and close Imatest
• Push images to Multicharts, Rescharts, SFRplus Setup, Multitest, and other modules

Installing the Imatest Push Interface

The Imatest Push Interface consists of two libraries

The functions needed for operating the Push Interface are housed in the Master_push_mode_interface library. The Master_push_mode_interface library contains functions that generate the various data structures needed to communicate with Imatest through internal calls to functions in the imatest_is_library.

Note that the Master_push_mode_interface library was built statically linked to the imatest_push_mode_library and thus a header file is only needed for Master_push_mode_interface library. The functions in the imatest_push_mode_library should not be invoked directly.

C++ Header and Source DLL Files:

Imatest IS includes C++ header and source files that you can use to link to Push Interface functions. Header files contain function definitions, enum definitions, and the corresponding function in the source file is used to link into the Imatest function that lives inside of the IS_push_mode_interface.dll file. The C++ libraries and corresponding files are located in the <Imatest  install folder>push_interfacelibscpp folder. For questions about function definitions inside of the header file, please write [email protected].

MATLAB and Image Files:

Imatest  also comes with the Matlab Compiler Runtime Libraries v9.2. More information can be found at the MathWorks website. The package also contains image files, which are placed on Imatest generated graphics and dialogs. The /images folder should be placed in the run time directory of your program to avoid errors when trying to display Imatest generated graphics. Additionally, some images used by the sample project are in the /push_interface_sample_projects/Data folder.

How to build an executable that utilizes the Imatest Push Interface

1. If not already installed, install the Matlab Compiler Runtime v9.2, which can be downloaded from Mathworks.
2. Have the Master_push_mode_interface.h and push_mode_IDs.h in the project directory.
3. Update your project with the correct include path to <MCR root>externinclude and library path <MCR root>externlibwin64microsoft.
4. Build your project.

Note that the Imatest *.dlls and the /image folder must be in the same directory from which you run your project.

Function prototypes and definitions

The Imatest IS Push Interface is initialized by calling it from within your C++ program. The initialization steps are the following:

1. Declare and initialize all variables.
2. Call init_imatest() to initialize the library functions and Matlab Compiler Runtime (MCR).
3. Call start_imatest() supplying the image, test, and chart data and an instance of Imatest will start and analyze the image.
4. Call push_imatest()to push single, new images for analysis in a specified module. Repeat as needed when the image is updated in your program and needs to be reanalyzed.
5. Call stop_imatest() to close Imatest IS.
6. Call terminate_imatest() to terminate the Imatest IS libraries and the MCR.
7. Clean up variables,close files and other resources, and exit.

Note that init_imatest() and terminate_imatest() can be called only once per process.
After terminate_imatest() is called none of the library functions can be called for the duration of the process.

The various parameters in the library functions are defined in the table below. All parameters are simple data types, with the various enumerated data types defined for convenience. The parameter command dictates what type of operation to perform (e.g refresh an existing module with a new image or open a new module to analyze the supplied image). The image is supplied by a pointer to unsigned 8-bit data, image, where the data must be column-major, planar-format RGB ( i.e. [R11 R21 R31 .. Rm1 R12 ... Rmn G11 G21 G31..Gm1 G12 ... Gmn B11 B21 B31 ... Bm1 B12 ... Bmn] where Xij denotes color 'X' at row i, column j.). The number of rows, columns, and colors in the image are supplied in the parameters imageRows, imageCols, andimageColors, respectively.

The module that Imatest opens is dictated by the testID parameter. The chart captured in the image is indicated by the value of chartID, and in special cases where any of the 'special gray charts' are used (Multitest and Multicharts only), additionally by specialGrayID. In the special case where a 'General m x n ' grayscale chart was used, the numRows and numCols must be supplied with the number of rows and columns of grayscale patches. If the value of chartIDdoes not equal either of the special grayscale values, then the values of specialGrayID, numRows, and numCols are ignored.

Enumerated data-type specifications

The various enumerated data-types outlined below are defined in the included file push_mode_IDs.h.

eCommand_t

The eCommand_t is an enumerated data-type that list the allowed commands. With the exception of eCommand_reload_image_only, the commands will cause Imatest to close the existing module window and open a new module window. The eCommand_reload_image_only command is meant for situations where the location and geometry of the chart within the image has not changed compared to the previous image supplied to Imatest. When eCommand_reload_image_only is sent, Imatest skips the standard region selection window assuming that all the regions are in the same locations in the new image. For example, if in your program the user is changing the color balance of an image that has already been analyzed by Imatest and then wishes to run the analysis on the modified image, then eCommand_reload_image_only would be appropriate. If the modified image has been cropped or otherwise distorted, then eCommand_load_new_image_only would be appropriate. However, if the new image requires a different analysis module, then the eCommand_load_new_test_and_image command would be appropriate.

eTestID_t

The eTestID_t data-type delineates the Imatest modules that can be addressed by the Push Interface. Issuing a given eTestID_t value will cause Imatest to open the corresponding module dialog. This operation akin to the user pressing the corresponding button on the main window and supplying the image under test.

Note that the value of the parameter testID must be accompanied by a congruent value for chartID.

eChartID_t

The eChartID_t type enumerates the allowed charts for Imatest. For Multicharts, Multitest, Rescharts, and SFRplus Setup, a specific chart identifier must be supplied, but for all others that are specialized to a specific chart (e.g. Wedge, Star, etc.) the value eChartID_none should be supplied.

eMultitest_special_gray_t

The eMultitest_special_gray_tenumeration delineates the special grayscale charts that are available in Multitest and Multicharts.

Note that a value from this enum must be accompanied by chartID = eMultitest_Special_Grayscale (or eMulticharts_Special_Grayscale ), otherwise it will be ignored by Imatest. Furthermore, if eMultitest_special_gray_Imatest_Dynamicis used, then the numRowsand numColsinput parameters must be specified.

Examples

Included in the installation of Imatest is a sample Visual Studio 2008 C++ project that demonstrates some of the functionality of the Push Interface using the supplied Imatest DLLs. Specifically it demonstrates loading an image into Multicharts, refreshing the Multicharts dialog with a new image, and then closing Multicharts and opening SFRplus Setup to analyze another image.