Help for MARSORTHO

PURPOSE:
To assemble multiple frames into a mosaic in orthographic projection. 
It takes either skin data asscoiated with XYZ data to generate ortho output, 
or it takes XYZ data to generate DEM. In order to generate ortho output, 
one-to-one correspondence is expected between XYZ and skin data. 
Moreover, every entry in skin list should be geometrically registered to 
every entry in XYZ list.

This is a multimission program. It supports and mission, instrument, 
and camera model supported by the Planetary Image Geometry (Pig) software 
suite.

The program provides the options to generate both dem and ortho outputs
in one execution. Dem and ortho outputs can also be generated individually.

The program provides different options to handle overlay areas for 
both ortho and DEM outputs. The overlay options include: 
    1. closest to camera (CLOSEST)
    2. average (AVG)
    3. minimum (MIN)
    4. maximum (MAX)
    5. first on top (FIRST)
    6. bottom on top (LAST)
For detailed information regarding overlay options, see parameter OVERLAY.

Radiometric correction is performed by default on integer inputs, 
and it may be turned off via the RAD keyword parameter. 
Radiometric correction is turned off by default on float inputs, 
and it cannot be turned on.

EXECUTION:

Note: For the usage examples below, if the command contains "...",
it means that command is incomplete. 

There are two ways to present INP input:
    1. marsortho inp=(a.img, b.img, c.img, ...) out=dem.img ...
    2. marsortho inp=ascii_listoffiles out=dem.img ...
where ascii_listoffiles is a text file created by Sybase or an editor,
containing the list of filenames to include in the mosaic, one per record.
Up to 200 input images can be listed.

There is only one way to present IN_XYZ input:
    1. marsortho inp=ascii_listoffiles1 in_xyz=ascii_listoffiles2 out=ortho.img ...
where ascii_listoffiles1 and ascii_listoffiles2 are the same as above. 
Every entry in ascii_listoffiles2 must be geometrically registered to 
every entry in ascii_listoffiles1.

OUT_DEM can be optional, and OUT can be optional, but at least one of 
them must be defined. For example:
    1. marsortho in_xyz out_dem=dem.img ... (correct)
    2. marsortho inp=img.lis in_xyz=xyz.lis out=ortho.img ... (correct)
    3. marsortho inp=img.lis in_xyz=xyz.lis ... (incorrect)

The program provides the following ways to define geometry.
    1. Define parameter NL. 
       If the parameter NL is defined, then SCALE (map resolution) will be 
       computed based on NL, and then NS will be computed based on SCALE and 
       MAXY and MINY (MAXY and MINY will be computed in the program). 
    2. Define parameter SCALE.
       If the parameter SCALE is defined, then NL and NS will be computed based
       on SCALE, MAXX, MINX, MAXY, and MINY (MAXX, MINX, MAXY, MINY will be
       computed in the program).
    3. Define both parameters NL and SCALE
       If both NL and SCALE are defined, then MAXX will be re-computed based on 
       NL and SCALE. 

The program has the capability of processing multi-bands INP inputs. All the 
bands can be processed at once, or each band can be processed individually. If 
BAND=N, then only that band will be processed. If BAND is not defined, then all 
bands will be processed. BAND is undefined by default to process all bands 
unless user explicitly defines it.
See the two usage examples below:
    1. Given that images in skin.lis contain 5 bands, and we only want to 
       process the second band.
           marsortho inp=img.lis in_xyz=xyz.lis band=2 out=ortho_band2.img ...
       By defining BAND=2, only band 2 will be processed, and the ortho output 
       will be a 1-band image.
    2. Given that images in skin.lis contain 5 bands, and we want to process 
       them all.
           marsortho inp=img.lis in_xyz=xyz.lis out=ortho_all_5_bands.img ...
       In order to have all the 5 bands get processed, all we need to do is left
       BAND to be undefined. The ortho output in this case will be a 5-bands 
       image.

