Documentation

Imatest IS Push Interface

The Imatest IS Push Interface is a library that allows developers to access the image quality analysis routines available in Imatest IS via function calls that push images to various modules within Imatest IS. This library is made available in the form of a C++ Dynamic Link Library (DLL) that is currently only available for 32-bit Windows. With functions in this library, the developer can start up the GUI of Imatest IS 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 IS 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 IS and have the same analysis modules display, and the same calculations, as in the stand-alone version of Imatest IS. The following modules can be addressed by the Push Interface:

Multicharts Blemish Random/Dead leaves
Multitest Uniformity Wedge
Rescharts Uniformity Interactive Dot
SFR ColorCheck Log F-Contrast
SFRplus Auto Stepchart Star
SFRplus Setup Distortion  

The Imatest IS Push Interface is included in the installation of Imatest IS 4.0. The relevant files for the Push Interface are located in the /push_interface sub-folder within the Imatest IS 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 IS 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 IS Push Interface

The Imatest IS Push Interface consists of two libraries

  imatest_is_library contains Imatest IS library functions
  IS_push_mode_interface contains Push Interface functions

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

Note that the IS_push_mode_interface library was built statically linked to the imatest_is_library and thus a header file is only needed for IS_push_mode_interface library. The functions in the imatest_is_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 IS install folder>\push_interface\libs\cpp folder. For questions about function definitions inside of the header file, please write support@imatest.com.

MATLAB and Image Files:

Imatest IS also comes with the Matlab Compiler Runtime Libraries v8.1. 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 IS Push Interface

  1. If not already installed, install the Matlab Compiler Runtime v8.1, which can be downloaded from Mathworks.
  2. Have the IS_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>\extern\include and library path <MCR root>\extern\lib\win32\microsoft.
  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 IS 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.
init_imatest(void) This function initializes the Matlab Compiler Runtime (MCR) and Imatest IS libraries as well as supplying the first image.
start_imatest(uint8_t* image, size_t imageRows, size_t imageCols, size_t imageColors, eTestID_t testID, eChartID_t chartID, int specialGrayID, int numRows, int numCols) This function starts Imatest IS, which will then analyze the first image.
push_imatest(eCommand_t command, uint8_t* image, size_t imageRows, size_t imageCols, size_t imageColors, eTestID_t testID, eChartID_t chartID, int specialGrayID, int numRows, int numCols) This function allows subsequent images and test commands to be sent.
stop_imatest(void) This function stops Imatest IS after all queued commands have been dealt with.
terminate_imatest(void) This function terminates the MCR and Imatest IS libraries.

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.

Table of parameter specifications

eCommand_t command An enum of type eCommand_t that indicates what type of operation to perform, e.g. eCommand_reload_image_only
uint8_t* image A uint8_t* pointer to an image in a column-major, planar-format RGB array
size_t imageRows The number of rows in the image.
size_t imageCols The number of columns in the image.
size_t imageColors The number of colors in the image.
eTestID_t testID An eTestID_t enum that indicates the what test or module to load, e.g. Multicharts.
eChartID_t chartID An eChartID_t that indicates what chart the image is of, e.g. eMulticharts_ColorChecker_24
eMultitest_special_gray_t specialGrayID An eMultitest_special_gray_t enum that indicates which specific Special Gray chart in Multitest used only with eMultitest_Special_Grayscale. If unused set to an arbitrary integer value.
int numRows The number of rows for the general m x n chart used only in conjunction with testID = eMultitest_Special_Grayscale and chartID = eMultitest_special_gray_general. If unused set to an arbitrary integer value.
int numCols The number of columns for the general m x n chart used only in conjunction with testID = eMultitest_Special_Grayscale and chartID = eMultitest_special_gray_general. If unused set to an arbitrary integer value.

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 IS 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 IS. When eCommand_reload_image_only is sent, Imatest IS 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.

eCommand_t

eCommand_load_new_test_and_image=1 Causes Imatest to close the current module (e.g. Multicharts) and load a new module with the supplied image.
eCommand_load_new_test_only Causes Imatest to close the current module and load a module with the existing image.
eCommand_load_new_image_only Causes Imatest to load a new image within the existing module – reopens region selection
eCommand_reload_image_only Cause Imatest to reload the image within the existing module – does not open region selection

 

eTestID_t

The eTestID_t data-type delineates the Imatest IS 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.

eTestID_t

eTestID_sfr = 1 Addresses the SFR button
eTestID_sfrplus_auto Addresses the SFRplus Auto button
eTestID_sfrplus_setup Addresses the SFRplus Setup button
eTestID_rescharts Addresses the Rescharts button
eTestID_colorcheck Addresses the Colorcheck button
eTestID_stepchart Addresses the Stepchart button
eTestID_random Addresses the Random/Dead leaves button
eTestID_star Addresses the Star button
eTestID_logfc Addresses the Log F-Contrast button
eTestID_wedge Addresses the Wedge button
eTestID_multitest Addresses the Multitest button
eTestID_uniformity Addresses the Uniformity button
eTestID_blemish Addresses the Blemish button
eTestID_uniformity_int Addresses the Uniformity Interactive button
eTestID_multicharts Addresses the Multicharts button
eTestID_distortion Addresses the Distortion button
eTestID_dot Addresses the Dot button
eTestID_none A place-holder

 

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.

eChartID_t

