Help for NIMSCMM2

PURPOSE & METHOD
----------------

 NIMSCMM2 creates a NIMS Merged Mosaic (MM) or "cube file" from one or
 more GLL Phase-2 EDR files, in a non-interactive (batch) mode.  It is
 the Phase-2 version of NIMSCMM, which includes all the products of the
 Main Mission and later stages at Jupiter, but does not include the
 earlier phases: Venus, Earth-1, Earth-2, Gaspra and Ida.  Processing
 of data for the latter phases requires program NIMSCMM, which is no
 longer supported.

 In addition to the cube, a "cocube" containing supplementary (mainly
 geometrical) information is produced, see parameter COCUBE.  

 The output DNs are computed by binning the input pixels, computing
 the weighted mean in case of overlap.  (The weights are saved in a
 weights file, see parameter WTFIL).  There are two binning algorithms,
 nearest-neighbour and footprint, see parameter BIN.  A discussion of
 the weighting algorithm is given under HELP WTFIL.
EXECUTION
---------
 The command line syntax for NIMSCMM2 is:

 NIMSCMM2 EDR CUBE TARGET PROJ [optional parameters]

 The following is a list of the required parameters:

 EDR specifies up to 25 input EDR files.

 CUBE specifies the name of the primary output file containing the NIMS
 cube.

 TARGET specifies the name of the astronomical body being observed.

 PROJ specifies the desired map projection.  Valid projections are
 Mercator, Simple Cylindrical, Normal Cylindrical, Sinusoidal, Lambert,
 (Polar) Stereographic, (Polar) Orthographic, and Perspective (or "Point
 Of View").

 All other parameters are formally optional.  However, in practice, in
 order to generate a projected cube, the following will be required:
 - PCKERNEL or AACSFILE
 - SPKERNEL
 - CALFILE
 - DARKFILE
 - DBMFILE (if the observation is in the booms)
 - IKERNEL (for a few cases where the default is not optimal).

 How to determine and obtain these files is described under Tutor in the
 Help section for the individual parameters.  In general, a good starting
 point is to examine the parameters that were used in the cube that was
 delivered to PDS by the MIPL Systematic Processing facility.  These can
 be found (as of 19 June 2008) at the following on-line URL:
 http://www-pdsimage.jpl.nasa.gov/resources/onlineData.html
 (Under "Sorted by Mission", click on "NIMS CUBEs".)  When you find the
 cube of interest, the History portion of the headers gives the files used
 to generate that cube.

 An example of a typical cube generation run of NIMSCMM2 under the current
 MIPL configuration is given at the end of the test procedure tstnimscmm2.pdf.
 Special Pixel Values

 NIMSCMM2 uses a scheme borrowed from the ISIS system to flag pixels
 with unusual circumstances.  These pixels are assigned values at the
 extreme low end of the numerical range of the data format used by the
 cube.  For integer data, this is not a problem, as long as the
 platform on which the program runs supports the two-byte integer
 format assumed by NIMSCMM2.  However, for floating-point data, the
 values used for these special pixels are platform-dependent, which
 violates the VICAR rule that its files be readable on any supported
 platform.  In particular, a cube generated on a platform using IEEE
 floating-point format (Sun, HP, Mac, PC, X86/Linux) will not be
 readable (at least as far as the special values are concerned) on
 one using the VAX format (Alpha, VAX), and vice versa.  Although
 this is an undesirable situation, it is tolerated because currently
 the best 3-D cube display software exists in the ISIS system (CV
 on Unix, QL3 on VAX/VMS).  Note that program VISIS2 is required to
 convert a VICAR NIMS cube to ISIS format.
 The following cases are flagged by special values in ISIS:

Minimum valid:  this is the minimum value which is considered a valid
 data item;  anything smaller is considered to be a special pixel,
 which is in some way invalid.  (Note that not all the values in the
 special-pixel range are actually in use, as gaps have  been left 
 intentionally for possible future use.)

Null:  this signifies that no valid data exist at this point.

High Instrument Saturation:  the instrument's signal was at the top
 end of its scale, so the signal is not a reliable measure of the
 quantity being detected, but only a lower limit to it.  For NIMS,
 this is 1023 DN.

Low Instrument Saturation:  the instrument's signal was at the bottom
 end of its scale.  For NIMS, this is 0 DN;  however, since it is not 
 possible for NIMS to observe a valid 0 DN because of the dark offset 
 added to the signal (0 DN means missing data), this value is not used
 by this program (but is included in this text for completeness).

High Representation Saturation:  the signal would exceed the top end of 
 the range of the data format used to represent it, i.e., 32767 for 
 halfword integer and of the order of 10^38 for floating-point.

Low Representation Saturation:  the signal would fall below the bottom 
 end of the range of the data format used to represent it, i.e., -32768 
 for halfword integer and of the order of -10^38 for floating-point.

 Since it is impossible for NIMS data to achieve the Representation
 Saturation values, these will never be encountered in NIMS cubes, and
 are not supported by this program.
 The following values are used for the data types supported by this 
 program:

			VAX floating-	IEEE floating-
		Integer	   point	  point

Min.Valid:	-32752     FFEFFFFF	  FF7FFFFA

Null:		-32768     FFFFFFFF	  FF7FFFFB

High Ins.Sat:	-32765     FFFCFFFF	  FF7FFFFE

Low Ins.Sat:	-32766     FFFDFFFF	  FF7FFFFD

 The floating-point values are defined by bit strings, hence are given
 in hex in the above table.  The actual values are of the order of
 -1.7014e38 for VAX and -3.4028e38 for IEEE.

INITIAL VERSION: L. W. Kamp, 5-Dec-1994

COGNIZANT PROGRAMMER: W. L. Bunch

REVISIONS:
  2015-02-24 WLB Removed VMS support. Added enable/disable-log to
                 tstnimscmm2.pdf. Fixed 64-bit bugs. Added missing headers.
  2019-06-14 WLB IDS-7924 - Fixed erroneous format directives.
  2019-08-01 WLB IDS-7923 - Replaced sprintf calls with zvnsprintf. Misc -Wall cleanup.
                 There remain 291 incompatible pointer type warnings and 39
		 implicit function definitions.
  2019-09-06 WLB IDS-7922 - Initialized some variables.
  2020-03-19 WLB IDS-8260 - Changed input buffer type for obscuration map from LOGICAL to INTEGER. Enhanced unit test.

PARAMETERS: