thmiric Documentation

thmiric - Generate THEMIS IR registered instrument coordinate cubes
OVERVIEW

This procedure processes Level 1 (radiometrically calibrated)
ISIS-formatted THEMIS IR cubes to produce aligned instrument coordinate
cubes.  (Uncalibrated raw data can also be processed.)  The REFBAND
parameter specifies a "reference band" in the input cube.  In the
output cube, the reference band data are unchanged and the other
bands are projected (and optionally resampled) so that they are
registered with the "reference band."  The reference band in the output
cube is padded with lines/columns of NULL pixel values to allow
registering the other bands without losing data.  The INTTYPE and
MINVALS parameters specify the desired interpolation algorithm and
handling of input NULL and Saturated values.

The input file (specified by the FROM parameter) should be an
ISIS cube that was produced by running "thm2isis" on a PDS file
produced by the Arizona State University software.  Alternatively,
the FROMLIST parameter can be used to specify a file that contains
a list of cubes to be processed.


PROCESSING WITHOUT USE OF TAE

This procedure provides an interactive interface to the PERL
scripts that perform the work involved in generating the
aligned instrument coordinate cubes. The PERL scripts can
also be run standalone from the command line which makes them
ideal for use in web.html applications. There are two PERL
scripts available for creating aligned instrument coordinate
THEMIS IR cubes: thmiric.pl, thmiric_batch.pl

The thmiric.pl script will process a single file for each
execution of the script. The thmiric_batch.pl script allows you
to process a list of files for each execution of the script.

The syntax for processing a single file is as follows:

thmiric.pl from [to] [refband] [toppad] [botpad] [leftpad]
  [rightpad] [retest] [inttype] [minvals]

The syntax for processing a list of files is as follows:

thmiric_batch.pl fromlist [refband] [toppad] [botpad] [leftpad]
  [rightpad] [retest] [inttype] [minvals]

All the parameters in square brackets [] above are optional. The
parameters in square brackets can be used to modify how the output
geometrically transformed cube is created. If a parameter is specified
on the command line, then all of the parameters preceding it must also
be specified. If you want the default of a parameter to be used, then
two dashes "--" can be used to specify this on the command line.  For
example, the following command can be used to process a single file
(called thm01.cub) and set the interpolation type (inttype) to
NEAREST_NEIGHBOR:

thmiric.pl thm01.cub -- -- -- -- -- -- NEAREST_NEIGHBOR

In the command above, the user wanted to specify a non-default
interpolation type of NEAREST_NEIGHBOR. However, the user wants to use
the default output filename, reference band, top pad, bottom pad, left
pad, and right pad.  The double dash "--" is used as a place marker so
that the script knows which value on the command line applies to which
parameter in the script.  Notice that none of the parameters that occur
after the interpolation type had to be set to "--" because the user is
letting everything else use the default value.


PROCESSING AND ERROR LOGGING

If an error occurs during processing, then thmiric.err will be
created, which will contain some error-related information.  The session
log file (print.prt unless the ISIS_LOG_FILE environment variable has
been set) will contain a complete history of the processing as well as
additional error information.

During processing, a number of intermediate files are created.  The
names of these intermediate files are constructed by taking the core
name of the input file (name without path or extension) and expanding
it into the names for the intermediate files.  There are 6 types of
intermediate files created during processing.  Here is a synopsis of
what those file names are and what they are used for:

corename_b#.cub        = A single-band file containing band number #
                         from the input file.
corename_b#_gm.cub     = This is the single-band file containing band
                         number # from the input file after it has been
			 geomed.
corename_reference.cub = This is the file containing the reference band
                         that is used to register the other bands to.
corename_tfile.dat     = A file containing transformation information
                         for the geom program.
corename_geom1.WRK     = A work file used by the geom program.
corename_geom2.WRK     = A work file used by the geom program.

Programmer:  Janet Barrett, U.S.G.S., Flagstaff, 21 Nov 2002

Input filename
  (default extension is .cub)

--

List of input filenames

--

Output filename
  (default extension is .cub)

--

Reference band
  (FILE band number)

--

Number of lines of padding
  on top of reference band

10

Number of lines of padding
  on bottom of reference band

10

Number of samples of padding
  on left of reference band

10

Number of samples of padding
  on right of reference band

10

Grid spacing for projection
  computation (Null, 1, 4, 16)

--

Interpolation type to be used
  (BILINEAR or NEAREST_NEIGHBOR)

BILINEAR

Minimum number of valid pixels
  for INTTYPE=BILINEAR

4

ADDITIONAL NOTES:

Parm	Description
FROM	This is normally a Level 1 (radiometrically calibrated) ISIS-formatted THEMIS IR cube created by running "thm2isis" on a PDS file produced by the Arizona State University software. Uncalibrated raw data can also be processed. ("thm2isis" runs "pds2isis" to convert to ISIS format and "levinit" to initialize the label for geometry processing.) The input cube can be one of the three pixel data types supported by ISIS. The output cube will be the same data type as the input cube. If the file extension is omitted, then ".cub" will be assumed. If FROM is specified, then the FROMLIST parameter must be specified as the Null TAE parameter value.
FROMLIST	This specifies a file that contains a list of cubes to be processed. The input list must be a single column file that contains one input cube file name per line. If the file extension of the filenames in the list is omitted, then ".cub" will be assumed. The input files are normally Level 1 (radiometrically calibrated) ISIS-formatted THEMIS IR cubes created by running "thm2isis" on PDS files produced by the Arizona State University software. Uncalibrated raw data can also be processed. Each input cube can be one of the three pixel data types supported by ISIS. The output cube will be the same data type as the corresponding input cube. If FROMLIST is specified, then the FROM parameter must be specified as the Null TAE parameter value. The output filenames will automatically be created by using the 'root' input name (without extension) with ".iric.cub" appended.
TO	If a single file is processed using the FROM parameter, then this parameter can be used to name the output file. If the file extension is omitted, then ".cub" will be assumed. This parameter is ignored when a FROMLIST is entered. If the FROMLIST option is used or if this parameter is left as the TAE Null parameter value, then the output filename will default to be the 'root' name of the input file (without extension) with ".iric.cub" appended.
REFBAND	This is the FILE band number in the input cube file to which the other bands will be registered. Note that REFBAND does not refer to the band number relative to the IR instrument. For example, if the input image has the BAND_BIN_ORIGINAL_BAND keyword set to (1,2,5,6,7) and you specify REFBAND=5, then the 5th band in the input cube (which is band 7 of the IR instrument) will be used. If REFBAND is specified as the TAE Null parameter value, then the reference band that is used will be the middle band of the cube. If there are an even number of bands in the cube, then the default REFBAND is determined by dividing the number of bands by 2. For example, if there are 4 bands in the cube, then REFBAND=2 would be used. If there are 5 bands in the cube, then REFBAND=3 would be used.
TOPPAD	TOPPAD/BOTPAD/LEFTPAD/RIGHTPAD specify the number of pixels of NULL padding that are to be added to the top/bottom/left/right sides of the reference band in the output cube. Adding this padding can prevent data for other bands from being lost when they are registered to the reference band.
BOTPAD	TOPPAD/BOTPAD/LEFTPAD/RIGHTPAD specify the number of pixels of NULL padding that are to be added to the top/bottom/left/right sides of the reference band in the output cube. Adding this padding can prevent data for other bands from being lost when they are registered to the reference band.
LEFTPAD	TOPPAD/BOTPAD/LEFTPAD/RIGHTPAD specify the number of pixels of NULL padding that are to be added to the top/bottom/left/right sides of the reference band in the output cube. Adding this padding can prevent data for other bands from being lost when they are registered to the reference band.
RIGHTPAD	TOPPAD/BOTPAD/LEFTPAD/RIGHTPAD specify the number of pixels of NULL padding that are to be added to the top/bottom/left/right sides of the reference band in the output cube. Adding this padding can prevent data for other bands from being lost when they are registered to the reference band.
RETEST	When the RETEST parameter is set to the Null TAE parameter value, the "lev1tolev1" program computes the projection to Instrument Coordinates by checking the corners and center point of each 64x64 box in the output image to see if any of them correspond to a point on the input image. If none of them fall on the input image, then it is assumed that no input data is projected within the 64x64 box. If a piece of the input image data falls within the box but does not hit the center or any of the corner points, then a corresponding piece of the input image data will get chopped off and will not appear in the output image. Specifying a RETEST value of 1, 4, or 16 (the only permitted values) allows the user to decrease the amount of input image data that does not get projected to the output image. When a non-Null RETEST value is specified, a 64x64 box that does not appear to contain any image data is retested with the specified pixel spacing to see if any of these points correspond to input image data. If any of the tested points (in either the original 64x64 box or the smaller retest boxes) corresponds to an input image pixel, then all points within the box will contain the proper projected input image pixels. Thus, specifying smaller RETEST values will increase the processing time while decreasing the amount of input image pixels that do not get projected to the output image. Specifying RETEST=1 will guarantee that no input image pixels are lost, but this will result in the greatest processing time.
INTTYPE	INTTYPE is the interpolation type to be used by the "geom" program in performing the geometric transformation. The two options are NEAREST_NEIGHBOR or BILINEAR. For more information, read the help for the "geom" program.
MINVALS	MINVALS is used to specify the minimum number of valid pixel values required to generate a valid pixel value when BILINEAR is the requested interpolation type for the "geom" program (see INTTYPE). MINVALS=1 will cause a valid pixel value to be output if any one of the four closest pixels in the input file that map to the output position are valid. MINVALS=4 will require that all four of the closest pixels in the input file that map to the output position be valid. You can specify from 1 to 4 pixels using MINVALS.