thmvismc Documentation

thmvismc - Generate THEMIS VIS registered map projection cubes
OVERVIEW

This procedure processes Level 1 (radiometrically calibrated)
ISIS-formatted THEMIS VIS 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.

Within each input band, each VIS framelet is projected independently
and the results are then mosaicked together.  If averaging of
overlap areas is not specified with the AVERAGE parameter, then
the TOP parameter allows specifying whether earlier or later
framelets are put "on top" in the output band mosaic.  The MOSSAT
and MOSALL parameters allow control over handling of Saturated
and NULL values during the mosaic operation.

The LREMOVE and RREMOVE parameters allow discarding columns of the
input file that do not contain useful data.  The TREMOVE and BREMOVE
parameters allow discarding lines at the top and bottom of each
input framelet that do not contain useful data.  (Lines at the top
of the top framelet or the bottom of the bottom framelet are not
discarded.)

Note that each framelet is projected independently, and the default
processing option specified by the RETEST parameter could result
in corners of each framelet getting chopped off.  In particular,
when the observation used a SPATIAL_SUMMING of 2 or 4, it might
be necessary to use the RETEST parameter to specify a smaller
grid size for the projection computation to prevent unacceptable
loss of input data.


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-projection of THEMIS VIS cubes: thmvismc.pl, thmvismc_batch.pl

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

There are two different ways to run each script (as seen below).
If you want to save most of the intermediate files created during
the map projection process, then the scripts must be run with the
-delete=no option. The intermediate files are very useful when
tracking down problems. Normally, you will not need to save the
intermediate files.

The syntax for processing a single file and saving the intermediate
files is as follows:

thmvismc.pl -delete=no from [to] [sampinc] [lineinc] [mappars] [retest]
  [inttype] [minvals] [mossat] [mosall] [average] [top] [lremove]
  [rremove] [tremove] [bremove] [trim] [kmres] [degres] [dem] [usedem]
  [override]

The syntax for processing a single file and deleting the intermediate
files is as follows:

thmvismc.pl from [to] [sampinc] [lineinc] [mappars] [retest]
  [inttype] [minvals] [mossat] [mosall] [average] [top] [lremove]
  [rremove] [tremove] [bremove] [trim] [kmres] [degres] [dem] [usedem]
  [override]

The syntax for processing a list of files and saving the intermediate
files is as follows:

thmvismc_batch.pl -delete=no fromlist [sampinc] [lineinc] [mappars]
  [retest] [inttype] [minvals] [mossat] [mosall] [average] [top]
  [lremove] [rremove] [tremove] [bremove] [trim] [kmres] [degres] [dem]
  [usedem] [override]

The syntax for processing a list of files and deleting the intermediate
files is as follows:

thmvismc_batch.pl fromlist [sampinc] [lineinc] [mappars] [retest]
  [inttype] [minvals] [mossat] [mosall] [average] [top] [lremove]
  [rremove] [tremove] [bremove] [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), save all intermediate files, and set the sample
increment (sampinc) to 10:

thmvismc.pl -delete=no 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 thmvismc.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 7 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#f#.cub      = A single-band single-frame file containing
                         band number # and frame number # from the
			 input file.
corename_b#f#_gm.cub   = This is the single-band single-frame file
                         containing band number # and frame number #
			 from the input file after it has been geomed.
corename_b#mos.cub     = This is the single-band multi-frame file
                         containing band number # and all frames from
			 band number # mosaicked together.
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.


PROCESSING SUMMARY

The following is a brief summary of the major processing operations
performed by the PERL script for each input file:

  1. Create temporary files that contain each individual framelet
     for each input band
  2. Run "lev1stats" to examine each temp file to determine overall
     range of latitude/longitude and default output resolution
  3. Run "lev1tolev2" and "geom" to project each framelet
  4. For each band, run "mosaic" to mosaic all framelets together
     for the band
  5. Run "cubeit" to combine all the single-band mosaics into
     a multi-band output cube

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)

--

Delete intermediate files?
  (YES, NO)

YES

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

Mosaic saturated values?
  (YES, NO)

NO

Mosaic NULL data?
  (YES, NO)

NO

Average the framelet overlap
  during mosaic?  (YES, NO)

NO

Mosaic later framelet on top?
  (YES, NO)

YES

Number of columns to remove from
  left side of input image

6

Number of columns to remove from
  right side of input image

10

Number of rows to remove from
  top of each framelet

0

Number of rows to remove from
  bottom of each framelet

0

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

NO

Output image resolution
(km/pix)
      or

--

Output image resolution
(pix/deg)

--

Use 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 VIS 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 ".vismc.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 ".vismc.cub" appended.
DELFILES	When DELFILES=YES, all intermediate files created during the map projection process will be deleted upon completion of the output file. If DELFILES=NO, then most of the intermediate files will not be deleted. Specifying DELFILES=NO will allow examining the individual projected framelets before all framelets for a band are mosaicked together. The equivalent to this parameter on the PERL script command line is the -delete=no option. If this option is missing on the command line, then all intermediate files will be deleted (the default). If this option is present, then most intermediate files will not be deleted.
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).
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.
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. Note that each VIS framelet is projected independently. Thus, each corner of each framelet could potentially be chopped of if the grid spacing for computing the projection is too coarse. In particular, when the SPATIAL_SUMMING mode (2 or 4) is used, the size of individual framelets is smaller, and it might be necessary to use the RETEST parameter to specify a grid spacing that is small enough to prevent unacceptable loss of data in the corners or edges of the framelets.
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.
MOSSAT	MOSSAT determines whether the "mosaic" program will move High and Low Saturated pixels from the input file into the mosaic file when mosaicking all projected framelets for a band together. For more information, read the help for the "mosaic" program.
MOSALL	MOSALL determines whether the "mosaic" program will move NULL pixels from the input file into the mosaic file when mosaicking all projected framelets for a band together. For more information, read the help for the "mosaic" program. NOTE: When TOP=NO, MOSALL will be set to NO.
AVERAGE	AVERAGE determines whether the "mosaic" program will average instead of overlaying projected framelets when mosaicking all framelets for a band together. For more information, read the help for the "mosaic" program.
TOP	TOP determines whether a framelet will be mosaicked "on top" or "underneath" when individual projected framelets for a band are combined. Since framelets are processed from the top of the input file (earlier) to the bottom of the input file (later), TOP=YES means that a later framelet will be "on top of" an earlier framelet in their area of overlap. For more information, read the help for the "mosaic" program.
LREMOVE	LREMOVE allows you to discard columns (samples) from the left side of the input cube as it is processed.
RREMOVE	RREMOVE allows you to discard columns (samples) from the right side of the input cube as it is processed.
TREMOVE	TREMOVE/BREMOVE allow you to discard rows (lines) from the top/bottom of each input framelet as it is processed. No lines will be discarded from the top of the top framelet or the bottom of the bottom framelet.
BREMOVE	TREMOVE/BREMOVE allow you to discard rows (lines) from the top/bottom of each input framelet as it is processed. No lines will be discarded from the top of the top framelet or the bottom of the bottom framelet.
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. 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 VIS 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 VIS 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.