thmirmc Documentation

thmirmc - Generate THEMIS IR registered map projection cubes
OVERVIEW

This procedure processes Level 1 (radiometrically calibrated)
ISIS-formatted THEMIS IR cubes to produce Level 2 cubes in which
all bands are aligned in a map projection specified by the MAPPARS
parameter.  (Uncalibrated raw data can also be processed.)  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.

The default operation is to produce an output cube that preserves
the resolution in the input data and that includes its full
latitude/longitude range.  Gathering the necessary statistics
on the input file can be a time-consuming operation, so the
SAMPINC/LINEINC parameters can be used to specify subsampling to
increase processing speed at the expense of using less-complete
statistics.  This could result in a spatial area that is somewhat
smaller than necessary for including all the input pixels.  Also,
a degredation in resolution could occur.

In most cases, the output map projection will use the longitude
system (0 to 360 or +/- 180) that was specified when "thm2isis"
was run.  However, if longitude 0 occurs within the data for a
0-360 longitude system projection, then the output projection will
automatically be switched to use the -180 to +180 longitude system.
In a similar manner, if the +/- 180 longitude system was selected
with "thm2isis", then the longitude system will be switched to
the 360 system if longitude 180 occurs in the data.  This automatic
switch of longitude systems prevents generation of large files
that contain some image data on the left and some on the right
with a large blank area in the middle.  The AUTOLON parameter
allows turning off this automatic longitude system switching
when desired, e.g., when generating files to be mosaicked with
other files.


PROCESSING WITHOUT USE OF TAE

This procedure provides an interactive interface to the PERL
scripts that perform the work involved in generating the map
projection cubes. The PERL scripts can also be run standalone
from the command line which makes them ideal for use in web
cgi applications. There are two PERL scripts available for
map projecting THEMIS IR cubes: thmirmc.pl, thmirmc_batch.pl

The thmirmc.pl script will process a single file for each
execution of the script. The thmirmc_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:

thmirmc.pl from [to] [sampinc] [lineinc] [mappars] [retest] [inttype]
  [minvals] [trim] [kmres] [degres] [dem] [usedem] [override]

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

thmirmc_batch.pl fromlist [sampinc] [lineinc] [mappars] [retest]
  [inttype] [minvals] [trim] [kmres] [degres] [dem] [usedem]
  [override]

All the parameters in square brackets [] above are optional. The
parameters in square brackets can be used to modify how the output map
projection 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 sample increment (sampinc) to 10.

thmirmc.pl thm01.cub -- 10

In the command above, the user wanted to specify a non-default sample
increment of 10. However, the user wants to use the default output
filename.  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
sample increment had to be set to "--" because the user is letting
everything else use the default values.


PROCESSING AND ERROR LOGGING

If an error occurs during processing, then thmirmc.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_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.
corename.stats.temp    = A file created by the lev1stats program.

Programmer:  Janet Barrett, U.S.G.S., Flagstaff, 29 Jul 2003

Input filename
  (default extension is .cub)

--

List of input filenames

--

Output filename
  (default extension is .cub)

--

Sample increment for finding
  lat/lon range

10

Line increment for finding
  lat/lon range

10

Map projection and parameters

--

Automatic longitude system?
  (YES, NO)

YES

Latitude range
  (default=calculated)

--

Longitude range
  (default=calculated)

--

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

--

Interpolation type to be used
  (BILINEAR, NEAREST_NEIGHBOR)

BILINEAR

Minimum number of valid pixels
  for INTTYPE=BILINEAR

4

Trim outside lat/lon boundaries?
  (YES, NO)

NO

Output image resolution (km/pix)
      or

--

Output image resolution (pix/deg)

--

Use a DEM file for radii source?
  (YES, NO)

YES

DEM file for radii source

"$ISISDATA/mola_mars_planetary_radius.cub"

Value to override grid size

