Help for MARSCOORDTRANS

PURPOSE:

This program will translate mosaic coordinates from one form into another.
The coordinates can come from parameters or a file, and may be output to
parameters, a file, or stdout.

Coordinates
-----------

The program works with three types of coordinates:  INPUT, MOSAIC, and
PROJECTION.  MOSAIC coordinates are always used; they can be converted to
or from either of the other two types.

INPUT:  These are line/sample coordinates in the input files.  INPUT
coordinates are expressed as a triplet of (image_number, line, sample).
All values are 1-based, so (3.0, 1.0, 1.0) means the upper-left corner of
the third input image.  Note that the image number is expressed as a float
for consistency with the other modes, although it will always be an integer.

MOSAIC:  These are line/sample coordinates in the mosaic file.  MOSAIC
coordinates are 1-based, so (1.0, 1.0) refers to the upper-left corner of
the mosaic.  They are in the order (line, sample).

PROJECTION:  These are the projected world-space coordinates, expressed in
the mosaic's coordinate system (unless overridden by COORD et al).  For
Cylindrical and Polar projection, PROJECTION coordinates are expressed as
(azimuth, elevation) in DEGREES.  For Vertical projection, they are expressed
as (X, Y).

Thus there are four modes, selected by the DIRECTION and COORD_TYPE keywords:

-from_mosaic -input      : MOSAIC -> INPUT
-to_mosaic -input:       : INPUT -> MOSAIC
-from_mosaic -projection : MOSAIC -> PROJECTION
-to_mosaic -projection   : PROJECTION -> MOSAIC

Note that for MOSAIC->INPUT, the result is not necessarily unique, as the
point could have come from any of several overlapping inputs.  By default
only the first matching input is reported; this matches the stacking order
used to create the mosaic.  If you wish to see all possible inputs, specify
-MULTI.


Coordinate Systems
------------------

The standard PIG COORD parameter set is used to specify the coordinate system
in which the PROJECTION coordinates are accepted or reported.  Use of these
parameters does not change the mapping of the mosaic, only the reporting.
So for example, a poor man's translation from SITE to ROVER frame could be
effected by running this program once with -site -projection -to_mosaic,
and feeding the results back into another run using the same mosaic with
-rover -projection -to_mosaic.

Input Image Files
-----------------

Obviously, the input mosaic must always be provided via the MOSAIC parameter.
Cylindrical, polar, and vertical projections are supported.  Projection
information is derived from the label; however, these values can be overridden
by SCALE, LEFTAZ, etc. (this should rarely be needed).

If INPUT coordinates are used, the input files used to make the mosaic must
be supplied.  The input files should generally match what was used to make
the mosaic, but that is not a requirement.  It is possible to provide a
subset of images, or even completely different ones.  However, if different
images are provided, the features in the mosaic may not match the features in
the input, as the transform is mathematical and not feature-based.  Any small
difference in pointing would be apparent.

In order to truly match the inputs, the nav file used to originally make the
image must also be supplied.  The surface model and projection parameters are
obtained from the mosaic and should not be specified.

Input image files are not necessary if PROJECTION coordinates are used.

Input and Output of Coordinates
-------------------------------

There are two ways of supplying input coordinates: by parameter or by file.

Parameter input uses the IN_COORDS parameter.  This parameter is simply a
list of 2-item (or 3-item for INPUT coords) coordinate values, one after
the other.  For example, converting the two points (50, 33.2) and (102.1, 27)
would be specified via:

    in_coords=(50, 33.2, 102.1, 27)

Thus in_coords contains 2n (or 3n for INPUT) values, where n is the number
of points to convert.

For an input file, provide the filename in the IN_FILE parameter.  File
formats are discussed below.

Note that it is possible to use both IN_COORDS and IN_FILE.  IN_COORDS
are translated first, followed by IN_FILE.  Both end up in all output methods.
However, this is not possible for the TWOLAYER file format; to use that,
IN_COORDS must not be specified.

There are three methods of output:  printing, parameter, or file.

Printing is simply that:  the translated coordinates are printed to stdout.
This occurs unless -noprint is specified.  Each coordinate will be printed
on its own line.

File output writes the results to a file, in the same format as the input
file.  The formats are discussed below.  This mode is active if a filename
is specified in OUT_FILE.

Parameter output uses the TAE parameter output facility.  This mode may be
useful for running the program from a script.  For efficiency reasons,
parameter output is not used unless -USE_PARM is specified.

Note that any or all of the output modes may be used simultaneously.

Coordinate File Formats
-----------------------

There are two file formats supported:  a simple list of coordinates ("-flat"),
or one with prepended counts ("-twolayer).  The same format is used for
input and output files.

In either case, coordinates are presented one per line and separated by
spaces, e.g.

50.0 33.2
102.1 27.0

For INPUT coordinates, there will be 3 values per line.

In the case of MOSAIC->INPUT only, and if -MULTI is specified, then there
can be more than one set of coordinates per line, indicating multiple matches.
All matches will be printed on the same line.  This means that lines will
exactly match between input and output files.  It is also possible in this
mode for the coordinate to map to none of the input images; in this case a
blank line is output.

A -FLAT file is simply a list of coordinates as specified above.

A -TWOLAYER file has coordinates broken into sets.  Each set is prepended
by an integer saying how many coordinates are in that set.  The entire file
is prepended by the number of sets.  Thus the file might look like:

3
2
50.0 33.2
102.1 27.0
3
12.5 9.0
10.0 1004.0
33.1 42.0
1
57.0 1020.0

The first 3 indicates there are 3 sets; the first has 2 entries, the second
3, and the last 1.

TWOLAYER output requires the input also come from a TWOLAYER file; input from
parameters is not supported.  (parameters input to a FLAT file is allowed).

EXECUTION:

Convert mosaic coordinates to projection, input via params, output to screen:

marscoordtrans mosaic=mosaic.img in_coord=\(50, 33.2, 102.1, 27\)
   -from_mosaic -projection

Convert mosaic coordinates to input, using files:

marscoordtrans mosaic.lis mosaic.img mosaic.nav in_file=coord_list.txt
   out_file=coord_out.txt -from_mosaic -input -noprint -twolayer

OPERATION:

The program sets up the input images a la marsmap, and the input mosaic as in
marsunmosaic.  It then loops through all coordinates provided, runs them
through the appropriate math exactly like marsmap or marsunmosaic, and
outputs the results.

NOT IMPLEMENTED YET:

Override of mosaic surface model via parameters
Output via out_coords parameter


HISTORY:

  2005-11    rgd - Original version, derived from marsmap and marsunmosaic.
  2017-09    jpr - Added support for polar and vertical projections.
  2019-03-21 jpr - IDS-7886 - Fixed math errors in marscoordtrans.
  2019-10-02 wlb - IDS-7926 - initialized some variables.
             Commented some unused variables.
	     Added a test script and log.
  2020-02-04 wlb - IDS 7929 - null-terminated a string.
  2020-03-05 wlb - IDS 7927 - replaced sprintf calls with snprintf.

COGNIZANT PROGRAMMER:  Bob Deen