Login or Create Account

Imatest API/EXE instructions

Running Imatest API/EXE

   My Account  |  Cart Contents  |  Checkout   
Table of contents
Introduction Installation Setup INI files DOS call Calling from Matlab Testing Error handling
See Also
Imatest API
Printable Page

How Imatest API/EXE works

Imatest API/EXE is a set of standalone programs initiated by DOS calls from the test system. The programs have the same functionality as the corresponding modules in Imatest Master, but they operate without user intervention, making them suitable for use in automated systems. They are represented by the blue box in the lower right of the figure below.

Gamutvision block diagram

The test system interacts with the API/EXE programs through files specified in the DOS command line: the primary inputs are an image file and an INI control file (created and saved by Imatest Master during setup). The output is data files in XML or Excel-readable .CSV format. Figures can be generated and saved if desired.

Although Imatest API/EXE operates independently of Imatest Master, we strongly recommend that API/EXE users have at least one Imatest Master installation on site.

Installing Imatest API/EXE

When you purchase Imatest API/EXE or request a 30-day trial we will send you details on how to download the installation files. A typical file name is colorcheck-04-02-07.exe, where 04-02-07 is the release date. The trial expires on the same date of the following month. (This naming convention may change in future releases).

Register Imatest APIInstallation: 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 API/EXE modules: Double-click on register_imatest.bat in the Imatest installation folder (C:\Program Files\Imatest\ in English language installations). Fill in the Name, Company, E-mail, and Password fields, keeping API in the program field, as shown on the right, then press Register.

Registration for trial version: 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 Pro password.

Path: You should add three folders to the system path if they are not present. In Windows XP,

Path conflicts
If a different version of Matlab from the one used for Imatest (6.5.1) has been installed on your system, you may experience a path conflict that causes an error message similar to the message shown on the right— or Imatest API/EXE may simply fail to run, without returning an error message.    
X   The procedure entry point svDoubleSclarRemW could not 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 three 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 API/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 difficult conflicts.

Setting up API/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 API/EXE in a named .INI file, which can be viewed and edited with any standard text 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
camera =
cyclesper = Max
cyclesper_value = 1
foclth =
gamma = 0.5

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

INI file: more detail

General settings  Press Settings, API options in the main Imatest window to open a dialog box that sets options that only affect API programs— they do not affect regular Imatest operation. These options are written into the INI file.

API options dialog box

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 in the INI file using any text editor; the API Options box is merely a convenience. Certain other options in the [imatest] section may be of interest to API 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 input dialog box prior to saving the INI file.


The rightmost column in the above table is the index of array save_file_list, which is included in each module's section ([sfr], [q13], [colorcheck], [distortion], and [uniformity]). 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.

SFR save

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 API/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.

c:\program files\imatest\sfr.exe param-1  param-2  param-3  param-4  param-5

Ths second method is to create and call to a DOS BAT file, which sets the path and calls a DOS command line. This may be needed when the first method fails, for example, when a path conflict is difficult to resolve (which may happen in installations that contain newer versions of Matlab than the one used to compile Imatest). The call to the BAT file has the form,

pathname\batfilename.bat

where batfilename.bat contains lines of the following form.

path="%ProgramFiles%\Imatest;%ProgramFiles%\Imatest\bin\win32;%ProgramFiles%\Imatest\toolbox\matlab;%path%"
c:\program files\imatest\sfr.exe param-1  param-2  param-3  param-4  param-5

The first three parameters (param-1 − param-3) are required. The fourth is optional but strongly recommended and the fifth is optional. The program name 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 API/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.
Param-2 Image file name. The full path name should be used, e.g.,"c:\program files\imatest\API\Stepchart_DR_Canon_G2.JPG"in the example below
Param-3 Folder where the API/EXE and other programs are located. ( "c:\program files\imatest" 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 (optional*) .ini control file name. If omitted, it defaults to imatest.ini in the same directory as sfr.exe."c:\program files\imatest\API\stepchart_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:\program files\imatest\API\Results" in the example below.)
*Always use these fields until further notice.

We may add additional parameter-value pairs on user request.

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 (which must be -1). Example:

"c:\program files\imatest\stepchart.exe" -1 "c:\program files\imatest\API\Stepchart_DR_Canon_G2.JPG" "c:\program files\imatest" "c:\program files\imatest\API\stepchart_DR_canon_G2.ini" "c:\program files\imatest\API\Results"

Calling API/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)

where command is a dos command string, which can take the form shown in the example above. Dos or system are recommended.

If you are running Matlab 6.5.1 (the same version used by Imatest), a direct DOS command line call (illustrated above), should work fine. But if you are using a newer version of Matlab (7+), the second method, a call to a DOS BAT file (also illustrated above), may be required to avoid path issues. The following code creates and runs a bat file (sfr_batest.bat). It has been tested with Matlab 7.4.0 (R2007a).

fbat = fopen('c:\imatest\matlab\sfr_battest.bat','wt');
fprintf(fbat,['path="%%ProgramFiles%%\\Imatest;%%ProgramFiles%%\\Imatest\\bin\\win32;' ...
     '%%ProgramFiles%%\\Imatest\\toolbox\\matlab;%%path%%"\n']);
fprintf(fbat,['"c:\\program files\\imatest\\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_battest.bat');
% !c:\imatest\matlab\sfr_battest.bat &

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

path="%ProgramFiles%\Imatest;%ProgramFiles%\Imatest\bin\win32;%ProgramFiles%\Imatest\toolbox\matlab;%path%"
"c:\program files\imatest\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"

Testing Imatest API/EXE

Several test files (image files, INI control files, and DOS BAT files) are available for testing and verifying API/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 API of the Imatest installation folder: C:\Program files\Imatest\API (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.ini
stepchart_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 API 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)
  Webcam image of distortion grid.
  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,

Error handling

Imatest API/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

APPDATA is a DOS environment variable whose value can be found by opening a DOS window (you can double-click start-dos.bat in the Imatest folder), and typing

set APPDATA                       (Returns the folder name corresponding to APPDATA)
               --or--
dir "%APPDATA%\Imatest"

APPDATA has values of the form

To facilitate debugging, the log file will be opened in Notepad if an error is detected and the first parameter of the API/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:\Imatest\data_distortion\distgrid101.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.