eChartID_none For use when the module does not require a chart ID (All except Multicharts, Multitest, Rescharts, and SFRplus Setup)
eMulticharts_ColorChecker_24 Multicharts: X-Rite ColorChecker (24 patch)
eMulticharts_IT8_7 Multicharts: IT8.7.
eMulticharts_DigitaL_TargeT Multicharts: CMP 003.
eMulticharts_QPcard Multicharts: QPcard 201.
eMulticharts_ColorChecker_SG Multicharts: X-Rite ColorChecker SG.
eMulticharts_Grayscale_Stepchart Multicharts: Grayscale Stepchart (linear)
eMulticharts_Special_Grayscale Multicharts: Special Grayscale Stepcharts.
eMulticharts_ChromaDuMonde_28 Multicharts: DSClabs ChromaDuMonde 28.
eMulticharts_SFRplus_20_patch_color Multicharts: SFRplus 20-patch color.
eMulticharts_UTT Multicharts: Universal Test Target (UTT) 9×3 Color.
eMulticharts_SpyderCHECKR Multicharts: SpyderCHECKR 8×6
eMulticharts_SMPTE Multicharts: SMPTE/Hale Color Bars (6 patches)
eMulticharts_TE226 Multicharts: TE226 HDTV 9×5 chart.
eMulticharts_General Multicharts: General m rows x n columns.
eMulticharts_DreamCatcher_48 Multicharts: DSClabs DreamCatcher 48.
eMulticharts_ColorGauge_6x5 Multicharts: ColorGauge 6×5
eMulticharts_Rez_Checker Multicharts: ColorGauge Rez-Checker 6Wx7H
eMultitest_ColorChecker_24 Multitest: X-Rite ColorChecker (24 patch)
eMultitest_IT8_7 Multitest: IT8.7.
eMultitest_ISO_14524 Multitest: ISO-14524 (last grayscale)
eMultitest_QPcard Multitest: QPcard 201.
eMultitest_ColorChecker_SG Multitest: X-Rite ColorChecker SG.
eMultitest_Grayscale_Stepchart Multitest: Grayscale Stepchart (linear)
eMultitest_Special_Grayscale Multitest: Special Grayscale Stepcharts.
eMultitest_ChromaDuMonde_28 Multitest: DSClabs ChromaDuMonde 28.
eMultitest_SFRplus_20_patch_color Multitest: SFRplus 20-patch color.
eMultitest_UTT Multitest: Universal Test Target (UTT) 9×3 Color.
eMultitest_SpyderCHECKR Multitest: SpyderCHECKR 8×6
eMultitest_SMPTE Multitest: SMPTE/Hale Color Bars (6 patches)
eMultitest_TE226 Multitest: TE226 HDTV 9×5 chart.
eMultitest_General Multitest: General m rows x n columns.
eMultitest_DreamCatcher_48 Multitest: DSClabs DreamCatcher 48.
eMultitest_ColorGauge_6x5 Multitest: ColorGauge 6×5
eMultitest_Rez_Checker Multitest: ColorGauge Rez-Checker 6Wx7H
eMultitest_DigitaL_TargeT Multitest: CMP 003.
eRescharts_SFR Rescharts: SFR chart.
eRescharts_SFRplus Rescharts: SFRplus chart.
eRescharts_Log_Frequency Rescharts: Log frequency chart.
eRescharts_Log_F_contrast Rescharts: Log-f contrast chart.
eRescharts_Star_chart Rescharts: Siemens Star chart.
eRescharts_Wedge_pattern Rescharts: Wedge pattern chart.
eRescharts_Random_Dead_Leaves Rescharts: Random/Dead leaves chart.
eRescharts_Focus_Score Rescharts: Focus score chart.
eSFRplus_Setup_SFR SFRplus Setup: SFR chart.
eSFRplus_Setup_SFRplus SFRplus Setup: SFRplus chart.
eSFRplus_Setup_Log_Frequency SFRplus Setup: Log frequency chart.
eSFRplus_Setup_Log_F_contrast SFRplus Setup: Log-f contrast chart.
eSFRplus_Setup_Star_chart SFRplus Setup: Siemens Star chart.
eSFRplus_Setup_Wedge_pattern SFRplus Setup: Wedge pattern chart.
eSFRplus_Setup_Random_Dead_Leaves SFRplus Setup: Random/Dead leaves chart.
eSFRplus_Setup_Focus_Score SFRplus Setup: Focus score chart.

 

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.

eMultitest_special_gray_t

eMultitest_special_gray_ISO_14524 = 1 ISO-14524 (OECF 12-patch circular) chart
eMultitest_special_gray_QA_61 QA-61 (square pattern) chart
eMultitest_special_gray_QA_62 QA-62 (square pattern) chart
eMultitest_special_gray_ISO_15739 ISO-15739 chart
eMultitest_special_gray_ITE ITE Grayscale chart
eMultitest_special_gray_OECF_20 OECF 20-patch circular chart
eMultitest_special_gray_circle Squares arranged in a circle chart
eMultitest_special_gray_ST_51 EIA Grayscale (ST-51) chart
eMultitest_special_gray_QA_79 QA-79 chart
eMultitest_special_gray_general General mxn (m rows x n columns) chart
eMultitest_special_gray_Imatest_Dynamic Imatest 36-patch Dynamic range chart

 

Examples

 

Included in the installation of Imatest IS 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.