Below are examples of complete commands for specific use cases:
    1. marsortho in_xyz=xyz.lis out_dem=dem.img dem_fill=5 nl=1000 -min

       The above command will use the images in xyz.lis to generate a DEM map 
       dem.img that has 1000 total number of lines with fill factor to be 
       (5 * 2 + 1) pixels. -min means when multiple points hit the same 
       position, the smallest value will be picked.
       For different options of handling overlay methods in DEM output, please 
       see parameter OVERLAY.

    2. marsortho inp=img.lis in_xyz=xyz.lis out=ortho.img NL=1000 
       brtcorr=example.brt -norad

       The above command will use the images in xyz.lis as coordinates and use 
       the images in img.lis as texture map to overlay on top of the 
       coordinates. The program will use example.brt generated by marsmap and 
       marsbrt to perform linear brightness correction. Parameter -norad will
       turn off the radiometric correction.

    3. marsortho inp=img.lis in_xyz=xyz.lis out_dem=dem.img out=ortho.img 
       nl=1000 dem_nodata=0 img_nodata=0 fill_size=5 -local -min

       The command above will use xyz.lis and img.lis to genereate DEM map 
       dem.img and ortho map ortho.img. Parameter nl sets the number of lines 
       for both dem.img and ortho.img. The number of samples will be calculated
       based on parameter scale which by default is 0.01, and the actual min and
       max values in xyz images. Parameters dem_nodata and img_nodata will set 
       the pixel values for the no data position for dem.img and ortho.img to be
       0. Parameter fill_size will set the fill size for dem.img and ortho.img 
       in pixels. Parameter -local will set the output frame to be local. -min 
       means in dem.img and ortho.img when multiple points hit the same 
       position, the smallest value will be picked. 

Index Files
-----------
Optionally, index (IDX and ICM) files can be output.  These collectively
identify what pixel from which input was used for each point in the mosaic.

The index file (IDX_OUT parameter) contains, for each pixel, a halfword
integer (16 bit signed) identifying which image the pixel came from.
0 indicates no value (black in the mosaic).  Numbers from 1-n match the
order of files in the input list file (or INP parameter, if a list file
isn't given).  For most mosaics, the file could be converted to byte using
CFORM (half is used to support more than 255 input files).

The ICM file (ICM_OUT parameter) is an Image Coregistration Map.  It is a
two-band float file containing the line, sample coordinate of the input
pixel used for the point.  This is the same basic format as correlation
maps such as MARSCOR3 produces, except that multiple images are involved
(thus the need for the index file).

HISTORY:
09-30-13  O. Pariser  Initial marsortho by O. Pariser, based on idl code from 
                      Jeff R. Hall
08-31-15  Steven Lu   Added SimpleImage support for better memory management. 
                      (replacing IBUF, FBUF, ...)
03-02-16  Steven Lu   Added support for radiometric and brightness correction.
03-02-16  Steven Lu   Added options to handle overlap areas.
03-02-16  Steven Lu   Added the capability of processing multiple bands.
07-24-16  Steven Lu   Added pixel-based fill implementation.
                      Added INPUT_RANGE capability.
                      Added morphologic erosion capability. 
02-10-17  Steven Lu   Changed RANGE parameter definition.
                      Added parameter CUT and CUT_TYPE.
09-06-17  Steven Lu   Added parameter Z_COORD
                      Added parameter Z_DIRECTION
                      Changed weighted fill to use camera resolution. 
10-06-17  Steven Lu   Added parameter FILL_FACTOR
                      Changed ERODE_FACTOR
11-21-17  Bob Deen    Added WRITE_COORD parameter
09-28-18  Steven Lu   Added IDX_OUT and ICM_OUT parameters.
10-31-18  Steven Lu   Added CAMERA_CENTER and PIXEL_ANGLE parameters.
12-10-18  Steven Lu   Fixed a bug for applying HSI brt corr when -NORAD is on.
04-21-20  Bob Deen/   Added elongated fill and erosion methods; 
          Steven Lu   OMP parallelization; Caching erosion kernel;

COGNIZANT PROGRAMMER: Oleg Pariser/Steven Lu

PARAMETERS: