Help for VISISX

PURPOSE:

 VISISX transforms from a Vicar 3-D image file to an ISIS Cube file
 and vice versa.

EXECUTION:

VISIS2 input output mode [suffix-images] [histfile] [taskname]

where "input" and "output" are Vicar and ISIS files, in a sequence
determined by "mode", the suffix-images are separate files in Vicar
but part of the cube in ISIS, and "histfile" is an optional ascii text 
file containing an ISIS History object.  If label processing is to be
done (in TOISIS mode only), then "taskname" must be specified to denote 
the task from which the history labels are to be taken.

The suffix images are optional.  If they are omitted in TOVICAR mode,
then any suffix data in the ISIS cube will simply be skipped over.  If 
they are specified in TOISIS mode, then the images will be checked for
consistency of dimensions with the core.  Currently, only backplanes
are supported in TOISIS mode.

Suffix planes / bands:

The Vicar cube file is stored as the Core of the ISIS cube.  The
suffixes are stored as separate image files in Vicar, but as part of
the cube in ISIS.  There are three kinds of suffixes: sideplanes,
backplanes, and bottomplanes.  This terminology comes from applications
in which two of the three cube dimensions are spatial and one spectral,
with the two spatial dimensions constituting the "front" view of the
cube, while the spectral one is the "depth".  For other applications,
these terms lose their meaning, but are retained here since spatial-
spectral cubes are the most common types currently used by VICAR.
Here are their definitions in terms of the storage orders supported
by VISISX:

Band-Sequential (BSQ) storage order, in which Sample is the most
rapidly varying dimension, then Line, then Band:
  Sideplanes are stored at the end of each line.
  Bottomplanes are stored at the end of the last line of each band.
  Backplanes are stored at the end of the cube.

Band-Interleaved by Line (BIL) storage order, in which Sample is the 
most rapidly varying dimension, then Band, then Line:
  Sideplanes are stored at the end of each line.
  Backplanes are stored at the end of the last band of each line.
  Bottomplanes are  stored at the end of the cube.

These are the only storage orders supported by VISISX.

Note that suffix planes are only allowed at the end of their
corresponding dimension, not at the beginning.
Not all combinations are supported.  Backplanes are supported
for all modes, but sideplanes and bottomplanes are only supported
for BIL format and in TOVICAR mode (for Cassini VIMS).  For this
case, here is the detailed specification of the dimensionalities:

Let the Core of the cube have the dimensions C1, C2, C3 (in order from
most to least rapid variation), and let the width of the suffix planes
be S1, S2, S3 (in the order Sideplane, Backplane, Bottomplane), then the
corresponding image dimensions will be:

Sideplane:   S1, C2, C3.
Backplane:   C1+S1, S2, C3.
Bottomplane: C1+S1, C2+S2, S3.

I.e., the "corners" formed by two successive suffix planes are included in
the second of each sequence.  

Again, note that the above schema is for BIL format only.
Assumptions and Restrictions:

1. All suffix planes are assumed to be in 4-byte (real or integer) format.
 (Additionally, VIMS side- and bottomplanes are always integers.)

2. Currently, only BSQ and BIL file organizations are supported.

3. The maximum BAND dimension allowed is 500.
05dec98  --  Written by L.W.Kamp (based on VISIS2).

Changes:

04dec98 -lwk- original version
09dec98 -lwk- added U_NL/S to zvopens in get_recinfo (for Solaris)
16dec98 -lwk- added support for BIL files and for SUFFIX planes 
        (TOVICAR mode only, not saved!);  specified "int" for functions 
        that return values
18dec98 -lwk- added HOST parameter
18jan99 -lwk- fixed HOST parameter
22jan99 -lwk- fixed CORE_ITEMS in TOISIS mode (was broken when BIL added),
        and CORE_ITEM_TYPE (was VAX-only); added CORE_NAME & CORE_UNIT as 
        they're required by Unix ISIS
26jan99 -lwk- use zvhost for int/realfmt
30jan99 -lwk- replaced HOST parameter in TOVICAR by search on CORE_ITEM_TYPE
01feb99 -lwk- treat NATIVE_TIMEs differently per project (tovicar mode only)
02feb99 -lwk- added "U_ORG","BSQ" to zvopen in write_object (TOISIS) to fix
        problem with BIL cubes
22apr99 -lwk- skip over the AXIS_NAME item in the specplot part of the label
        for the case of a NIMS cube
