Documentation – Legacy v5.1 and below

Imatest IT/EXE instructions

How Imatest IT/EXE works

Imatest IT/EXE (Industrial Testing EXE; formerly API/EXE) is a set of standalone programs initiated by DOS calls, which can be issued by a test system. The programs have the same functionality as the corresponding Imatest Master modules, but they operate without user intervention, making them suitable for use in automated testing systems. They are represented by the blue box in the lower right of the figure below.

Imatest IT/EXE flow diagram

The test system interacts with the IT/EXE programs through files specified in the DOS command line— primarily an image file and an INI control file (created and saved by Imatest Master during setup). The output is data files in Excel-readable CSV, JSON, and/or XML formats. Figures (PNG files) can be generated and saved if desired.

Watch on YouTube.

The following programs are included in IT/EXE (links are to descriptions of the Master versions).

SFR   SFRplus   Colorcheck   Stepchart
Uniformity (Light Falloff)   Distortion   Blemish   Dot Pattern
OIS   eSFR ISO   Star   Wedge
Random   Multitest    Checkerboard   SFRreg

Although Imatest IT/EXE operates independently of Imatest Master, we strongly recommend that IT/EXE users have at least one Imatest Master or Image Sensor installation on site to facilitate setting up and testing the INI file.

Comparison of Imatest IT/EXE and DLL
EXE DLL
Called from any program (C++, LabVIEW, etc.) using a DOS command Called directly from C, C++. Support for .NET, C-Sharp, and LabVIEW is under development.
Input includes an INI control file and an image file (raw or processed). Input includes an INI control file. The input image (raw or processed) may be read from a file or directly passed from the calling program (much faster).
Output to CSV, JSON, and XML files, and (optionally) to figure image files. Output to all files supported by EXE. In addition, variables can be returned directly to the calling program. Most of the key results included in the CSV files can be returned directly using a JSON object.
Slow on first run because the Matlab Runtime library has to be loaded and unpacked. Faster on succeeding runs. Generally faster, especially with direct image passing.

Installing Imatest IT/EXE

When you purchase Imatest IT/EXE or request a trial we will send you details on how to download the installation file. A typical installation file name is Imatest-IT-EXE-version_exp_date.exe. The expiration date will be displayed in the DOS window when a module is run, for example, "Colorcheck IT 18-Dec-2011 valid through 01-Feb-2013". This may change somewhat when the new registration system is implemented.

Register Imatest IT

Old registration window (prior to Imatest 3.7)

Installation: Install the module by double-clicking on the installation file name in Windows Explorer. Then either register the module (if you purchased it) or make sure Imatest Studio or Pro is registered on your computer (for the trial version).

Registering IT/EXE modules (before 3.6): Double-click on register_imatest.bat in the Imatest installation folder (C:Program FilesImatest in English language installations). Fill in the Name, Company, E-mail, and Password fields, keeping IT in the program field, as shown on the right, then press Register.

Registration for trial version (before 3.6): Can be done in two ways. (1) Install Imatest and register it using the normal procedure: Click Help, Register, then fill in the fields and press Register. (2) Double-click on register_imatest.bat in the Imatest installation folder. The dialog box shown on the right appears. Fill in the fields and select Imatest in the program field, then press Register. The 30-day trial version will work with an Imatest Studio or Master password.

Path: You should add folders to the system path if they are not present.

  • Open the Control Panel.
  • Double-click on System in Windows XP. In Windows 7, click on System and Security, then System.
  • Click on the Advanced tab in the System Properties window (Advanced system settings in Vista/7).
  • Click on Environment Variables. If Matlab is installed on your system, see the Path conflicts box, below.
  • Select PATH in the User variables... window.
  • Click on Edit....
  • Check to see if the folders listed below are included in the Variable value field for Path. (Note: the Edit window is annoyingly tiny and can't be resized. You may find it useful to copy the contents by clicking control-A, control-C, then pasting it into a text editor.) See explanation of %ProgramFiles%, below. If they are not there, add them to the Variable value field. (You may copy and paste.)
    • Before Imatest 3.6:; %ProgramFiles%Imatest; %ProgramFiles%Imatestbinwin32; %ProgramFiles%Imatesttoolboxmatlab
    •  Imatest 3.8-3.9:; "%ProgramFiles%ImatestIT-EXE; %ProgramFiles%MATLABMATLAB Compiler Runtimev714runtimewin32;
      %ProgramFiles%MATLABMATLAB Compiler Runtimev714"
    • Imatest 3.10-4.0:; "%ProgramFiles%ImatestIT-EXE; %ProgramFiles%MATLABMATLAB Compiler Runtimev81runtimewin32;
      %ProgramFiles%MATLABMATLAB Compiler Runtimev81"
  • %ProgramFiles% is an environment variable that represents the system default program installation folder in Windows XP and 32-bit Vista/7 installations. Use %ProgramFiles(x86)% for 64-bit Vista/7. %ProgramFiles% is equivalent to C:Program Files in 32-bit English-language installations. These folder have different names in non-English installations, for example, %ProgramFiles% is C:Programme in Deutsch. %ProgramFiles% and %ProgramFiles(x86)% should be consistent for all languages. Alternatively, you may use the actual folder names. ; C:Program FilesImatestIT-EXE; C:Program FilesMATLABMATLAB Compiler Runtimev81runtimewin32;C:Program FilesMATLABMATLAB Compiler Runtimev81" (English-only) After you add the folders, be sure the Path list is well-formatted— that it consists of proper folder names separated by semicolons (;).
  • Click OK ... to close the System window.
Path conflicts If a different version of Matlab from the one used for Imatest (6.5.1 prior to version 3.6) has been installed on your system, you may experience a path conflict that causes an error message similar to the message below— or Imatest IT/EXE may simply fail to run, without returning an error message.

X The procedure entry point svDoubleSclarRemW could not be
be located in the dynamic link library libmwservices.dll

If you receive such a message, you can try two solutions.

1. Alter the Path environment variable in System variables, located below User variables in the Environment Variables window. Be sure that the folders listed above appear before the similar folders for the installed version of Matlab. This may involve some careful copying and pasting. Be sure to check the path carefully before you click OK.

2. Initiate IT/EXE programs using the second method shown below: call a DOS BAT file, which sets the path and calls the command line. (Do this instead of directly calling the command line.) This often resolves conflicts.

Setting up IT/EXE

Set up the test system (lights, camera, etc.) and photograph a test chart lighted and framed as it would be in the actual tests.

Save the image in a standard file format. It should have the same pixel count as the actual test images.

Analyze the image using (GUI-based) Imatest Master.

When the settings are correct— when the ROI (region of interest), the calculation details, and the output files and folder locations are what you need for production— press Save settings... (or Settings, Save Settings...) in the Imatest main window. This allows you to save the control information for Imatest IT/EXE in a named INI file, which can be viewed and edited with any standard text editor or with the INI File Editor. Be sure to save it in a convenient, accessible folder. The contents of .ini files are largely self-explanatory. Here is a sample.

[sfr]
nht_save = 2052
nroi = 2
nwid_save = 3076
roi_mult = 1606 931 1735 1149;334 1693 466 1912
aper =
CA = Min
cyclesper = Max
cyclesper_value = 1
gamma = 0.5

The INI file is divided into sections that start with a bracketed name. [sfr], [sfrplus], [q13], [colorcheck], [distortion], [uniformity], [blemish], and [dot] are the sections for the eight programs that comprise IT/EXE. Of the remaining sections, only [api] (described below) affects IT/EXE operation.

INI file: more detail

The settings described below are listed in the Imatest INI Reference.

General settings Press Settings, IT options in the Imatest Master main window to open a dialog box that sets options that only affect IT programs— they do not affect regular Imatest operation. These options are written into the [api] section of imatest.ini. See the [api] section of the INI File reference.

IT_optionsImatest IT (Industrial Testing) settings

Checking Always save then delete figures makes sure all figures are closed at the end of the run, no matter what the other settings indicate.

Checking Never display progress bars and warning messages disables these graphic displays. These settings affect the contents of the following lines in the INI file.

[api]
nomsg = 1
savedel = 1

These lines can be edited using any text editor or the INI File Editor; the IT Options box is merely a convenience. Certain other options in the [imatest] section may be of interest to IT users.

[imatest]
readexif = 1 (Reads EXIF data from JPEG images when set to 1; readexif = 0 turns off EXIF read.)

Figures The INI control determines which figures are generated and saved. Any figures that aren't needed they should be turned off for speed. Most are set to either Min (figure off) or Max (figure on), but some (noted in the table below), are set to 0 (figure off) or a number >= 1 (figure on, depending on conditions). These parameters can be set using a text editor, but it's usually more convenient to uncheck the appropriate boxes in the Imatest Master input dialog box prior to saving the INI file.

SFR saveThe rightmost column in the above table is the index of array save_file_list, which is included in each module's section ([sfr], [sfrplus], [q13], [colorcheck], [distortion], [uniformity], [blemish], and [dot]). This index indicates which output figures and files to save. It is generated by the Save dialog box (shown on the right for SFR; Note that the order of the indices may differ from the figure.) For example,

[SFR] ...
save_file_list = 1 0 0 0 0 1 0 0

directs the SFR module to save the MTF plot in cycles/(pixel or distance) and the CSV output file that contains detailed results.

Another important variable that appears in the sections for the five modules is closefigs. If closefigs = 1, figures will be deleted after being saved.

Some specific settings

[SFR]

roi_mult contains the coordinates of the region(s) of interest, four entries per region: Left, Top, Right, Bottom (L T R B, with the number of regions specified by nroi). Units are in pixels from the top-left of the image. Note that this is different from the order displayed on the SFR Edge/MTF figure: L R T B.

DOS Command line call

Imatest IT/EXE programs are initiated by one of two methods.

The first and simplest method is a direct DOS command line call, which has the following form (for 64-bit Windows Vista/7).

C:Program Files (x86)ImatestIT-EXEsfr.exe param-1 param-2 param-3 param-4 param-5 { param-6 ... }

Available program names (typically located in %ProgramFiles(x86)%ImatestIT-EXE) include

sfr.exe, sfrplus,exe, colorcheck.exe, stepchart.exe, distortion.exe, uniformity.exe, blemish.exe, and dotpattern.exe.

The second method is to create and call to a DOS BAT file, which sets the path and calls a DOS command line. Use this method to resolve path conflicts (which may happen in installations that contain different versions of Matlab from the one used to compile Imatest). The call to the BAT file has the form,

pathnamebatfilename.bat

where batfilename.bat contains lines of the following form.

path="%ProgramFiles%ImatestIT-EXE; %ProgramFiles%MATLABMATLAB Compiler Runtimev714runtimewin32; %ProgramFiles%MATLABMATLAB Compiler Runtimev714"; %path%"

C:Program Files (x86)ImatestIT-EXEsfr.exe param-1 param-2 param-3 param-4 param-5

The first three parameters (Param-1 - Param-3) are required. The fourth is strongly recommended and the fifth and beyond are optional. Program names and parameters 2-5 should contain full path names to minimize the likelihood of error.

Param-1 -1 Closes the DOS window and all figures when the program terminates. For normal operation of IT/EXE programs. -2, -3, and -4 are for debugging.-2 Keeps the DOS window open after the program terminates.-3 Closes the DOS window and all figures when the program terminates and opens the error log file if an error is detected.-4 Keeps the DOS window open after the program terminates and opens the error log file if an error is detected.-11 Combine files (Param-2, Param-6, ff.), i.e., average them before analysis. This can be useful for viewing fixed pattern noise.
-12 Use two files (Param-2 and Param-6) to analyze temporal noise (Stepchart and Colorcheck-only).
Param-2 Image file name. The full path name should be used, e.g.,"C:Imatest_dataITStepchart_DR_Canon_G2.JPG" in the example below. If the file name contains an asterisk (*)— it will be treated as a wildcard character, and several files may be read. Additional image files can be entered starting with Param-6.
Param-3 Folder where the IT/EXE and other programs are located. ( "C:Program FilesIT-EXEimatest" in the example below, which is typical of English language systems). The C:Program Files folder has different names in different languages, for example, C:Programme in German. The name can be viewed by entering set %ProgramFiles% in a DOS window.)
Param-4
.ini control file name. If omitted, it defaults to imatest.ini in the same directory as the exe programs. "C:Imatest_dataITstepchart_DR_canon_G2.ini" in the example below.) We strongly recommend including it.
Param-5 (optional) folder where results are written. If omitted, it defaults to subfolder Results in the directory that contains the image file. ( "C:Imatest_dataITResults" in the example below.) If you want to omit this parameter but use Param-6, enter [].
Param-6, Param-7, ...
(optional)
Additional image files (there can be many).
If Param-1 == -1 through -4, the files (Param-2, Param-6, ff.) are read and analyzed separately.

If Param-1 == -11, the files are combined, i.e., averaged before analysis (usefulfor viewing fixed pattern noise).
If Param-1 == -12, use two files (Param-2 and Param-6) to analyze temporal noise (Stepchart and Colorcheck-only).

If field names contain blanks, they should be enclosed in quotation marks ("). We recommend always enclosing all fields, including the program call, in quotation marks, except for parameter 1. Example:

"C:Program FilesimatestIT-EXEstepchart.exe" -1 "C:Imatest_dataITStepchart_DR_Canon_G2.JPG" "C:Program FilesIT-EXEimatest" "C:Imatest_dataITstepchart_DR_canon_G2.ini" "C:Imatest_dataITResults"

Calling IT/EXE from Matlab

DOS commands can be called from Matlab by statements of the form,

dos('command')
system('command')
!command
— or—
!command & (opens and displays results in a separate DOS window— convenient if you want one opened)

where command is a dos command string, which can take the form shown in the example above.

If you are running a different version of Matlab from the one used to compile IT/EXE, use the second method described above, a call to a DOS BAT file, to avoid path issues. The following code creates and runs a bat file (sfr_batest.bat).

fbat = fopen('C:imatestmatlabsfr_battest.bat','wt');

fprintf(fbat,['path="%%ProgramFiles%%\Imatest\IT-EXE; ...
%%ProgramFiles%%\MATLAB\MATLAB Compiler Runtime\v714\runtime\win32;' ...
'%%ProgramFiles%%\MATLAB\MATLAB Compiler Runtime\v714; %%path%%"n']);

fprintf(fbat,['"C:\Program Files\imatest\IT-EXE\sfr.exe" -1 "C:\imatest\data_SFR\Canon_17-40_24_f8_C1_1409.jpg" ' ...
'"C:\Program Files\imatest" "C:\Imatest\matlab\Results\Canon1740_ctr.ini"n']);

fclose(fbat);

dos('C:\imatest\matlab\sfr_bat\test.bat'); % system(...) will also work.

% !C:\imatest\matlab\sfr_bat\test.bat &

%% and \ are escape sequences that cause single % and characters to be written. File sfr_battest.bat contains the following two lines:

path="%ProgramFiles%ImatestIT-EXE; %ProgramFiles%MATLABMATLAB Compiler Runtimev714runtimewin32; %ProgramFiles%MATLABMATLAB Compiler Runtimev714"; %path%"

"C:Program Filesimatestsfr.exe" -1 "C:imatestdata_SFRCanon_17-40_24_f8_C1_1409.jpg" "C:Program Filesimatest" "C:ImatestmatlabResultsCanon1740_ctr.ini"

Testing Imatest IT/EXE

Several test files (image files, INI control files, and DOS BAT files) are available for testing and verifying IT/EXE installations. The image files can also be used with Imatest Master. Right-click on the file names in the table below to download the files. We recommend saving them in subfolder IT of the Imatest installation folder: C:Program FilesImatestIT (in English language installations) or in the equivalent in other languages (for example, C:Programme... in German). For testing we recommend setting the first parameter in the DOS call to -4 (keep the DOS window open and display the error log if an error occurs).

Downloadable test images
Module
Image file
INI & BAT files Description
  Webcam image of high and medium contrast custom charts created by Test Charts and printed on an Epson R2400 printer: these can have larger regions of interest (ROIs) than the ISO 12233 chart below.
  Webcam image of ISO 12233 chart. At this distance the available regions of interest are very small.
  Webcam image of the Kodak Q-14 grayscale and GretagMacbeth ColorChecker.
stepchart_DR_canon_G2.inistepchart_DR_canon_G2.bat Image of the Stouffer T4110 transmission test chart taken with the Canon Powershot G2. Excellent dynamic range measurement.
(image in Colorcheck, above)GMB_Q-14_webcam.jpg
  Webcam image of the Kodak Q-14 grayscale and GretagMacbeth ColorChecker.
  12-patch OECF chart (for IT and Imatest Master only ). Available from Applied Image.
  Image of Kodak Q-14 chart with "black hole" cavity for measuring veiling glare (susceptibility to lens flare)
Distortion image from webcam204 kBdistortion_webcam_a.jpg
  Webcam image of distortion grid.
Uniformity(LightFalloff)
  Image of nearly uniformly illuminated surface taken with the Canon 10-22mm lens on the EOS-20D, f/4.5, 22mm, ISO 1600.

To use these test files,

  • Make any necessary changes to the saved ini and bat files using a text editor. You'll need to update folder names if Imatest is installed in a folder other than C:Program FilesImatest or the test files (above) have been saved in a folder other than C:Program FilesImatestIT. You only need to edit folder names in the appropriate section of the ini file, which follows the module name enclosed in brackets: [sfr], [sfrplus], [colorcheck], [q13] (for Stepchart), [distortion], [uniformity] (for Light Falloff), [blemish], or [dot].
  • Open a DOS window (Start, Run..., cmd; Start, All Programs >, Accessories >, Command Prompt).
  • Change to the directory where the files are located. Typically, entercd C:Program FilesImatestIT-EXE.
  • Run the bat file by entering the file name, omitting the bat-extension. For example,stepchart_DR_canon_G2
  • Verify the results by looking in the folder where results are stored, typically subfolder Results of the folder that contains the image, ini, and bat files. If you found errors that aren't obvious and aren't covered in the Troubleshooting page, please contact us.

Error handling

Imatest IT/EXE modules return a value of 0 if they terminate correctly or 1 or larger if they terminate in error.

If an error is detected, a message is

  • appended to the error log file, which has the name of the form module.log (sfr.log, colorcheck.log, stepchart.log, distortion.log, uniformity.log, ...), and is is located in %APPDATA%Imatest.
  • written to the CSV and/or XML file that would otherwise contain the results of the run. For the example above,

"C:Program Filesimateststepchart.exe" -1 "C:Program FilesimatestITStepchart_DR_Canon_G2.JPG" "C:Program Filesimatest"

"C:Program FilesimatestITstepchart_DR_canon_G2.ini" "C:Program FilesimatestITResults"

If a CSV output file were called for, it would be C:Program FilesimatestITResultsStepchart_DR_Canon_G2_summary.csv ;

if an XML output file were called for, it would be C:Program FilesimatestITResultsStepchart_DR_Canon_G2.xml .

APPDATA is a DOS environment variable whose value can be found by opening a DOS (CMD) window and typing

set APPDATA (Returns the folder name corresponding to APPDATA)

--or--

dir "%APPDATA%Imatest"

APPDATA is typically

  • C:Usersyour nameAppDataRoaming in Windows Vista/7.
  • C:Documents and Settingsyour nameApplication Data in Windows XP.

To facilitate debugging, the log file will be opened in Notepad if an error is detected and the first parameter of the IT/EXE DOS call is -3 or -4.

Lines in the log file have the format,

[Date Time], file_name, error_message

Example:

[05-May-2007 23:34:08], C:Imatestdata_distortiondistgrid101.jpg, Inconsistent Vert lines 17 det.; 18 avg. Incomplete line?

We are constantly working to improve the robustness of Imatest algorithms to minimize the occurrences of errors, which are typically caused by poor region (ROI) selections or poor quality images.