Documentation – Previous v5.2

Imatest Push Interface

Current Documentation
View previous documentation
View legacy documentation
All documentation versions

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:

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

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.


  • 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 Color/Tone Interactive, Rescharts, SFRplus Setup, Color/Tone Auto, and other modules


Installing the Imatest Push Interface

The Imatest Push Interface consists of two libraries

  imatest_push_mode_library contains Imatest library functions
  Master_push_mode_interface contains Push Interface functions

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_interface\libs\cpp folder. For questions about function definitions inside of the header file, please write

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>\extern\include and library path <MCR root>\extern\lib\win64\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 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 (Color/Tone 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. Color/Tone Interactive.
eChartID_t chartID An eChartID_t that indicates what chart the image is of, e.g. eColor_Tone_Interactive_ColorChecker_24
eColor_Tone Auto_special_gray_t specialGrayID An eColor_Tone Auto_special_gray_t enum that indicates which specific Special Gray chart in Color/Tone used only with eColor_Tone_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 = eColor_Tone_Special_Grayscale and chartID = eColor_Tone_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 = eColor_Tone_Special_Grayscale and chartID = eColor_Tone_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.


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.


eCommand_load_new_test_and_image=1 Causes Imatest to close the current module (e.g. Color/Tone Interactive) 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



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.


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_color_tone Addresses the Color/Tone 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 Color/Tone Interactive button
eTestID_distortion Addresses the Distortion button
eTestID_dot Addresses the Dot button
eTestID_none A place-holder



The eChartID_t type enumerates the allowed charts for Imatest. For Color/Tone, 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_none For use when the module does not require a chart ID (All except Color/Tone, Rescharts, and SFRplus Setup)
eColor_Tone_Interactive_ColorChecker_24 Color/Tone Interactive: X-Rite ColorChecker (24 patch)
eColor_Tone_Interactive_IT8_7 Color/Tone Interactive: IT8.7.
eColor_Tone_Interactive_DigitaL_TargeT Color/Tone Interactive: CMP 003.
eColor_Tone_Interactive_QPcard Color/Tone Interactive: QPcard 201.
eColor_Tone_Interactive_ColorChecker_SG Color/Tone Interactive: X-Rite ColorChecker SG.
eColor_Tone_Interactive_Grayscale_Stepchart Color/Tone Interactive: Grayscale Stepchart (linear)
eColor_Tone_Interactive_Special_Grayscale Color/Tone Interactive: Special Grayscale Stepcharts.
eColor_Tone_Interactive_ChromaDuMonde_28 Color/Tone Interactive: DSClabs ChromaDuMonde 28.
eColor_Tone_Interactive_SFRplus_20_patch_color Color/Tone Interactive: SFRplus 20-patch color.
eColor_Tone_Interactive_UTT Color/Tone Interactive: Universal Test Target (UTT) 9×3 Color.
eColor_Tone_Interactive_SpyderCHECKR Color/Tone Interactive: SpyderCHECKR 8×6
eColor_Tone_Interactive_SMPTE Color/Tone Interactive: SMPTE/Hale Color Bars (6 patches)
eColor_Tone_Interactive_TE226 Color/Tone Interactive: TE226 HDTV 9×5 chart.
eColor_Tone_Interactive_General Color/Tone Interactive: General m rows x n columns.
eColor_Tone_Interactive_DreamCatcher_48 Color/Tone Interactive: DSClabs DreamCatcher 48.
eColor_Tone_Interactive_ColorGauge_6x5 Color/Tone Interactive: ColorGauge 6×5
eColor_Tone_Interactive_Rez_Checker Color/Tone Interactive: ColorGauge Rez-Checker 6Wx7H
eColor_Tone_ColorChecker_24 Color/Tone Auto: X-Rite ColorChecker (24 patch)
eColor_Tone_IT8_7 Color/Tone Auto: IT8.7.
eColor_Tone_ISO_14524 Color/Tone Auto: ISO-14524 (last grayscale)
eColor_Tone_QPcard Color/Tone Auto: QPcard 201.
eColor_Tone_ColorChecker_SG Color/Tone Auto: X-Rite ColorChecker SG.
eColor_Tone_Grayscale_Stepchart Color/Tone Auto: Grayscale Stepchart (linear)
eColor_Tone_Special_Grayscale Color/Tone Auto: Special Grayscale Stepcharts.
eColor_Tone_ChromaDuMonde_28 Color/Tone Auto: DSClabs ChromaDuMonde 28.
eColor_Tone_SFRplus_20_patch_color Color/Tone Auto: SFRplus 20-patch color.
eColor_Tone_UTT Color/Tone Auto: Universal Test Target (UTT) 9×3 Color.
eColor_Tone_SpyderCHECKR Color/Tone Auto: SpyderCHECKR 8×6
eColor_Tone_SMPTE Color/Tone Auto: SMPTE/Hale Color Bars (6 patches)
eColor_Tone_TE226 Color/Tone Auto: TE226 HDTV 9×5 chart.
eColor_Tone_General Color/Tone Auto: General m rows x n columns.
eColor_Tone_DreamCatcher_48 Color/Tone Auto: DSClabs DreamCatcher 48.
eColor_Tone_ColorGauge_6x5 Color/Tone Auto: ColorGauge 6×5
eColor_Tone_Rez_Checker Color/Tone Auto: ColorGauge Rez-Checker 6Wx7H
eColor_Tone_DigitaL_TargeT Color/Tone Auto: 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.



The eColorTone_special_gray_tenumeration delineates the special grayscale charts that are available in Color/Tone.

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


eColor_Tone_special_gray_ISO_14524 = 1 ISO-14524 (OECF 12-patch circular) chart
eColor_Tone_special_gray_QA_61 QA-61 (square pattern) chart
eColor_Tone_special_gray_QA_62 QA-62 (square pattern) chart
eColor_Tone_special_gray_ISO_15739 ISO-15739 chart
eColor_Tone_special_gray_ITE ITE Grayscale chart
eColor_Tone_special_gray_OECF_20 OECF 20-patch circular chart
eColor_Tone_special_gray_circle Squares arranged in a circle chart
eColor_Tone_special_gray_ST_51 EIA Grayscale (ST-51) chart
eColor_Tone_special_gray_QA_79 QA-79 chart
eColor_Tone_special_gray_general General mxn (m rows x n columns) chart
eColor_Tone_special_gray_Imatest_Dynamic Imatest 36-patch Dynamic range chart




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 Color/Tone Interactive, refreshing the Color/Tone Interactive dialog with a new image, and then closing Color/Tone Interactive and opening SFRplus Setup to analyze another image.