by Ben-chin Cha (04/20/2001)


CALIBRATION_FACTOR program provides the IDL user with a widget application package for flexibly image calibration features for an input set of 2D image_array. It uses the calibration factor table and the number of image operations desired to define a calibration function.

The image calibration function is defined through a set of boxes of selection lists and the table of calibration factors. A user can dynamically enter the new table values and saves as a new vector file, or loads the an vector file and modify the calibration factors through the vector table.

Based on the final calibration factor table entries and list selections, it provides fast and flexible image calibration and report generations.

Command Syntax

Please refer User's Reference Guide for CALIBRATION_FACTOR for command syntax.


Setup Requirement for Unix System

At APS all IDL programs are installed in the /usr/local/epics/extensions/bin/$HOST_ARCH directory. For proper operation of these programs, a user first has to make sure that the IDL 5.0 or later is used. For example, use IDL 5.2 release, set the following :
	source /usr/local/rsi/idl_5.2/bin/idl_setup 
In order to access IDL programs installed in the local epics/extensions/bin, a user has to make sure that the following two environment variables are set before invoking IDL :
         setenv EPICS_EXTENSIONS /usr/local/epics/extensions
and make sure the directory /usr/local/epics/extensions/bin/$HOST_ARCH is in his/her IDL search path.


To access the SCAN2D CALIBRA program in IDL just enter the following command at the IDL prompt:
          [,Classname=classname] [,Inpath=inpath] [,Title=title]
This commnad will automatically load the program into the IDL session . The variables IMAGE_ARRAY specifies whole detector image arrays, ID_DEF specifies the detector presence indicators, and Xv, and Yv specifies the corresponding X and Y positioner value vectors. The string variable classname specifeds the filename where the image_array was extracted from. The string variable inpath specifies the data path to the filename. The string variable title specifies the title of the widget window to be used.

Before calling the CALIBRATION_FACTOR, referal variables must be defined first.


Activate Calibration Widgets

As CALIBRATION_FACTOR program is invoked, a dialog message box 'Calibration-info ' pops up, it reminds the user in order to define and access the calibration function buttons he/she should first to enter the # of mathematical operations desired. It is accomplished by entering the integer number in the text field "# of Opers" and then follows with a CR (carriage return). Then all the inactive widgets will become activated.

The upper portion of calibration program is the calibration factor control area. It consists of widgets related to the loading, modifying, and saving the definition of calibration factor.

The lower portion consists of widgets related to the calibration function control area. It consists of three rows: a row of calibration function buttons, a row of text field of # of Opers: with resultant calibration function, and a row of scroll area of definition selection lists.

Calibration Factor Control Area

The File menu allows the user to load old or save the new calibration factor. The table area allows the user modify the calibration factors through double clicking the old number and then type in the new number followed with the carriage return.
File Menu            
    ->Open...        - Load old calibration factor file into table
    ->Save as...     - Store the calibration factor table as a new file
    ->Save           - Replace the opened file by the new calibration 
                              factor table
    ->Done           - Close the calibration program
Help...              - Pops up the on-line help about this program 
Done                 - Close the calibration program 
Table Area           - Enter the new values of calibration factors 

Calibration Function Control Area

In order to access or modify the definition of the calibration function, a user should always start with the desired (or corrected) number of image operations in the '# of Opers:' text field then followed with the Return key.

The resultant calibration function and the scroll text area containing the selection lists will be updated automatically. Then a user can dynamically re-define the calibration function through selecting the selection lists. The calibration buttons 'Accept & ReCalc...', 'ASCII...' , 'ROI...', and 'Pick1D...' will be activated as soon as the '# of Opers:' is entered.

Default             - Reset all the calibration factors back to 1.0
Accept & ReCalc...  - Accept the calibration function and calculate
                             the new image, then run plot2d program
ASCII...            - Prepare the ASCII file of the calibration 2D
                             image and then run cw_term to display it
ROI2D...            - Run scan2d_roi program with the calibration
Pick1D...           - Run calibra_pick1d program for accessing
                             various column / row 1D fitting or plotting
# of Opers          - Enter the number of image operations desired
                             followed with the carriage return 
Function area       - Display the resultant calibration function 
Scroll Lists area   - Select the desired box of lists to re-define the
                             calibration function
The reusltant calibration function is updated whenever the selection lists or the # of Opers are been modified.

The scroll list area shows the composition of the scroll lists used in the definition of the calibration function. First list is the calibration factor selection box. The # of Opers determines the remaining number of selection boxes of list displayed. For each arithmetic term, there are two lists associated with it: operator selection list and detector selection list.

The calibration factor list consists of NDET factors. The operator list consists of +,-,*,/,(,) selection items. The detector list consists of NDET detector itemes. The NDET is the last detector number defined in scan file.

The constructed function based on the scroll list selections is displayed in the widget of 'Function Area'. A user has to make sure the function is correctly defined before the calculation is performed.


The calibration files are stored under the CALIB sub-directory. If the CALIB sub-directory is not found, it will be automatically created for user on UNIX system, on W95 a user has to create it manually. The program tries to create the CALIB sub-directory under the source data directory first, if the user has no write permission then it will try to create the CALIB sub-directory where the program was invoked.

Two types of file can be saved by the calibration program: definition file and report file.

Definition File

The definition file stores the table of calibration factors. The calibration definition files are saved in XDR format and are not human readable. They can be read and writen by the U_READ, U_WRITE routines.

Report File

The calibration report file is saved in ASCII format which is human readable. The header area contains the information about where the souce images were originally extracted. The calibration function and multiplication factor used are also displayed with the tabulated calibration image data.

Other Output

Since other 2D image processing programs: SCAN2D_ROI, CALIBRA_PICK1D, EZ_FIT on the calbration array can also be invoked by this program, therefore many other types of 1D/2D plot, tiff, ascii, ROI, or XDR files can also be generated by this program.