Warning: Push Mode Interface will be deprecated in the 2021.1 release. Please migrate to Imatest IT for programmatic image analysis.
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.
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 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 support@imatest.com.
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
- If not already installed, install the Matlab Compiler Runtime v9.2, which can be downloaded from Mathworks.
- Have the Master_push_mode_interface.h and push_mode_IDs.h in the project directory.
- Update your project with the correct include path to <MCR root>\extern\include and library path <MCR root>\extern\lib\win64\microsoft.
- 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:
- Declare and initialize all variables.
- Call init_imatest() to initialize the library functions and Matlab Compiler Runtime (MCR).
- Call start_imatest() supplying the image, test, and chart data and an instance of Imatest will start and analyze the image.
- 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.
- Call stop_imatest() to close Imatest IS.
- Call terminate_imatest() to terminate the Imatest IS libraries and the MCR.
- 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.
| 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.
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.
| 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 |
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.
| 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 |
eChartID_t
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. |
eColorTone_special_gray_t
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 |
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 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.