06jun99 -lwk- allow for partial subset of labels depending on 'maplabs'
        flag -- this is designed to allow NIMSSKY cubes to be processed, but
        ideally each label item should be checked separately
13sep99 -lwk- check for ORTHOGRAPHIC alone and replace by OBLIQUE_ORTHO;
        start search for map keywords at "GROUP = IMAGE_MAP_PROJECTION",
        since some cubes have RADIUS keywords before MAP_PROJECTION_TYPE
19jun00 -lwk- removed objectindex stuff from keyword_value (since we have
        only 1 object containing labels);  deleted a few residual "NIMS"s
        and function byte_nibble;  added EAST/WESTERNMOST_LONGITUDEs to
        ISIS->VICAR mode
20jun00 -bam - added new keywords FIRST_LINE_SAMPLE, LINE_EXPOSURE_DURATION,
        START_TIME, and EASTERNMOST/WESTERNMOST LONGITUDE (these replace
        MINIMUM/MAXIMUM LONGITUDE in the newer files). I have also added a
        new function for double precision values, get_double_value, and
        modified the code to accept this new function.  This is necessary
        for port to LINUX.
11jul00 -lwk- fixed bug checking for map labels in ToVic mode
18jul00 -lwk- checking for Property map labels even if no Task specified
15may02 -lwk- added ISIS 'CYLINDRICAL_EQUAL-AREA'
27apr04 -lwk- merged BAM and LWK versions;  increased MAXBANDS to 600;
        check for fullword int in inverse mode;  fixed bug in treatment of 
	backplanes in write_object
29apr04 -lwk- added support for suffix planes in TOVICAR mode;  replaced
        all references to "forward/backward" modes with "toisis/tovicar"
22may04 -lwk- added VIMS keywords: START/STOP_TIME (need special function
        find_keyword_str to distinguish from NATIVE_TIME), INTERLINE_DELAY,
        EXPOSURE_DURATION, X/Z_OFFSET
01jun04 -lwk- added VIMS keywords SAMPLING_MODE_ID & SCAN_MODE_ID;  fiddled
        with string delimiters in get_string_value() (again)
15jun04 -lwk- changed algorithm for distinguishing NATIVE_TIME and plain
        TIME, since Cassini has now made both strings
18jun04 -lwk- allow backplanes from co-cube in TOISIS mode;  changed treatment
        of the various suffix planes
22jun04 -lwk- translate CORE_NAME/UNIT to Vicar items; added BAND_SUFFIX items
        for display of backplanes in cv
28jun04 -lwk- added option to read wavelengths in from user parameter
14jul04 -lwk- added FAKEPROJ keyword as a workaround for limited ISIS projections
26jul04 -lwk- changed PROJECT_NAME to MISSION_NAME in TOISIS mode; fixed code to
        find SUFFIX_ITEM_TYPE
22sep04 -lwk- added more VIMS keywords at CCA's request;  fiddled some more with
        the code for START_TIME & NATIVE_START_TIME (latter can be with or without
        quotes!)
12oct04 -lwk- enabled fullword integer support in TOVICAR mode; added label items
        BAND_BIN_ORIGINAL_BAND/ORIGBANDS and (in VICAR) WAVUNIT;  read TARGET name
        in TOISIS mode
19oct04 -lwk- added CORE_MULTIPLIER input for Radar cubes
21oct04 -lwk- get NB from input cube label, not from WAVES! (TOISIS mode)
29oct04 -lwk- added ISIS special values to CORE & BAND_SUFFIX label items (TOISIS mode)
10dec04 -lwk- remove hard-coded nbkpln=9;  added FRAME_LINE/SAMP to BAND_SUFFIX items
        for VIMS
07may05 -lwk- added case of nbkpln=2
08may05 -lwk- write entire Vicar history to PDS History object in TOISIS mode
18may05 -lwk- fixed problems with backplanes in BSQ cube in TOISIS mode; ensure that
        co-cube is always BSQ in TOVICAR mode
01jun05 -lwk- fixed bug introduced by last change in calculation of FILE_RECORDS
27oct05 -lwk- look for LAT_TYPE as well as LATITUDE_TYPE
28oct05 -lwk- added X86 (Linux) hostname support, treat it as AXP.
29oct05 -lwk- changed AXP-UNIX to X86-LINUX at RGD's request since that's the only
        currently officially supported VICAR platform of that flavor