tesmap Documentation

tesmap - Generate projected ISIS file from TES (vanna/vanilla) data

The easiest way is to provide the name of an existing level 2 image
cube in the INITFROM parameter.  The user can then modify many of the
projection characteristics using other input parameters.  The second
way is to completely provide all the information in input parameters.
The following is a list of projection parameters that can be used to
specify (INITFROM not provided) or alter (when INITFROM file is given)
projection characteristics:

TARGDEF  - The name of the target object from whence the data came.
           For example this can be "MARS", "EUROPA" or some other
	   supported planetary body.  It is typically only needed to
	   specify planet radii and the direction of postive longitude.
	   See $ISISDATA/targets for supported and recognized bodies.
	   This parameter is ignored if INITFROM is given, required if
	   its not given.
	
MAPPARS  - String to specify the name of the desired projection and any
           parameters specific to it as needed.  See the PDF description
	   in mappars.pdf. This file describes all supported ISIS
	   projections and their parameters.  This parameter is optional
	   if INITFROM is given and can be used to specify a completely
	   different projection.  It is required if INITFROM is not
	   given.  Example: "SINU:0,OCENTRIC".
	
LATRANGE - Use this parameter to set the minimum and maximum latitude to
           represent in the output projection.  All raster data that
	   falls outside this latitude range will not be included in the
	   output file.  If INITFROM is given, the ranges in this
	   projection are used.  It can be used to alter the latitude
	   range in INITFROM if so desired.  It is required when
	   INITFROM is not specified. Example: LATRANGE=(-40.5,-10.2)
	
LONRANGE - Use this parameter to set the minimum and maximum longitude
           to represent in the output projection.  All raster data that
	   falls outside this longitude rnage will not be included in
	   the output file.  If INITFROM is given, the ranges in this
	   projection are used.  It can be used to alter the longitude
	   range in INITFROM if so desired.  It is required when
	   INITFROM is not specified.  Example: LONRANGE=(10.5,45.0)

KM       - This parameter sets the resolution of the output projection
           in units of kilometers per pixel. Only one of KM or DEG can
	   be specified, not both.  One of KM or DEG is also required
	   for all runs of tesmap.

DEG      - This parameter sets the resolution of the output projection
           in units of pixels per degree.  Only one of DEG or KM can be
	   specified, not both.  One of KM or DEG is also required for
	   all runs of tesmap.
	
LATSYS   - This parameter is used *solely* to designate the latitude
           coordinate system LATRANGE parameter is specified in.  This
	   allows the user to specify these ranges in either
	   planetocentric or planetographic.
	
LONSYS   - This parameter is used *solely* to designate the longitude
           coordinate system LONRANGE parameter is specified in.  This
	   allows the user to specify these ranges in either -180 to 180
	   (180) or 0 to 360 (360) ranges.
	
The new ISIS geometry software, referred to as "Lev", has added
functionality for supporting different latitude and longitude
coordinate geometry.  LATSYS, LONSYS and LONDIR are used to specify
this information to ISIS geometry software so that projections can be
properly supported.

In the Lev software, there are 3 occurances of these parameters in one
form or another.  In tesmap there is one additional occurance in the
raster configuration file that I will describe below.

1)  LATSYS and LONSYS appear explicity in user interface PDF files.
    This is mostly limited to geometry initialization applications such
    as levinit.  tesmap also has these parameters.

    They are in level 2 (projection application) PDFs to notify the
    application which coordinate system input values are specified in.
    For example, LATRANGE require a minimum and maximum latitude range
    of representation.  LATSYS tells the application if the user
    provides them in planetographic (OGRAPHIC) or planetocentric
    (OCENTRIC) latitude coordinates.   LONSYS exists to notify the
    application how longitude ranges as specified in LONRANGE are
    specified.  They can range from -180 to 180 (180) degrees or 0 to
    360 (360) degrees.

2)  LATSYS and LONSYS are also found in the ISIS image cube labels in
    the IMAGE_MAP_PROJECTION keyword group.  LATSYS is stored in the
    KEYWORD_LATITUDE_TYPE keyword and used to establish subsequent user
    inputs and reported values.  LONSYS is stored in the
    LONGITUDE_SYSTEM keyword and specifies how longitudes are used and
    reported in subsequent ISIS applications.

3)  An equivalent to LATSYS is also used in the MAPPARS parameter for
    some projections.  This is of the form MAPPARS="SINU:0,OCENTRIC".
    Here, this notifies the Lev software the desired latitude system to
    used to compute physical storage locations (i.e., line/sample) for
    the geometric data.  Note that Simple Cylindrical and Sinusoidal
    projections can use both OCENTRIC and OGRAPHIC latitude coordinate
    systems to store data.  ALL OTHER PROJECTIONS USE OGRAPHIC!!

4)  The tesmap application needs LATSYS, LONSYS and LONDIR in the
    raster configuration file to fully describe these elements for each
    latitude and longitude coordinate read from the raster data file.
    These can be entirely different than the other sources - tesmap
    converts the raster geometry coordinates to whatever is needed for
    projection compatability.  LONDIR is an additional parameter used to
    specify the direction of positive longitude of the raster longitude
    geometry.

For tesmap to be thorough and perform correctly, all these
parameters must be considered carefully.  See also the mappars PDF in
the ISIS system for further information.

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az

Output rasterized level 2 cube
filename to create or add raster
data to

NONE

Optional input ISIS level 2
cube name used to initialize
projection and label parameters

--

input data file

NONE

Wavenumber of TES observation
0   - uses IMC mode
5   - 5  Wavenumber
10  - 10 Wavenumber

5

Name of file containing list
of SPICE kernel files

"$ISISMGSDATA/tes_kernels.def.2"

Comma delimited list of
fields to be extracted from
vanna/vanilla file.

Valid Forms:
name[12]  - extract 13 col with
            "name" as the
            reference field
bol[0:10] - extract fields 0
            through 10, or the
            first 11 fields.
	
Note that fields start with
index 0.

--

Choose detector selection
algorithm to apply to all
results.  This is used to
determine how to generate
the output pixel data
when one or more detectors
overlap the same output
pixel.

Valid Form:
OPERATOR="max(10)"
  Selects the detector whose
  value is the highest in the
  11th column.

OPERATOR="max(temp[10])"
  Same as above only names the
  11 column

OPERATOR="average"
  Averages all the overlapping
  detectors.  Note that this is
  not the same as DETMERGE=YES.

Note it can generally be
anything specific to a special
algorithm.

"avg"

Use merged detector set.
"YES" will average all fields
in detectors 1 through 6 or
however many exist.  "NO" uses
each individual detector to
map to the output file.

"NO"

Target definition filename
used only to establish planet
or body radii (level 2)

--

Map projection and parameters
(e.g. MAPPARS="SINU:0,OCENTRIC")

--

Latitude range

--

Longitude range

--

Image resolution (km/pix)
      or

--

Image resolution (pix/deg)

--

Latitude system used to report
values in:  OGRAPHIC or OCENTRIC
(default OGRAPHIC)

"OGRAPHIC"

Longitude system used to report
values in:
360 - 0 to 360
180 - -180 to 180
(default 360)

360

Prime meridian adjustment
offset in degrees

ADDITIONAL NOTES:

Parm	Description
TO	Name of the output cube file for the MODE="INIT" option. For the MODE="ADD" option is also the input file that the raster file will be added/merged to.
INITFROM	Optional name of an existing ISIS level 2 projected file which will be used to initialize the TO level 2 parameters. This is very useful if the goal is to produce a projected image for direct comparison to an existing product. tesmap will allow further modification to the projection through other input parameters. For example, you may have a data set that has a different pixel resolution that another product. You would like to compare the two products directly so it needs to have the same LATITUDE and LONGITUDE ranges and projection parameters. The only difference being the pixel resolution, the comparison product can be specified in INITFROM and the user can use KM or DEG to alter the pixel resolution. Once you have created the rasterized product at a different resolution, use the ISIS application "lev2tolev" to specify the same pixel resolution as the original product you wish to compare to. See also tesmap general help for further details on use of this parameter.
MODE	This parameter specifies the action for handling the output file specified in the TO parameter. tesmap can be used to create a new level 2 image completely from scratch using the "INIT" mode. The user must supply the following minimum parameters: TARGDEF MAPPARS LATRANGE LONRANGE KM or DEG The caller can provide the name of an existing ISIS level 2 projected file where all parameters are initialized from in the INITFROM parameter. The caller can also selectively change any aspect of the projection using the above parameters. The other option is to update an existing level 2 projected file using the "ADD" mode. The file specified in TO must exist and be a level 2 projected ISIS file. All parameters but CONFIG and UPDATE are ignored in this mode.
UPDATE	UPDATE provides users control over how raster data is added to the file. In may cases, data may map to the same line and sample. The user may decide to use the UPDATE="REPLACE" option which is essentially last-in precedence. The last value that maps into a particular line/sample replaces any value previously there. UPDATE="PRESERVE" has the opposite effect - it will honor any exist valid value and never replace it with any raster data that maps to the line/sample location. The last option, UPDATE="AVERAGE" is a compromise of the two options. This option creates a BAND suffix named "RASTER_COUNT" that accumulates the number of raster DN that maps to the line/sample locations and maintains a running average of this location. A "running average" is implemented in such a way that the final result is always readily available after a run of tesmap. This is acheived by taking the DN value at the line/sample location, multiplying it be the count of DN previously added to it, then adding in the incoming DN value and diving this sum by the old count plus one. The count is then incremented by one and rewritten to the backplane. There are several considerations to be aware of when this option is used. 1) When a file is initialized with this mode, it must be used for any subsequent tesmap run or incorrect results may occur. 2) Selecting this option for a file that was not originally initialized with option is allowed but it runs in a different mode. It will average any existing value with the incoming DN but does not maintain a running average. It will only average the two values. The problem with this technique is that the last value in will have far more weight if more than two values are averaged. 3) To disable this option, one can physically remove the RASTER_COUNT BAND suffix using the ISIS "dsk2dsk" application and applying an appropriate SFROM.
TARGDEF	This parameter is used to specify target parameters definitions such as radii, omega 0, etc... For tesmap, it is used only to define planet or body radii. This is essential for ISIS level 2 routines to compute latitude/ longitude and line/sample coordinates on the target body. This parameter is not needed if INITFROM is provided and it contains the desired target information. TARGEF can be provided as the name of a planet (e.g., MARS) in which case a file of the form "TARGDEF.def.n" will be searched for in the $ISISDATA/targets directory. "n" is the highest occuring number starting with 1. For example, if Mars is the desired target then the default value will be "$ISISDATA/targets/mars.def.n", "n" being the highest version found. Users can also specify an explicit file from which to initialize from. The format must follow the same as those in the $ISISDATA/targets directory and one of these files is a good starting point to developing your own. This parameter is needed only when creating new files (MODE="INIT") *and* INITFROM is not provided or is not of the desired target body.
MAPPARS	This parameter is used to specify the map projection and its specific parameters. For example, "SINU:0,OCENTRIC" implies Sinusoidal map projection with a central longitude of 0 and values reported in planetocentric coordinate systems. **NOTE** For a detailed explanation of MAPPARS, tutor the mappars.pdf (i.e., TAE> tutor mappars). This parameter is needed only when creating a new output file (MODE="INIT") *and* INITFROM is not specified or does not contain the proper projection parameters.
LATRANGE	Specifies the latitude range of the output projection. LATRANGE(1) is the minimum latitude, LATRANGE(2) is the maximum. The coordinates specified here are subject to the LATSYS parameter coordinate specification and must be expressed in the system specified in this parameter.
LONRANGE	Specifies the longitude range of the output projection. LONRANGE(1) is the minimum longitude, LONRANGE(2) is the maximum. The coordinates specified here are subject to the LONSYS parameter coordinate specification and must be expressed in the system specified in this parameter.
KM	This specifies the map resolution in kilometers/pixel.
DEG	This specifies the map resolution pixels/degree.
LATSYS	This parameter is used to define the latitude system computed by "lev1" programs. Valid values are either OGRAPHIC or OCENTRIC. The default is OGRAPHIC. Your selection is written to the labels of the cube or table file. This effects programs which output or use the latitude, for example, "qview", "lev1stats", "lev1tolev2". See also tesmap general help for a very detailed discussion on this and its associated parameters.
LONSYS	This parameter is used to define the longitude system computed by "lev1" programs. Valid values are either 180 or 360. The default is 360 which implies longitudes will be output in the range of 0 to 360. The value 180 implies longitudes will be output in the range of -180 to 180. Your selection is written to the labels of the cube or table file. This effects programs which output or use the latitude, for example, "qview", "lev1stats", "lev1tolev2". See also tesmap general help for a very detailed discussion on this and its associated parameters.
PMEROFF	This parameter allows the user to make adjustments to each longitude value to adjust for differing prime meridian values. TES is one example where this parameter is useful. TES used IAU 1994 prime meridian values to compute longitudes. When attempting to compare/overlay TES data to MGS MOC or MOLA data, the longitudes more than likely were computed using a different prime meridian for MARS. By simply providing the difference between the prime meridians for each instrument, TES can be better aligned with MOC or MOLA. This value is *added* to each longitude prior to mapping to an output pixel location. It is assumed to in units of degrees.