--

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 VIS 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 ".irmc.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 blank, then the output filename will default to be the 'root' name of the input file (without extension) with ".irmc.cub" appended.
SAMPINC	SAMPINC/LINEINC are the sample/line increments that will be used when collecting statistics about a single-band framelet using the "lev1stats" program. "lev1stats" is used to determine the latitude and longitude ranges as well as resolution. Specifying SAMPINC=1 and LINEINC=1 will result in the most accurate results from the "lev1stats" program. However, small SAMPINC/LINEINC values cause "lev1stats" to run slower. Processing speed can be increased by specifying larger SAMPINC/LINEINC values. However, this could result in an output spatial area that is somewhat smaller than that necessary for including all input pixels. Also, a degredation in resolution could occur.
LINEINC	SAMPINC/LINEINC are the sample/line increments that will be used when collecting statistics about a single-band framelet using the "lev1stats" program. "lev1stats" is used to determine the latitude and longitude ranges as well as resolution. Specifying SAMPINC=1 and LINEINC=1 will result in the most accurate results from the "lev1stats" program. However, small SAMPINC/LINEINC values cause "lev1stats" to run slower. Processing speed can be increased by specifying larger SAMPINC/LINEINC values. However, this could result in an output spatial area that is somewhat smaller than that necessary for including all input pixels. Also, a degredation in resolution could occur.
MAPPARS	MAPPARS allows the user to specify the desired output map projection and its associated parameters that will be used by the "lev1tolev2" program to create the output map-projected file. When this is specified as the TAE Null parameter value (--), the MAPPARS value that will be used for calling "lev1tolev2" will be MAPPARS="SINU:clon,plattyp", which will create a Sinusoidal Equal-Area map with center longitude (clon) equal to the average of the longitude range of the output map. The projection latitude type (plattyp) will be the latitude system that is recorded in the LATITUDE_SYSTEM keyword in the ISIS_TARGET keyword Group in the input file. The value of this keyword is normally set by the LATSYS parameter when running "thm2isis" to translate the PDS QUBE file to ISIS format. If a non-null value is specified for MAPPARS, then this value will be used as the value of the MAPPARS parameter passed to "lev1tolev2". An extensive explanation of this parameter and its various options and defaults can be obtained by tutoring "mappars" in TAE and typing "help *". Note that when SINU or SIMP is specified as the projection name in the MAPPARS value, the default latitude type OGRAPHIC will be used if the projection latitude type is not specified, i.e., the standard MAPPARS default will be used rather than the latitude system that is specified in the input file LATITUDE_SYSTEM label keyword. If OCENTRIC latitudes (the usual standard for THEMIS) are desired, then OCENTRIC must be specified in the MAPPARS value.
AUTOLON	AUTOLON specifies whether or not the longitude system for the output projected image should be automatically determined. When the PDS QUBE file is converted to ISIS format with "thm2isis", the user specifies the desired longitude system (0 to 360 or +/- 180) with the LONSYS parameter. (The desired longitude system is recorded in the LONGITUDE_SYSTEM label keyword in the ISIS_TARGET Group.) The AUTOLON parameter specifies whether or not "thmirmc" will attempt to make an automatic adjustment to the specified longitude system. When AUTOLON=YES is specified, then an automatic switch of longitude system is sometimes done to prevent generation of a large file that contains part of the image data on the left and part on the right with a large blank area in the middle. This occurs when the 0-360 longitude system was selected but the image data crosses longitude=0. This also occurs when the +/- 180 longitude system was selected and the image data crosses longitude=180. Specifying AUTOLON=NO will disable this automatic switching of longitude systems. This allows creating projected images with the specified longitude system when this is necessary for creating mosaics of multiple images (which must all have the same longitude system).
RETEST	When the RETEST parameter is set to the Null TAE parameter value, the "lev1tolev2" program computes the projection to Map 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.
LATRANGE	Latitude range of the desired output cube which will be produced by "geom". If the range is not entered then it will be automatically computed. If the range is entered then LONRANGE must be entered as well.
LONRANGE	Longitude range of the desired output cube which will be produced by "geom". If the range is not entered then it will be automatically computed. If the range is entered then LATRANGE must be entered as well.
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.
TRIM	TRIM determines if the lev1tolev2 program will trim (set to NULL) those parts of the output image that fall outside of the requested lat/lon boundaries. The default is NO. For more information, read the help for the lev1tolev2 program.
KMRES	KMRES is the map resolution of the output file in kilometers/pixel. Use this parameter if you will be mosaicking multiple THEMIS IR images together. The mosaic program requires that all files being mosaicked together have the same map resolution. If both KMRES and DEGRES are specified as the TAE Null parameter value, then the "lev1stats" program will determine the minimum average resolution of all bands in the input image and will use this as the default. If a value is entered for KMRES, then a value must not be entered for DEGRES.
DEGRES	DEGRES is the map resolution of the output file in pixels/degree. Use this parameter if you will be mosaicking multiple THEMIS IR images together. The mosaic program requires that all files being mosaicked together have the same map resolution. If both DEGRES and KMRES are specified as the TAE Null parameter value, then the "lev1stats" program will determine the minimum average resolution of all bands in the input image and will use this as the default. If a value is entered for DEGRES, then a value must not be entered for KMRES.
USEDEM	Determines if a DEM file will be used as a source for the local radius for each projected point. If USEDEM is YES, then the file specified by the DEM parameter will be used as a radii source. If USEDEM is NO, then the ellipsoid defined by the radii in the targdef file will be used instead.
DEM	This is a level 2 file to be used as a source for the local radius for each projected point. The default is to use $ISISDATA/mola_mars_planetary_radius.cub as a DEM file for Themis images. This file will only be used if the USEDEM parameter is YES.
OVERRIDE	This parameter is used to enter a grid spacing that will override the grid spacing computed by the "lev1tolev2" program. This parameter should not be used in most cases. If a tile in a cube is not projecting correctly because of undetected changes within the tile, then OVERRIDE should be set to force a finer grid. Valid values are 1, 4, and 16.