calmrg Documentation

calmrg - Level1 / merge exposure pairs for Clementine LUB filter
This procedure takes an input file list that contains the input cube
file names of one orbit and runs it thru CLEMPAIR which divides the
pairs of images into two output lists.  All images are run thru
UVVISCAL and RAW_MAXIMUM, RAW_MEAN, & RAW_STANDARD_DEVIATION values
are collected from the labels of each pair of images. The long exposure
is determined by the RAW_MEAN + RAW_STANDARD_DEVIATION value of one
file that is greater than it's pair.  The merge decision tree is
as follows:

1) If long-exp RAW_MAXIMUM is less than 255, use it only.
2) If long-exp RAW_MEAN + RAW_STANDARD_DEVIATION is greater than
       255, use short-exp only.
3) Otherwise, merge long-exp and short-exp by coregistering the
   two files and using the trim filter approach.

The filter merge process involves running a few trim filters on
the saturated file (long-exp) to allow for "smooth" edges of the
areas that will be replaced with the non-saturated file (short-exp).
The input files are also trimmed at the edges to remove invalid data.

Only one of the exposure files were kept in previous processing and
the camera angles were updated ONLY for that file that was kept.
There is a master file of PRODUCT_ID's that each input file to CALMRG
is checked against with the program CLEMPROD. The file that has the
matching PRODUCT_ID to the master file (MASTERFL) is held "still" in
coregistration and it's labels are assured to be kept during the
merging process.  CALMRG bombs if neither of the long/short exposure
files are found in the master file.

****
The purpose of the master list is to ensure that the output lev1
files of CALMRG are the PRODUCT_ID's contained in the ISIS
Clementine (750/lub) SPICE file for updated geometric control.
After CALMRG, the user should be able to run SPICELAB on the output
lev1 files and have a spice record found for each file.  SPICELAB
will update the images labels with the control base camera angles.
If there are any problems, such as not finding images within the
master file, CALMRG "echo's" the filenames to the calmrg(orbit).prt
ascii log file.  At the end of the process, the program ERRORS is
run on the calmrg(orbit).prt file and creates the ercm(orbit).prt
file which contains only the warnings and errors that occurred
during the CALMRG run.
****

**NOTE: This procedure was built for lub filters with a specific
master file in mind...USE AT YOUR OWN RISK when processing other
clementine filters.  What is kept "still" is arbitrarily chosen when
processing other filters and might not be the one you want to keep
if it is highly saturated.  EXPMRG is recommended for other filters.

