Help for VISIS2

PURPOSE:

 VISIS2 provides transformations from NIMS systematic VICAR files to a NIMS
 ISIS Cube file and from a NIMS ISIS Cube file to VICAR files.


EXECUTION:

There are two transformation modes, Forward and Backward, for which the
command lines are, respectively:
 
VISIS2 ( 2DHIST [,SPECPLOTS] ,VCUBE ,COCUBE [,SIICUBE] ) ICUBE  [HISTFILE]

VISIS2  ICUBE  ( 2DHIST [,SPECPLOTS] ,VCUBE ,COCUBE [,SIICUBE] )  [HISTFILE]

where	2DHIST is a VICAR 2-D histogram file produced by HIST2D; 
	SPECPLOTS are zero to six spectrum files produced by SPECPLOT; 
	VCUBE is the primary VICAR cube (merged mosaic) produced by NIMSCMM2;
	COCUBE is a VICAR cube of supplementary data produced by NIMSCMM2;
	SIICUBE is a VICAR cube file of "spectral index" images;
	ICUBE is an ISIS-format PDS-labelled cube;
	HISTFILE is an ascii text file containing an ISIS History object;
	and square brackets, [], denote optional items.
	Other parameters are described under Help or Tutor.

NOTE:  A simplified way to run VISIS2 is provided in the proc RVISIS2.PDF,
which is delivered with this program.
Description of NIMS ISIS Cube File

The NIMS ISIS cube file consists of 512-byte records.  Following the PDS
(Planetary Data Standard) "object-oriented" convention, this cube consists 
of the following objects, each of which is described in the label object
(the first object):

1. A label object of ASCII data describing the cube, using only PDS-standard
keywords.

2. A history object of ASCII information giving a processing history of the 
cube.  This object may contain non-standard (program-specific) keywords,
although they should follow general PDS conventions.  When VISIS2 is run
in Backward mode, thie HISTFILE parameter should be specified in order to 
preserve this object, which contains any ISIS processing that has been done 
on the cube, as this will not show up in the VICAR history labels.

3. A 2-D histogram object (containing the 2-D histogram input file, excluding
its VICAR label) of BYTE data format, with dimensions 256x408

4. Zero to six spectrum objects (containing the Spectrum input files data),
of nibble (4-bit) data format, with dimensions 340x500, 

5. A 3-D "Qube" object of varying dimensions.  This object contains the 
input VICAR cube data (which may be of HALF or REAL data format), with the 
Co-cube and Spectral Index Cube (if any) appended as backplanes to the cube 
(these backplanes are always of REAL data format).  The Qube object has a 
band-sequential (BSQ) data organization, meaning that data follow a band-
line-sample hierarchy of organization.
NOTE ON ISIS PROCESSING OF CUBES WITH POINT PERSPECTIVE PROJECTION.

The ISIS labels that this program generates should be fully compatible with
the current ISIS software system.  However, it should be noted that the
Point Perspective projection used in many NIMS cubes has two problems in
ISIS:

1. The labels made by VISIS2 for this projection are not readable by all ISIS
 programs and must be corrected by running the ISIS program FIXLUCAS.

2. The ISIS version of the Point Perspective projection (as implemented in
 program NUPROJ) is different from that in VICAR, in that it is for the Vertical
 Perspective only, whereas VICAR's is a Tilted Perspective.  These give different
 results when the optical axis intercept point does not pass through the
 sub-spacecraft point.  However, tests have shown that the difference is not
 great for most cases, so reasonable results may be obtained using NUPROJ on
 such cubes if errors of a few pixels are acceptable.

ERROR HANDLING FOR VICAR LABEL ITEMS NOT FOUND 

When generating an ISIS cube file from VICAR format files, label items needed
for the PDS label of the cube file are retrieved from the VICAR labels of the 
input files and the NIMS CATALOG PROCESSING domain.   If an item cannot be 
found in the VICAR label, three courses of action are used for various types 
of label items.  If the item is a RIM value or a date/time value, the digit 9 
is used to fill the value.  If the item is a temperature, the value is set to 
zero.  In all other cases, the character 'x' is used to fill the value.
PROGRAM HISTORY:

Program VISIS written by: Justin McNeill, October, 1989

Current cognizant programmer: W. Bunch

Revisions: 
  1994-12-10 LWK Ported to Alpha, converted to GLL Phase 2 requirements, and renamed VISIS2
  1995-02-10 LWK added Sybase interface
  1995-09-11 LWK VISIS2 extended to support Phase 0 also;  VISIS will not
		be ported separately.
  1995-09-19 LWK fixed error that caused WAVELENGTHS, etc., to be missing;  added
	     pointing source & start/stop sub-solar label items;  added 1 to map
	     offsets per PDS def'n;  fixed slew_tol in inverse mode
  1995-11-28 LWK fixed code for East Long. determination 
  1995-12-14 LWK MOSNUM is now in phase-1 label too
  1996-01-10 LWK fixed East Long. determination in inverse mode
  1996-02-16 LWK fixed NATIVE_..._TIME mf format; band_bin mode determination;
             zlgets for DRK_AVE and RAD_SENS; North Angle is mpNORTH_ANGLE, not
             mpCARTESIAN_AZIMUTH for Perspective;
  1996-02-21 LWK Corrected SSC and OAL Line/Samps in inverse mode:  the label 
             items are _offsets_ (relative to 1,1), although the MP items 
             are not!
  1996-02-28 LWK initialize astretch[] & r/g/b_siid items to prevent illegal
             floating-point errors
  1996-03-06 LWK fixed NATIVE_..._TIMEs again to avoid embedded blanks
  1996-03-20 LWK- minor fixes to avoid Unix build warnings
  1996-03-23 LWK Removed JR/JSA Target Id's per PDS decision.
  1996-05-10 LWK Added BAND_BIN_SELECTED_BAND label array;  allow for variable 
		number of backplanes due to deselected GP's.
  1996-06-29 LWK removed underscores from NEAR_INFRARED_MAPPING_SPECTROMETER ISIS
             label item
  1996-08-06 LWK ensure OBSNAME is zero-terminated;  changed waves arrays since
             NIMSCMM2 now gives array after WET deselection
  1996-08-15 LWK- fixed special values in floating-point case (missing final #,
             and low/hi instr.rep. keywords)
  1996-08-25 LWK added BAND_MASK to output cube label in inverse mode
  1996-08-27 LWK Removed BAND_BIN_SELECTED_BAND, changed BAND_BIN_ORIGINAL_BAND
		to the latter's definition.
  1996-09-11 LWK fixed error in COORDINATE_SYSTEM_NAME when Planetocentric
  1996-09-27 LWK Removed all planetocentric/detic latitude conversions, because
             NIMSCMM2 now writes either one consistently.
  1996-10-05 LWK removed underscores (_) from keyword names inside comment NOTES
             to avoid the parser confusing these with the keywords themselves
             in inverse mode
  1996-10-09 LWK added photometric correction cutoff
  1996-10-31 LWK allowed multiple Cal files; added min/max central body label items
  1996-11-05 LWK added grating correction and instrument threshold label items;  
             changed min/max "target_center" distances to "slant"
  1996-11-08 LWK fixed POINTING_OFFSET label item
  1997-02-28 LWK added PHOTOMETRIC_CORRECTION_NOTE, moved POINTING_OFFSET to next
             to other pointing stuff (in History) per RM request
  1997-05    LWK changes to support intermediate processing by ISIS NIMSGEOM
		on MIPS Systematic cubes:  added GR_POS_nn_RIGHT_EDGE_PROJ_LINE
		and -SAMPLE backplanes in Footprint tubes;  added parameter
		HISTFILE and the capability of storing ISIS history labels;
		fixed long-standing bug whereby GR_POS_nn_PROJECTED_LINE & 
		-SAMPLE backplane names were interchanged in the 
		BAND_SUFFIX_NAME array (!)
  1997-05-13 LWK changed SUB_SOLAR_AZIMUTH to SOLAR_AZIMUTH; put a copy of
             POINTING_OFFSET back into Label so that ISIS s/w can access it
  1997-05-15 LWK added GR_POS_nn_RIGHT_EDGE_PROJ_LINE/SAMPLE backplane names in 
             footprint tube;  increased LABELMEMORY (from 60000 to 72000) to
             acommodate extra backplanes
  1997-05-22 LWK fixed bug whereby the GR_POS_nn_PROJECTED_LINE & _SAMPLE 
             backplane names were interchanged in the BAND_SUFFIX_NAME array;
             move STD_DEV_SELECTED_BACKPLANE from history to label in order to
             make it available to ISIS label routines
  1997-05-27 LWK added Lommel-Seeliger photometric correction;  removed reference
             to tube/cube in "Qube structure" label comment
  1997-05-29 LWK fixed NATIVE_START/STOP_TIME format in inverse mode for cube
             output, removed these from 2D-hist and specplots;  added parameter
             HISTFILE and the capability of storing ISIS history labels
  1997-06-01 LWK get obsext/mosnum from qube name in inverse mode and write them
             to vicar label, so that a following forward-mode run will be able
             to retrieve them (needed for catalog lookup)
  1997-07-10 LWK save list of cube history tasknames and use these to add to
             the ISIS VICAR history
  1997-08-08 LWK added quotes to Lommel-Seeliger keyword (for Unix ISIS)
  1997-09-14 LWK label changes (NATIVE_TIMEs in quotes, most _NOTEs converted
             to comments) requested by PDS;  fixed conversion of NATIVE_TIME in
             inverse mode:  make get_string_value ignore double quotes (");  
             omit single quotes (') from OBSERVATION_NAME
  1997-09-16 LWK remove quotes from NATIVE_TIMEs for now, in order to give ISIS
             s/w a chance to prepare for this
  1997-09-20 LWK added SPECIALP parameter and SPECIAL_PROCESSING label stuff
  1997-10    LWK changed SINUSOIDAL to 'SINUSOIDAL_EQUAL-AREA' in Map proj'n type
             to satisfy ISIS; write true GP in the GR_POS_nn tube backplanes;
             changes for Unix ISIS compatibility:  added EAST/WESTERNMOST_LONG
             keywords (redundant with MINUMUM/MAXIMUM);  added OFFSET_DIRECTION,
             with switch of signs in LINE/SAMPLE_PROJECTION_OFFSET when TO_ORIGIN;
             also, LINE/SAMPLE_PROJECTION_OFFSET should *not* have 1 added if
             obtained thru MP calls, as those are already relative to (1,1)
             (since jan'94) -- only if mpo2buf/buf2mpo used, and for Perspective,
             where PLANET_CENTER_LINE/SAMPLE are not offsets;  only convert
             Longitudes if POSITIVE_LONGITUDE_DIRECTION needs to be changed!
  1997-10-01 LWK added SUPPNOTE, combined all qube NOTEs into one; removed NOTEs 
             from 2D-Hist and Spectra in inverse mode;  revised SPECIAL_PROCESSING 
             comment per RM intructions and moved it to the label (after the _TYPE 
             item)
  1997-10-06 LWK don't write geometry blackplanes and many label items for 
             CALIBRATION data;  fixed a few label bugs in inverse mode (SCET format,
             GRATING_STEPS/DELTA)
  1997-10-15 LWK add single quotes (') back to OBSERVATION_NAME since these begin 
             with a numeric from C10 on;  not double quotes, since this item is a
             "literal", not a "string" (PDS distinction!)
  1997-10-16 LWK changed SINUSOIDAL to 'SINUSOIDAL_EQUAL-AREA' in Map proj'n type;
             write true GP in the GR_POS_nn tube backplanes
  1997-10-19 LWK changes for Unix ISIS compatibility:  added EAST/WESTERNMOST_LONG
             keywords (redundant with MINUMUM/MAXIMUM);  added OFFSET_DIRECTION, with
             switch of signs in LINE/SAMPLE_PROJECTION_OFFSET when TO_ORIGIN;  also,
             LINE/SAMPLE_PROJECTION_OFFSET should *not* have 1 added if obtained 
             thru MP calls, as those are already relative to (1,1) (since jan'94)
             -- only if mpo2buf/buf2mpo used, and for Perspective, where 
             PLANET_CENTER_LINE/SAMPLE are not offsets;  only convert Longitudes
             if POSITIVE_LONGITUDE_DIRECTION needs to be changed!
  1997-10-05 LWK added RADIANCE_FACTOR to core types
  1997-10-29 LWK added MAXIMUM_PIXEL_DISTORTION label item, and comments 
             describing the footprint algorithm and label items
  1997-12-09 LWK write TO_ORIGIN keyword to label for Perspective too!  added 
             TO_ORI parameter to allow user to correct for cubes made without this;
             support B_AXIS_RADIUS in inverse mode (mpbuf2mpo uses this only for
             POV case, so should really convert to pure MP calls if this is 
             significant for other projections)
  1998-02-13 LWK fixed precision of NATIVE_..._TIME conversion;  allowed multiple
             dark files (for NIMS98 calibration)
  1998-02-15 LWK partially re-enabled quotes around NATIVE_..._TIMEs, since ISIS 
             is now supposed to be able to handle this -- however, for now just
             write spaces where the quotes will go, as a safer course (this allows
             simple hand-editing);  write CUBE_SIZE label item in inverse mode for 
             tube, so that a subsequent forward VISIS2 can recognize it as tube
  1998-02-18 LWK fully re-enabled quotes around NATIVE_..._TIMEs
  1998-03-08 LWK added RTI to NATIVE_START_TIME for the sake of the Spike file
             conversion program
  1998-03-12 LWK added keyword USECAT/NOCAT to allow suppression of catalog use
  1998-04-06 LWK- don't use AACSFILE item for Calibration data;  write more items
             to label for Calibration file (solar/cenbody distances, band_suffix...
             items)
  1998-04-08 LWK fixed START/STOP times to handle cubes made in inverse mode;
             don't check task of cocube
  1998-04-21 LWK changed double quotes around LOMMEL-SEELIGER to single
  1998-04-29 LWK fixed code reading NATIVE_START_TIME in inverse mode to cover 
             case of old cubes where this has only two fields;  also fixed 
             NATIVE_STOP_TIME
  1998-05-07 LWK allowed CORE_UNIT = DIMENSIONLESS (inverse mode)
  1998-05-13 LWK removed references to BELOW_THRESH  & MISSING_SENSITIVITY from 
             label
  1998-05-14 LWK changes due to renaming of CALIBRATION target to CAL/SKY
  1998-05-25 LWK changed CORE_NAME, CORE_UNIT, PRODUCT_ID for IOF cube
  1998-05-27 LWK added BREAK to Histogram description;  also, get this from
             HIST2D label since that's always present (but spec.plots may not be)
  1998-06-07 LWK revisions to support PTUB/GTUBs (note that Inverse mode for 
             this is TBD -- may never be needed!);  increased LABELMEMORY again 
             (to 84000) for extra backplanes
  1998-06-09 LWK revised Special Processing comment;  fixed "Footprint" note for
             tube case
  1998-06-22 LWK added cutoff & sensitivity ratios for hi-gain thermal regime
             (label items only)
  1998-06-24 LWK fixed processing of HISTFILE & associated label items
  1998-06-29 LWK more fixes to HISTFILE (etc.) processing, for 2nd VISIS2 run
             on a cube;  ensure that VERSION_DATE reflects pgm. version
  1998-07-12 LWK ensure that COORDINATE_SYSTEM_NAME=PLANETOGRAPHIC is written
             correctly in inverse mode (same fix as for NIMSCMM2 in feb97)
  1998-07-28 LWK add check for zero meridian being in image when determining
             EAST/WESTERNMOST_LONGITUDE
  1998-08-12 LWK added message to above check;  adjust cen_lon to (-180,180)
             range if min/max lon's are in this too
  1998-08-13 LWK fixed mpxy2ll call for tube case
  1998-08-14 LWK disabled mpxy2ll call and entire zero meridian check (since
             nimscmm2 does it right now), because it still fails for certain
             tube cases (e.g., R/T)
  1998-08-15 LWK moved THERMAL_DETECTOR arrays out of BAND_BIN group because
             they don't have the Band dimension
  1998-09-19 LWK fixed MAP_SCALE in Perspective case (take target radius into
             account)
  1998-12-15 LWK changes for Unix:  made all functions that return values "int";
                replaced variable "string" with "xstring" to avoid RTL collision
  1999-02-04 LWK changed CODMAC part of DATA_SET_ID to 3 for Tube case
  1999-02-17 LWK added GRATING_STEP_INFLATION to history, renamed 
             GRATING_CORRECTION to GRATING_POSITION_CORRECTION
  1999-03-07 LWK allowed nbpln=5 when writing BAND_SUFFIX_NAME/UNIT for special
             (non-NIMS) processing support
  1999-03-21 LWK added 2 more decimals places to precision of pshift/ainfl in label
  1999-04-04 LWK fixed CORE_UNITS comment for RADIANCE_FACTOR case (PI was wrong)
  1999-04-09 LWK removed MINIMUM/MAXIMUM_LONGITUDE items, revised EASTERNMOST/
                WESTERNMOST_LONGITUDE algorithm (yet again!) to ensure both items
                are always positive;  note that current NIMSCMM2 always makes
                min_lon < max_lon in VICAR label, but this will no longer be true
                when an ISIS cube has been converted back to VICAR by VISIS2
                (shouldn't matter!)
  1999-04-11 LWK fixed determination of mphase, which was incorrect when 
             TASK=VISIS2:  in forward mode need special keyword, in inverse must
             search cube History;  fixed OBSNAME/OBSEXT processing for phase-0
  1999-04-14 LWK fixed a bug processing BAND_BIN_ORIGINAL_BAND introduced by
             previous change
  1999-04-26 LWK added wobble parameters to History (only)
  1999-05-17 LWK added wobble cone estimate 
  1999-05-25 LWK removed WOBBLE_MODE item (per change in nimscmm2)
  1999-07-19 LWK fixed mphase determination when task=NIMSCMM_SM
  2000-01-26 LWK fixed Y2K bug in PRODUCT_CREATION_DATE
  2000-01-25 LWK added SATURATION_THRESHOLD_WEIGHT label item and SCLK_GAPS
             history item
  2000-05-28 LWK check for SK_ID if SP_KERNEL is missing
  2000-06-20 LWK fixed bug (found by BAM in VISISX on Linux, where it is fatal!)
             in get_real_value where float/double are confused:  added routine 
             get_double
  2000-07-03 LWK changes for histogram-binning case
  2001-01-10 LWK added label comment defining slant distance backplane
  2001-08    LWK added support for platform-dependent special-pixel values and
                label items
  2001-10-29 LWK replaced get_string_value by get_qstring_value in keyword_value
             for string contstants
  2002-08-17 LWK added code to support platform-dependent special-pixel values
  2002-08-20 LWK also to support other platform-dependent label items
  2002-09-17 LWK added U_NL,U_NS to zvopen calls with NOLABELS
  2004-08-19 LWK fixed bug in get_recinfo() (inverse mode only)
  2006-06-09 LWK disabled special code to read BEG/END_SCET (will give problems
             for certain formats!  Fix is TBD as it seems non-urgent ...)
  2006-06-14 LWK added check following xlgets on RAD_CONV/BASE
  2007-04-07 LWK disable NOTE processing as it crashes 14ensucomp mosaic cube;
             removed get_cat() and catalog include file; added quotes to
             START/STOP_TIMEs to satisfy ISIS on Shifty
  2009-09-17 LWK disabled PRODID (not used under unix)
  2010-02-05 LWK added code in write_object to update the host information in TOVIC
             mode
  2011-03-14 LWK added EAST_LON keyword for C.Phillips ISIS3 work
  2011-11-13 LWK changed format of START/STOP_TIME to conform to PDS stds
  2012-02-03 LWK changed 'SINUSOIDAL_EQUAL-AREA' back to SINUSOIDAL (see change in
                1997 above) -- Unix ISIS seems to have changed its syntax
  2012-02-10 LWK added PC for Linux to list of hosts
  2016-02-24 WLB Fixed 64-bit bugs and library call errors.
  2019-06-14 WLB IDS-7924: Cast format args to expected type.
                 IDS-7922: Initialized some variables.
  2019-08-07 WLB IDS-7923: Replaced some sprintf calls with snprintf.

PARAMETERS: