convert Documentation

convert - Convert cube data format to different computer platforms
convert converts a standard ISIS cube file to a different computer
platform architecture.  Currently, convert supports Sun, DEC VAX and
DEC Alpha (running Digital Unix).  Silicon Graphics (SGI) platforms
are compatible with Suns.   Conversions are performed on the core
region and any suffix planes that contain standard ISIS numeric data
types.  The specific platforms mentioned can be specified or the generic
types can be used if the user knows the architecture of the desired
platform.  These generic terms include "MSB" (Most Significant Byte or
Big Endian), "LSB" (Least Significant Byte or Little Endian, "IEEE"
(refers to a specific floating point storage format) and "VAX" (which
refers to VAX floating point format).  The option to "convert" data from
one architecture to the same architecture (PLATFORM="HOST") is supported
since convert can be used to translate special pixel values to valid or
other special pixel values.

convert does not support conversion of ISIS table files or Instrument
Spectral Libraries (ISLs).  Table files can be converted using tbl2asc
on the originating platform and then asc2tbl on the target platform.
ISL support will be incorporated at a later date.

The TAE parameter PLATFORM allows selection of the output platform.  The
input data type is determined by the contents of the file specified in
the FROM parameter.  convert will only work on standard ISIS cube files.
convert can be used to perform "conversions" on data originating on the
"HOST" computer or a compatible format by selecting PLATFORM="HOST".
This will include substituting/translating special pixel values to other
values, stripping off objects other than the QUBE and HISTORY data
objects, and specifying extra unused records to be allocated in the
output cube file for the label and history object.  A record is 512
bytes.  The default values for extra records for LABEL and HISTORY are
15 and 25, respectively.  Although specific hosts are listed, the
generic platforms provided should support most other platforms as well.

The TAE parameters NUL, LRS, LIS, HIS, and HRS, correspond to the ISIS
special pixel values of NULL, LOW_REPR_SAT, LOW_INSTR_SAT,
HIGH_INSTR_SAT and HIGH_REPR_SAT, respectively.  The default for these
values is "NO_CHANGE" which means that special pixel values are retained
during the conversion process.  Note that the conversions between IEEE
and VAX floating point require substitution of special pixels since the
binary representations are different for these values.  This translation
will be performed automatically by convert unless overridden by the
aforementioned parameters.  These parameters are declared as string
types to allow for changing one special pixel value to another (using
NUL, LRS, LIS, HIS, HRS as values) or to a specified valid value (such
as the character string representation of the numeric value).  This
value will be converted to the core pixel type representation.  Note,
however, that the operation to make this happen has the potential to
result in a replacement value to be translated to a special pixel value
i.e., low or high representation saturation if the numeric value is
outside the range that can be represented in the output file.  convert
will report this case and *continue* processing the input file.  convert
does not apply any replacement values specified in these parameters to
any suffix region.

When undefined suffixes occur in input cubes (which is always assumed to
be storing 4-byte entities), convert will simply do a byte swap where
required.  The ISIS standard is for values in undefined suffixes to be
just that - undefined.  As such, it is just not clear how to handle
these.  convert simply does a 4-byte swap conversion.  Note that this
may not be sufficient for every case.  The suffix corner region that
intersects the fastest and second fastest varying axes is converted
subject to the fastest varying suffix definitions.

convert also allows the user to shrink or expand the ISIS label section
and/or HISTORY object.  This can be useful for those cubes that will
require lots of interactive work where HISTORY and labels can grow in
place - no output cube file generation.  The XLABRECS parameter can be
used to specify the number of extra records to allocate to the output
ISIS file label section.  The XHSTRECS parameter applies in the same
fashion to the HISTORY object.  The default value of the NULL TAE
parameter value will result in the normal number of default records to
be allocated to each section during file creation.

The TAE parameter, PROPOBJS, allows the user to select propagation of
other objects that cannot be converted by convert.  The only objects
modified by convert are the QUBE and HISTORY objects.  If other existing
data objects are deemed valid for the targeted output platform, then
convert can propagate them unmolested to the output file.  The label
information for each additional object will remain intact with no
modifications.  Note that the history object is always propagated and
is compatible to all configurations since it consists entirely of
textual information.  The default setup for convert assumes a
HOST-to-HOST transfer, therefore propagating all extra objects.  If
PROPOBJS="NO", then all other objects are removed from the output file.
Otherwise the objects and label information are propagated as is to the
output cube file.

convert uses dynamic memory to process the file.  The maximum amount
of memory convert can allocate is subject to the ISISBUFMEM environment
variable.  If this environment variable is set to a valid integer value,
then convert will not allocate any more bytes than this value.  If it is
not defined, then the default is about 4 megabytes (4,000,000 bytes).
If convert complains about not enough memory or memory allocation
fails, contact the cognizant programmer on ways to use ISISBUFMEM to
get around these problems.

Note that an extreme condition exists when converting VAX floating point
values to IEEE real and vice versa.  This is only a problem with pixel
values that have very small or very large exponents and thus does not
occur under any normally encountered values.  Converting VAX to IEEE
can result in UNDERFLOW; IEEE to VAX can result in OVERFLOW.  When these
conditions are detected, the final exponent conversion is not performed.
The values are still valid for both forms, but, basically will be off by
a factor of four.  Note that this is not a reversible condition since
convert has no way of tracking previous occurrances of this condition.
Repetitive inverse runs of convert will never yield more than a factor
of four discrepancy in these cases (think about why this is so!).

PROGRAMMER: Kris Becker, USGS, Flagstaff, Az.

Input cube file name
  (default extension is .cub)

NONE

Input subcube specifier

--

Output cube file name
  (default extension is .cub)

NONE

The type of hardware the output
cube is to conform to.
Supported hardware types are:
HOST
SUN   (MSB_IEEE)
VAX   (LSB_VAX)
ALPHA (LSB_IEEE)
MSB_IEEE
LSB_IEEE
MSB_VAX (not defined in PDS)
LSB_VAX

"HOST"

Value to replace ISIS NULL
pixel value with

"NO_CHANGE"

Value to replace ISIS
LOW_REPR_SAT pixel value with

"NO_CHANGE"

Value to replace ISIS
LOW_INSTR_SAT pixel value with

"NO_CHANGE"

Value to replace ISIS
HIGH_INSTR_SAT pixel value with

"NO_CHANGE"

Value to replace ISIS
HIGH_REPR_SAT pixel value with

"NO_CHANGE"

Number of extra label records
to allocate to output file

--

Number of extra HISTORY records
to allocate to output file

--

Propagate extra objects from
input cube to output cube

"YES"

User comment

" "

ADDITIONAL NOTES:

Parm	Description
FROM	The input cube file that is to be converted. If the file extension is omitted, then ".cub" is assumed.
SFROM	SFROM specifies the subcube using a single string for all three dimensions of the cube. The order of the three dimensions is always "samples:lines:bands". If a dimension is left blank, all the data for that dimension is selected. The default value of NULL for SFROM selects the entire cube. Any application below can be used for any dimension. To select specific data from any dimension: "10-100(3):11,12,15-20:1-10(2)" = This example will select every third sample starting with sample 10 thru 100. It selects lines 11 and 12, and 15-20. It selects every other band, starting with band 1 thru 10. There are special characters that can be used for selecting a subcube efficiently, such as "*","#", and "~". For examples type "help sfrom" in TAE. **NOTE** For more examples and explanation of the many features of the SFROM parameter, tutor the sfrom.pdf or refer to Introduction To ISIS, Section 6, of the ISIS User's Manual **
TO	The output cube file created by convert. If the file extension is omitted, then ".cub" is assumed.
PLATFORM	This parameter specifies the type of hardware the output cube is to conform to. The supported hardware architectures are MSB and LSB byte storage orders and VAX and IEEE floating point. Some specific platforms names are provided and can be used. If the architecture is known and the specific platform name is not provided as an available option, use one of the generic names. The value of "HOST" will always refer to the platform convert is executing on.
NUL	This parameter allows the user to specify an explicit value to replace the ISIS NULL special pixel value. This can have several forms. The default of "NO_CHANGE" means that these values are propagated to the output file unchanged, i.e., the special pixel value is written to the output file as the same type of special pixel value. Other valid character strings are "NUL", "LRS", "LIS", "HIS", "HRS", which correspond to ISIS special pixel values NULL, LOW_REPR_SAT, LOW_INSTR_SAT, HIGH_INSTR_SAT, and HIGH_REPR_SAT, respectively. A specific numerical value may be used to translate it to a valid value.
LRS	This parameter allows the user to specify an explicit value to replace the ISIS LOW_REPR_SAT special pixel value. Refer to the NUL parameter for more details.
LIS	This parameter allows the user to specify an explicit value to replace the ISIS LOW_INSTR_SAT special pixel value. Refer to the NUL parameter for more details.
HIS	This parameter allows the user to specify an explicit value to replace the ISIS HIGH_INSTR_SAT special pixel value. Refer to the NUL parameter for more details.
HRS	This parameter allows the user to specify an explicit value to replace the ISIS HIGH_REPR_SAT special pixel value. Refer to the NUL parameter for more details.
XLABRECS	This parameter allows the user to specify the number of extra (unused) records to allocate to the label section of the output file. A value of the TAE null parameter (default) will (at the time this program was authored) result in 15 extra records to be allocated to the label section of the output file. This is in addition to the number required to accomodate any existing label information in the input file. A value of 1 will actually cut down the size of the label.
XHSTRECS	This parameter allows the user to specify the number of extra (unused) records to allocate to the HISTORY object of the output file. A value of the TAE null parameter (default) will (at the time this program was authored) result in 25 extra records to be allocated to the output file. This is in addition to the number required to accomodate any existing HISTORY information in the input file.
PROPOBJS	This flag allows the user to specify whether to propagate additional objects other than HISTORY and QUBE objects that exist in the input cube to the output cube file. Note that setting PROPOBJS = "YES" will transfer object label and data to the output cube unaltered and may be useless and probably invalid on the specified hardware platform. This is because convert does not perform data conversion on extra objects.
USERNOTE	Comment from the user. This will be recorded in the ISIS session log file and also in the History entry that is put into the History object of the output file.