CALMRG creates an ascii output file in the default directory:
calmrg_fit_(ORBIT #).lis  - contains the filenames of the long and
and the short exposure frames, the gain and offset of each file and
the correlation coeffients [MULT,ADD,R] that were applied in COREG
and FIT to numerically fit the short exposure frame to the long
exposure when necessary. CALMRG uses a separate procedure called
mrgfile to "echo" the information contained in calmrg_fit_#.lis.
A long_exp_orbit#.lis and short_exp_orbit#.lis are created that
contain the filenames of the decided long and short exposures.

**NOTE:  The default is to automatically delete the uvviscal output
files (lubxxxx.cub.cal).
You can save the input files by setting the DELCAL option to "N".

**NOTE2: The HISAT parameter is set at 250 in UVVISCAL when there
         is an attempt to merge the exposure pairs.  If there is
         only one image without a pair, or if for some reason, only
         the short or long exposure is kept then HISAT = --.
Programmer:  Tammy Becker, U.S.G.S., Flagstaff

List of input cube file names
 (No default file extension)

NONE

Orbit number for log filenames
     only

NONE

Filter A,B,C,D or E for log
  filenames only (optional)

--

"Truth" PRODUCT_ID Master file

"$ISISCLEMDATA/clemcontrolid.lis"

Delete input files (yes/no)

NO

Delete output of UVVISCAL
     (yes/no)


   USE FOLLOWING PARAMETERS
      FOR UVVISCAL ONLY...

YES

Convert to I/F reflectance
   values

YES

Dark current constant
(Optional)

--

Dark current file
(Optional)

--

Array of flat-field
coefficients
(Optional)

--

High_Instrument_Saturation
(Default is ISIS Definition)

--

Minimum saturated pixels in
  column before NULL

4

Output pixel type

3

Output pixel data range

0.0,1.0

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROMLIST	List of input cube file names. There is no default extension. The input cubes should be all the files contained in an entire orbit that have been thru CLEM2ISIS. If only a portion of an orbit is desired, the user should make sure that complete pairs are included in the list. Make note that this is a list of file names and that it might be necessary that the list contains the path name for each of the files. The input images are automatically deleted and the output files will go to the same directory that the input files existed. The file extension of the output files will be input + lev1. The output bit type is 3 (floating point) and dn values will represent absolute radiance units.
ORBIT	This parameter tells the procedure the orbit number of the input cube files for print file name purposes. The assumption is that the input file list contains one orbit. If the input list contains more than one orbit, the list must be sorted by orbit and pairs should be listed together. This ORBIT parameter can be set to any integer value, keeping in mind that all output text files created by CALMRG will have the parameter value in the filenames.
FILTER	This paramter tells the procedure the filter that is contained in the fromlist. This is an optional parameter, and can be left at the default null value. This is used simply of output log filenames only.
MASTERFL	This file contains the list of PRODUCT_ID's that are to be held as truth. This is the list of LUB images that were sent to Rand Corp. for updating camera angles. If this parameter is NULL, the procedure assumes that it DOES NOT matter which of the pair of images are "held" as truth, therefore one of the images in each pair will be arbitrarily chosen as truth. It is recommended that EXPMRG be used for other filters, the decision of what is kept is not centered on or biased by a master list. **** The purpose of the master list is to ensure that the output lev1 files of CALMRG are the PRODUCT_ID's contained in the ISIS Clementine (750/lub) SPICE file for updated geometric control. After CALMRG, the user should be able to run SPICELAB on the output lev1 files and have a spice record found for each file. SPICELAB will update the images labels with the control base camera angles. If there are any problems, such as not finding images within the master file, CALMRG "echo's" the filenames to the calmrg(orbit).prt ascii log file. At the end of the process, the program ERRORS is run on the calmrg(orbit).prt file and creates the ercm(orbit).prt file which contains only the warnings and errors that occurred during the CALMRG run. ****
DELLEV0	Specify whether or not to delete the input files to CALMRG. These files are contained in the FROMLIST.
DELCAL	Specify whether or not to delete output files from UVVISCAL. The output files of UVVISCAL have the input file name with point and take up four times the space as your 8-bit input files.
CONV	This option allows the output values to be written as absolute radiance or converted to reflectance values (I/F).
DCCONST	This constant will replace the array of dark current coefficients in the derived dark current file. In most cases, the default should be used for this parameter to indicate the derived dark current file is to be used. The name of the derived dark current file is $ISISDATA/dcfile.cub
DCFILE	This parameter allows the user to use an alternate dark current file. In most cases, the default should be used for this parameter to indicate the derived dark current file is to be used. The name of the derived dark current file is $ISISDATA/dark_uv.cub.
FFFILE	This parameter allows the user to use an alternate flat-field file. In most cases, the default should be used for this parameter to indicate the derived flat-field file is to be used. The name of the derived flat-field file is $ISISDATA/flat_"FILTER_NAME"_uv.cub.
HISAT	High_Instrument_Saturation value. The default is the ISIS definition of High_Instrument_Saturation which is 255 for 8-bit data.
OTYPE	Output pixel data type. Permitted values are: 0 - output type is same as input file pixel type 1 - 8-bit (integer with type conversion parameters) 2 - 16-bit (integer with type conversion parameters) 3 - 32-bit (floating point)
MIN	This parameter is used in the program NULLSAT. It is a user specification for the minimum number of pixels that must be saturated in a column before the entire column is set to NULL-ed. This removes the "haloing" affect of surrounding pixels of the saturated area.
ORANGE	Output pixel data range. If the output pixel type is 1 (8-bit integer with type conversion parameters) or 2 (16-bit integer with type conversion parameters), then the type conversion parameters in the output file will be set to values that allow representing the specified range of output values. Output values outside this range will be stored as the special "representation saturation" value. The ORANGE parameter is ignored if the output pixel type is 3 (32-bit floating point) since type conversion parameters are not applicable to floating point pixel values. If both ORANGE(1) and ORANGE(2) are 0.0, then the type conversion parameters in the output file will automatically be set to allow representing the same range of values as can be represented in the input file. (The user will be required to supply a specific range for ORANGE if the input pixel type is 3 (32-bit floating point) and the output pixel type is 1 (8-bit with type conversion parameters) or 2 (16-bit with type conversion parameters)).
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.