[Table of Contents] [Introduction to ISIS (UNIX)] [ISIS Program Summary (UNIX)] [ISIS PICS Program Summary (UNIX)] [Display Summary (UNIX)] [Program Summary (VMS)] [App. A-Cube Label] [App. B-Cube History] [App. C-Table Label] [App. D-Subcube Specifier]
ISIS combines elements of both classical image processing and spectral analysis, as well as new techniques developed specifically for the analysis of image cubes. Standard image processing techniques can be applied to the individual spatial-spatial planes of image cubes. Spectral analysis techniques can be applied to the individual spectra of the cubes. In addition, a new set of analysis programs, designed to take advantage of the combination of image and spectral information, can be used to analyze image cubes.
There are two main documents that provide detailed information for ISIS application programmers. The ISIS System Design document (ISD) describes the system design and the programming environment that is provided for developing application programs. The ISIS Programmer's Reference Manual contains complete descriptions of the various I/O and utility subroutines that are contained in the ISIS programming environment.
$TAE
This will give you the "TAE>" prompt, indicating that TAE is ready to accept a command. In most cases, you can use either upper case or lower case when using TAE. Also, TAE commands can be abbreviated using only enough characters needed to uniquely specify the command.
TAE>T CUBEDIV
TAE will then display a list of the parameters for the program, along with a brief description of each parameter and its initial default value (if any). The "?" prompt at the bottom of the screen indicates that TAE is ready for a tutor mode command. Since most programs have more parameters than can be displayed on one "page", typing the RETURN key will display the next page of parameters. You can set the value for a particular parameter by typing the name of the parameter (which may be abreviated) and the desired value, which must be separated by an "=". For example, to specify a file called TEST.CUB as the input file for the CUBEDIV program, type the following:
?FROM = TEST.CUB
Alternatively, typing the down-arrow or up-arrow keys will select the "next" or "previous" parameter for interactive editing of the current parameter value.
When you have specified all the parameter values, typing "RUN" (or simply "R") will run the program with the current parameter values. If you decide you don't want to run the program, typing "EXIT" will return to the "TAE>" prompt.
?SAVE TEST
will save the parameters in a file called TEST.PAR. The RESTORE command (with an optional file name) will restore a set of previously-saved parameter values.
When you RUN a program in tutor mode, the current parameter values are automatically saved in a file called LAST.PAR. If an error is detected, you can then tutor the program and use the "REST LAST" command to restore the complete set of parameter values. You can then correct a parameter value without having to re-specify all the other parameter values.
TAE>QL3 FROM=TEST.CUB PLOTMODE=BANDNUMBER
This command will run the program with the specified values for the FROM and PLOTMODE parameters. The default values will be used for any parameters that are not specified. If parameters are specified in the same order as the parameter definitions for the program, then the parameter names may be omitted. Thus, the following would be equivalent to the above command:
TAE>QL3 TEST.CUB PLOTMODE=BANDNUMBER
Most ISIS programs include the USERNOTE TAE parameter, which does nothing other than allow the user to specify an arbitrary comment that will be recorded in the session log file and the cube file history entry.
The default file name for the session log file is the file PRINT.PRT located in the current default directory. If desired, the user can select a different file by defining the VMS logical name ISIS$LOG_FILE to be the desired file. This can be done by typing a command such as:
DEFINE ISIS$LOG_FILE SESSION.LOG
Note that this is an operating system command that is typed before starting the TAE session. If no file extension is specified, then ".DAT" will be used. The specified file name may optionally include a disk directory specification. Multiple concurrent sessions are not permitted to use the same session log file. Thus, one of the main reasons for specifying a different session log file is to allow multiple concurrent sessions, e.g., two interactive sessions or an interactive session along with a batch run.
The session logging can be turned off by setting the log file name to be the null device, i.e., "NLA0:". Note that the colon must be specified, otherwise "NLA0" will be interpreted as a file name and a file named "NLA0.DAT" will be used.
In most cases, the normal operating system conventions are applicable for determining the location of a data file, i.e., an explicit directory and/or disk device can be specified, but the file is assumed to be located in the current default directory if the user does not specify a directory and disk device.
$DEFINE DATA DUA2:[NIMSUSER.DATA]
The logical name can also be defined after entering TAE by using
the DCL command, e.g.:
$TAE
Note that when the logical name is defined within TAE the
definition will be deleted when you exit from TAE. Thus, the
definition will not be remembered from one TAE session to another.
Defining a logical name before entering TAE will maintain the
definition across multiple TAE sessions.
Another way to use logical names is to define a VMS logical
name in which the
definition is an actual cube file name. The logical name can
then be entered for the TAE parameter value that specifies a cube
file name in an ISIS program. For example:
$DEFINE MYCUBE BASHFL$DUA0:[MOON]BIGLONGCUBEFILENAME.CUB
The DEFINE command can use another logical name in the definition.
For example, if MOON$DATA were defined to be BASHFL$DUA0:[MOON],
then the following DEFINE command could be used:
$DEFINE MYCUBE MOON$DATA:BIGLONGCUBEFILENAME.CUB
The ISIS I/O routines will use a two-step process when trying
to determine the actual disk filename to use. First, an intermediate
string will be formed by assuming that the supplied string is a logical
name and by translating it into its defined value. If the user-supplied
string is not a defined logical name, then the intermediate
string will be just the original user-supplied string. In the second
step, the I/O routines will check the intermediate string to see if
it has an extension, i.e., a ".
$DEFINE MYCUBE BASHFL$DUA0:[MOON]BIGLONGCUBEFILENAME.CUB
Note that the disk device and directory can be omitted from the
definition of the logical name, e.g.:
$DEFINE MYCUBE BIGLONGCUBEFILENAME.CUB
When this logical name is used, the current default directory will
be used as the location of the file.
However, note that a device and/or directory CANNOT be combined with
the reference to a logical name. I.e., the following will NOT work:
$DEFINE MYCUBE BIGLONGCUBEFILENAME.CUB
When ISIS records the TAE parameters in the HISTORY entry and the
Session Log file, the exact string specified by the user will be
recorded. In addition, most programs will also record the translated
string that gives the actual disk file name that is to be used. This
will be recorded as a comment line delimited by "/*" and "*/". (The
translated string that is recorded will not include an assumed default
file extension. Also, the translated string will not be recorded when
a logical name is used only for specifying a disk directory.)
The QUBE files that are supported by the ISIS I/O routines are
used for storing multi-dimensional data arrays. The maximum number of
supported dimensions is six. A CUBE file is a special case of a qube
file in which the number of dimensions in the data array is three.
(See the ISD for more information on the generalized qube files.)
Cube files are normally
used for storing data produced by imaging spectrometers.
Thus, two of the dimensions correspond to spatial
coordinates and the other dimension corresponds to the spectral
(wavelength) coordinate. The contents of the data values in a standard
cube file can of course consist of things other than observations
measured by an imaging spectrometer.
Each cube file contains at least two data objects, a HISTORY
object and a QUBE object. A cube file may optionally contain "extra" data objects in addition to the HISTORY object and QUBE object. The standard ISIS
cube-processing programs will propagate these "extra" data objects
unchanged from an input file to an output file.
All ISIS programs automatically maintain the history information.
When an application program reads data from an input file and writes
processed data to an output file, it will copy the input file history
information to the output file and then append a new history
entry for the current program.
Some of the label keywords are contained within GROUPs. The
most important of these is the BAND_BIN group, which describes the
spectral (wavelength band) axis of the cube. These include a list of
wavelengths (BAND_BIN_CENTER) and a list of the original instrument
band numbers that correspond to the file band numbers
(BAND_BIN_ORIGINAL_BAND). This keyword group might optionally
include a list of instrument grating positions and detector numbers
(BAND_BIN_GRATING_POSITION and BAND_BIN_DETECTOR).
The AXES keyword specifies the number of dimensions (axes) in the
core. For standard cube files, this value is always three. The
CORE_ITEMS keyword has an array of integer values that specify
the length of each axis of the core. These values are expressed as the
number of pixels. The AXIS_NAME keyword has an array of literal
values that specify the
names of the axes.
The order of the values in CORE_ITEMS and AXIS_NAME corresponds
to the physical storage order of the data. (See below for details
on physical storage orders.)
The core data values are further described by the required
application-owned keywords CORE_NAME and CORE_UNIT. (These are called
"application-owned" because they are maintained by the applications
code of the programs rather than by the ISIS system routines. The
applications programs can set these keywords to any desired values.)
The label also includes a number of keywords that
describe the format of individual core pixel values. These are
described in detail later in this chapter.
The SUFFIX_ITEMS keyword has an array of integer values that
specify the number of suffix planes that exist along each of the
three axes. The order of the values in SUFFIX_ITEMS corresponds
to the physical storage order of the data file, i.e., the values
in the array correspond to the values in the AXIS_NAME keyword.
(See below for details
on physical storage orders.)
In a manner similar to the core description keywords, the name of
each suffix plane and the units of the data values are described in
suffix description
keywords of the form axis_SUFFIX_NAME and axis_SUFFIX_UNIT, where
"axis" is the name of the axis that is extended by the suffix data,
e.g., BAND_SUFFIX_NAME and BAND_SUFFIX_UNIT for suffixes that are
backplanes.
The "axis" value must correspond to one of the axis names listed in
the AXIS_NAME keyword. The suffix description keywords all have array
values, where the number of values corresponds to the number of suffix
planes on the axis. This allows each suffix plane to have a description
that is independent of all the other suffix planes.
Note that the name of each suffix plane is required to
be unique within each suffix region in a cube file.
Additional suffix description keywords are described later
in this chapter.
In a standard three-dimensional cube file, the names of the three
axes are always SAMPLE, LINE, and BAND.
The AXIS_NAME keyword has an array of values that list the names of the
axes in the cube. The order of the names specifies the cube storage
order in the file. The first axis is the fastest varying, and the
third axis is the slowest varying. The standard ISIS cube-processing
programs support the following three storage orders:
(SAMPLE, LINE, BAND) - Band Sequential (BSQ)
The CORE_ITEMS and SUFFIX_ITEMS keywords have array values. The
order of these values corresponds to the order of the axes listed in
the AXIS_NAME value.
In the physical file storage,
suffix pixel data (if present) is "scrambled" in with the
associated core pixel data. For example, in a BSQ storage order file,
the physical cube storage in the file begins with the pixels in the
first (top) line of the spatial-spatial image plane at the first
wavelength band. This is followed by the sideplane pixel values that
extend this line of core pixels. Next are the core pixels for the second
line, followed by the sideplane pixels for the second line.
After the last line of this first core image plane (and its associated
sideplane pixels) come the bottomplane pixels associated with the first
band. This is then repeated for the second through last bands.
Finally, all the backplane data are stored after all the core data
and associated sideplane and bottomplane pixels. Thus, in a
BSQ file, all of the backplane pixels are stored together in a single
contiguous block at the end of the cube data object. This means that
backplanes can be added to a BSQ file without creating a new file
because it only requires adding new data at the end of the file.
(This is true only if the qube object is the last object in the file,
which is usually the case since any "extra" data objects usually are
located between the history object and the qube object.)
However, adding backplanes to a BIL or BIP file requires creating a
new file.
In general, most application programs are capable of processing
BSQ storage order files. In most cases, one additional storage
order can be handled by each program. The storage orders that can
be processed and the efficiency of processing usually depend upon
whether the program does its processing in terms of spatial planes
or in terms of spectra. For example, the CUBEDIV program divides
each spatial plane by a given spatial plane. This program is most
efficient when processing a BSQ file, but BIL files can also be
processed. Like most spatial processing programs, CUBEDIV cannot
process a BIP file because there is no way to make spatial processing
acceptably efficient for BIP files. The RATIOCS program divides
each spectrum in a cube by a given spectrum and is thus an example
of a spectral processing program. RATIOCS is most efficient when
processing a BIP file, but it can also process either a BIL file
or a BSQ file.
Note that the TRANSPOSE program will convert a standard cube file
from one physical storage order to any other physical storage order.
It is important to note that the standard ISIS
cube-processing programs assume that values stored in a file are
stored in formats that are native to the host computer on which the
software is currently running. Thus, for example, there is no
capability for "on the fly" conversion of "foreign" floating point
formats to the native floating point format.
This conversion would
need to be performed by a translator program that converts a file
from a "foreign" format to the standard ISIS cube file format for the
current host computer.
A single integer type code value is used to identify the various
supported data types, i.e., combinations of CORE_ITEM_TYPE and
CORE_ITEM_BYTES keyword values. This is described in more detail
below.
However, there are several aspects of the
different storage formats that are important to the user. First,
different data types result in different disk file sizes. Second,
different data types allow different precision (number of significant
digits) in the stored pixel values. 4-byte format uses the most
disk space and allows the greatest precision. 1-byte format uses
the least disk space and allows the least precision. The third
important aspect of the different data formats is the range of values
that can be represented. With 4-byte format, the representable
range is the range of floating point values and is thus nearly
unlimited for all practical purposes. For 2-byte or 1-byte format,
the representable range varies depending upon the current values of
the type conversion parameters. This is discussed in more detail
below.
The following is a summary of the three standard pixel representation
formats for core pixels:
In a manner similar to the core description keywords,
the data type for suffix pixels is described in suffix description
keywords of the
form axis_SUFFIX_ITEM_BYTES and axis_SUFFIX_ITEM_TYPE, where "axis"
is the name of the axis that is extended by the suffix data, e.g.,
BAND_SUFFIX_ITEM_BYTES and BAND_SUFFIX_ITEM_TYPE
for the suffixes that are backplanes. The "axis" name corresponds to
one of the axis names listed in the AXIS_NAME keyword.
Each suffix plane within
a single file can have a different data format. Thus, the values of
these keywords are arrays. Each element of the array refers to a
separate suffix plane.
Type conversion parameters can also be used
for some of the standard suffix data types.
These are contained in keywords of the form
axis_SUFFIX_BASE and axis_SUFFIX_MULTIPLIER, e.g., BAND_SUFFIX_BASE and
BAND_SUFFIX_MULTIPLIER for the backplane suffixes. Each suffix can have
different type conversion parameters, so these keywords have array values.
When a suffix pixel contains
a numerical value, it is expected that in most cases it will be
stored in one of three standard formats:
The ISIS application programs
will preserve the identity of special pixel values when
converting pixels from one representation to another. For example, when
converting from 2-byte format to 4-byte format, a 2-byte null pixel
will be converted to a 4-byte null pixel.
When the output pixel data type is 1-byte or 2-byte (OTYPE=1
or OTYPE=2), then the application program converts the internal 4-byte
floating point values to the selected output type using the output
file's type conversion parameters. In most cases, the user has
control over the type conversion parameters that are used. However,
rather than directly specifying these parameters, the ORANGE TAE
parameter allows the user to specify the range of pixel values that
can be represented in the output file. The application program will
then compute the type conversion parameters that will allow
representing the desired range of values. In most cases, the
default value of ORANGE is (0.0, 0.0), which indicates that the
desired range for the output file is the same as the range of
values that can be represented in the input file. (If the input file
is 4-byte floating point format and the output file is 1-byte or
2-byte format, then the user must specify an explicit range for the
output file.)
During the conversion of internal 4-byte floating point values to
output 1-byte or 2-byte format, some values may be outside the range
of values that can be represented in the output format using the
current type conversion parameters. These will be converted to either
the high or low "representation saturation" special values. These are
thus valid output data values that are "lost" because they are outside
the specified ORANGE. The application program will report a count of
such "lost" output data values. If desired, the user could then
re-run the application program with a larger ORANGE in order to
reduce or eliminate these lost values. Note that most application
programs will propagate a saturated input pixel value into a
corresponding saturated output pixel value. These pixels are NOT
included in the count of saturated pixels that are created during
the output type conversion process.
For most application programs, the user specifies the input
subcube specifier with the SFROM TAE parameter, which has a string
value. In many cases, the user can specify the subcube specifier
string without enclosing it in double quotes. However, if it contains
commas or parenthesis, the TAE syntax requires that it be enclosed
in double quotes.
The following subsections describe the detailed format and
selection capability that is provided by the subcube specifier.
The default value of the SFROM parameter is the null string (all
blanks), which selects the entire input cube file (both core and
suffix) and is thus the most commonly used value.
Several examples of the subcube
specifier are given in the last subsection of this section.
On the first reading of this document, it might be useful to skip
to the next major section (Instrument Spectral
Library Files) and then return to the detailed description of the input
subcube specifier at a later time.
The application program may or may not actually process or use all the
data selected by the input subcube specifier. The part of the selected
data that is used will depend upon the definition and intended purpose
of the application program. For example, one application program might
be defined to process all selected core data and never process selected
suffix data. Another program might make use of a suffix plane. In
this case, the input subcube specifier would select the set of suffix
planes that are passed to the application code, but there would
be a separate TAE parameter that selects which suffix plane is to be
actually used by the program.
Some programs may be capable of processing a selected subarea of the
input core data. Most of these programs use the input subcube
specifier to select the input data that are passed to the program and
then use other TAE parameters to specify the part that will actually be
processed. The exact method of specifying this process selection will
vary according to the needs of the individual programs.
For most programs that process an input file and put the results into
an output file, the size of the output file will correspond to the
size of the part of the
input file selected by the input subcube specifier. (In
some cases, the output file might be larger than the input subcube
specifier due to the addition of new suffix planes. Also, a program
that performs a geometric transformation might produce an output file
that has a spatial size that is different from the input file.)
Selected input
data that are not processed will normally be propagated unchanged to the
output file. For example, if the definition of a program consists of
processing only core data, then any selected input suffix data will
be propagated unchanged to the output file.
If the "physical" order flag is omitted, then the three axis specifiers
are assumed to be in the "logical" storage order: SAMPLE, LINE, BAND.
This "logical" order can only be used with standard 3D ISIS cube files.
In most cases, each input file will have a corresponding
input subcube
specifier that can be used for selecting parts of the input file.
Each input subcube specifier will be supplied by a separate TAE
parameter that has a length of 128. When the user enters the value
for one of these TAE parameters, it may be necessary to enclose the
string in double quotes as required by the usual TAE rules for entering
string values.
The names of the TAE parameters that specify input
subcube specifiers will be SFROM or SFROM1, SFROM2, etc.
The application program PARSE will accept a parse equation
string in which subcubes
are indicated as expressions enclosed by square brackets immediately
following the name of a cube file. The contents and meaning of this
expression will be the same as the input subcube specifier string
describe above.
If an entire axis specifier is the null (blank) string, then all
indices on the axis are being selected. This includes all core indices
and all suffix indices (if applicable).
If only one component (core or suffix) of an axis specifier is given,
then all indices are being selected for the component not given.
If a core specifier contains only a range modifier without an explicit
range, then a range of "1-*" is assumed. The same applies to a suffix
specifier inside the parentheses that delimit the suffix specifier.
The suffix index values are separate from the core index values. The
suffix index values also start with "1" to indicate the first suffix
along an axis.
An ISL file is a special type of cube file that is stored
in BIP (band interleaved by pixel) storage order. The actual spectral
data are stored in the core of the cube, and the spectral header
data are packed into a set of backplanes on the cube. This storage
organization allows rapid searching through the list of spectra in
a file since each spectrum and its associated header data are stored
as a contiguous piece of the physical disk file.
Note that the QL3 cube display program is not able to display
a standard ISL file since it is stored in BIP storage order. The
TRANSPOSE program can be used to convert a BIP Instrument
Spectral Library file to either BSQ or BIL storage order, either of
which QL3 is able to display. (The conversion from BIP to BIL will
run faster than the conversion from BIP to BSQ. However, the
initial start-up time for QL3 will be slower for BIL than for BSQ.
Rather than running TRANSPOSE once to convert BIP storage order directly
to BSQ, it may be faster to run TRANSPOSE to convert BIP to BIL and
then run it a second time to convert BIL to BSQ.)
In a cube file, the name of the data object that contains the
cube data is always "QUBE". However, in a Table file, the name of
the data object that contains the table data is arbitrary and can
vary from one Table file to another. One reason for this is to
allow a single Table file to contain more than one table data object.
(Duplicate object names are not permitted within one file.) In
some cases, the name of the Table data object is determined by the
application program. In other cases, the name of the Table data
object can be specified by the user.
Note that a cube file can contain one or more Table objects
in addition to the QUBE and HISTORY objects.
The number of columns of data contained in each row of the table
is recorded in the COLUMNS label keyword. Each different column is
identified by a unique name, which is recorded in the array of values
in the COLUMN_NAME keyword.
Each column can contain either a scalar value or an array of
values. (Most Table objects contain only scalar values.) The number
of elements in each column is recorded in the COLUMN_ITEMS keyword.
The data type of each element of each column is recorded in the
COLUMN_ITEM_TYPE and COLUMN_ITEM_BYTES keywords. Most tables use
only INTEGER*4 and REAL*4 data types, but a variety of other data
types are supported, e.g., INTEGER*2 and CHARACTER*n (character strings
of arbitrary length).
The table object description can optionally include the
AUX_ROW_DEFINITION group of keywords. This group contains keyword
names of the form name_NOTE, where "name" is the column name that
is recorded in the COLUMN_NAME keyword. The values of these keywords
are text strings that describe the meanings of the columns.
The ASC2TBL program translates table data from an ASCII text
format into a standard ISIS binary table file. This can be
used for converting the output of the TBL2ASC program back into
the standard ISIS binary table format. This allows the use of a
text editor for editing values in a table file. The ASC2TBL
program can also be used for translating other types of text table
data, e.g., the prototype format text table files and "foreign"
text table data that contains no header information.
Mosaic operations are implemented only by a few special mosaic
programs.
A few programs are only capable of operating in the update mode.
These programs include the FROM TAE parameter, which specifies the
name of the input file that is to be updated. (These programs do not
use the TO parameter since the output file is the same as the input
file.)
Some of the programs are only capable of operating in the mode
in which a new output file is created. These programs include the
FROM and TO TAE parameters to specify the input file and new output
file being created.
Many of the programs are capable of either updating the input
file or creating a new output file. These programs include both the
FROM and TO parameters. If the TO parameter is specified as the
null string (all blanks), then the input FROM file will be updated.
If a non-blank TO is specified, then it will be the name of the
new file that is created. Note that if TO specifies the same filename
and extension as FROM, then the input file will NOT be updated.
Instead, a new version of the file will be created. Also, note
that in most cases an input file cannot be updated if the input
subcube specifier is used to select a sub-area of the input file.
At any given time there might be "development" versions of some
ISIS programs installed on your system. These are programs that
are being made available on an experimental basis. These might
include revised versions of programs contained in the "new" system.
These might also include the latest experimental versions of new
programs that are under development and have not yet been included
in the "new" ISIS system. The SETDEVISIS program will select these
"development" programs for use. If a requested program is not
found in the "development" area, then ISIS will look for it in the
"new" area.
The program descriptions that are contained in this User's
Manual describe the set of programs that form the "new" ISIS release.
The date at the top of each page of the descriptions gives the
date of the last modification to the file that contains the program
description. The date of the last modification to the source code
for each program is reported in the VERSION_DATE recorded in the
history entry and session log entry
when the program is run. Note that updates to a
program description are independent of updates to the source code.
For example, an update might include a source code bug fix that
does not require a change to the program description. Or, a
program description might be updated without a change to the source
code of the program.
In addition, each section of the entire User's Manual is available
as a separate file. This includes the title page, intro chapter,
program summary, program descriptions, and appendices. Also, a new
release of ISIS includes a file that contains only the program
descriptions that are new or changed since the previous update.
This allows updating a copy of the User's Manual without re-printing
the entire manual. Typically, this would consist of replacing the
title page and program summary and then inserting any new or changed
program descriptions. If a large number of program descriptions are
new or changed, then the entire program description section can be
printed.
TAE>DCL DEFINE DATA DUA2:[NIMSUSER.DATA]
TAE>QL3 FROM=DATA:TEST.CUB
$TAE
TAE>QL3 FROM=MYCUBE
$DEFINE MYCUBE BASHFL$DUA0:[MOON]BIGLONGCUBEFILENAME
$TAE
TAE>QL3 FROM=BASHFL$DUA0:[MOON]MYCUBE5.0 - CUBE FILES
The following describes the overall format and characteristics
of the standard three-dimensional
cube files that are processed by the standard ISIS programs.
This includes a description of the pixel data types that
are supported in cube files. The format and access to data in
cube files are described in more detail in the ISIS System
Design document (ISD).5.1 - BASIC CUBE FILE STRUCTURE
ISIS cube files are stored as standard PDS labelled files.
A PDS labelled file consists of two basic parts. The first part
is the label, which is located at the beginning of the file. The
remainder of the file is the data area, which contains one or
more data objects. The label describes the structure and content
of the file. Information in the label is stored in a "keyword=value"
text format. Appendix A contains an example label for an ISIS
cube file.5.2 - CUBE FILE HISTORY OBJECT
The HISTORY object contains text information that records
the sequence of processing operations that created the file. This
consists of a sequence of history entries, each of which describes
an application program that was run and the TAE parameters that
were used. The format of history entries is the same as entries
in the ISIS session log file. Appendix B contains an example
cube file history. This listing was produced by running the LHLIST
program, which extracts the label and/or history from a cube
file and displays it on the terminal and/or puts it into a text
file.5.3 - CUBE OBJECT DESCRIPTION KEYWORDS
The label of a cube file contains various keywords that describe
the cube data object. These include
keywords that specify the number of axes (AXES, which is always 3 for cube
files), the name of each axis (AXIS_NAME),
the physical storage order (i.e., order of the axis names),
the length of each axis (CORE_ITEMS), the number of
suffix planes (if any) on each axis (SUFFIX_ITEMS),
various keywords that describe the pixel data type for the file
(CORE_ITEM_TYPE, CORE_ITEM_BYTES, etc.), and name and units for the
values stored in the main cube data array (CORE_NAME and CORE_UNIT).5.4 - CUBE DATA OBJECT FORMAT
The following diagram illustrates the general structure of a cube
data object. Note that this is a conceptual or "logical" view of the
cube. Most application programs provide this logical view of a cube
to the user. For example, the user usually can refer to logical
band numbers rather than referring to indices along the first, second,
or third axis of the cube.
(This logical view is separate from the issue of the physical
storage of the cube data object in a file, which is discussed later
in this chapter.)
______________________ .
/ / /| . ^
/ backplane / / | } suffix . /
/_ _ _ _ _ _ _ _ _/_ _/ | } region . /
/ / /| | . / d
/ / / |c | . / n
/ / / |o | . / a
/ core / / |r | . / B
/ / / |n | . /
/_________________/___/ e |e | . /---------------->
| | | d e|r | . | Sample
| | | i n | /| l . |
s | | |s a |/ / a . | L
p | | | l / / r . | i
a | core | |p /|/ t . | n
t | | | / / c . | e
i | | | / / e . |
a | | | / / p . |
l |_________________|___|/ / s . v
| bottomplane | | / } suffix .
|_________________|___|/ } region .
spatial ^^^ .
suffix region .
5.4.1 - CORE REGION
The core region of the cube data object contains the main data
array that is being stored in the cube file. For a standard ISIS cube
file, this is normally the imaging spectrometer data cube, which
consists of a
number of spatial-spatial image planes corresponding to different
wavelength bands.5.4.2 - SUFFIX REGIONS
Each of the three axes in a cube data object may optionally include
suffix data that extend the length of the axis. Conceptually, this
can be viewed as forming one or more
suffix planes that are attached to the core
cube as shown in the diagram above.
Suffix planes that extend the (logical) band dimension are called
BACKPLANES.
Suffix planes that extend the (logical) sample dimension are called SIDEPLANES.
Suffix planes that extend the (logical) line dimension are called BOTTOMPLANES.
Note that these terms refer to the logical axes and are not necessarily
related to the physical storage of the cube data object.
The suffix planes are used for storing auxillary data that are
associated with the core data. For example, a backplane might be used
for storing the latitude values for each spatial-spatial pixel. Another
backplane might be used for storing the wavelength of the deepest
absorption feature that was found in the spectrum at each
spatial-spatial pixel. One
or more sideplanes might be used for storing engineering data that are
associated with each spatial line.5.4.3 - CORNER REGIONS
If a cube file includes suffixes on more than one axis, then the
region that is the intersection between two (or all three) of the
suffix regions is called a CORNER region. Corner region data are
currently not used.5.4.4 - PIXEL STORAGE SIZES
In a standard three-dimensional cube file, core pixels can be
stored in one of three different formats, which occupy one, two,
or four bytes. All the core pixels within a single file must be of
the same storage size. All suffix pixels always occupy four bytes
of storage in the file.
However, several different formats are supported for the contents of
a four-byte suffix pixel. Handling of different pixel data types
is described in detail below.5.4.5 - PIXEL COORDINATES
The pixel indexing that is used by the I/O routines allows use of
the "logical" coordinate system shown in
the diagram above. SAMPLE=1 is the left edge of the spatial-spatial
core image. LINE=1 is the top edge of the spatial-spatial core image.
BAND=1 corresponds to the spatial-spatial image at the "front" of the
diagram. Coordinates within the suffix regions are independent of
the core coordinates and are not an extension of the core coordinates.
Thus, the first suffix on an axis has a coordinate of 1. However,
suffixes are usually identified by name rather than by index number.5.4.6 - STORAGE ORDERS
The disk file in which a cube data object is stored is physically
accessed as if it were a one-dimensional data structure. Storing the
cube pictured above thus requires that the "logical" three-dimensional
structure be mapped into the one-dimensional physical file structure.
This involves moving through the three-dimensional structure in certain
patterns to determine the linear sequence of core and suffix pixel
values that occur in the file. In ISIS cube files this pattern is
defined by specifying
which axis index varies fastest in the linear sequence of
pixel values in the file, which axis varies second fastest, and which
axis varies slowest.
(SAMPLE, BAND, LINE) - Band Interleaved by Line (BIL)
(BAND, SAMPLE, LINE) - Band Interleaved by Pixel (BIP)5.5 - PIXEL DATA TYPES
The following sections describe the standard supported data
types for core pixels and suffix pixels.5.5.1 - TYPE CODES AND LABEL KEYWORDS
The data type for core pixels is described by two label keywords.
CORE_ITEM_BYTES has an integer value that specifies the number of
storage bytes occupied by a pixel value. CORE_ITEM_TYPE has a string
value that specifies the internal binary representation of the
stored value. The CORE_ITEM_TYPE values stored in the
label of a cube file include a system-specific prefix, e.g.
"VAX_INTEGER" or "VAX_REAL".5.5.2 - CORE PIXEL DATA TYPES
Conceptually, a core pixel is always considered to have a "real"
number value ("real" as opposed to "integer"). It is very easy to
misunderstand the following discussion if this critical concept is not
recognized. Thus, we will emphasize it:
---------------------------------------------------------------
| CONCEPTUALLY, A CORE PIXEL IS ALWAYS CONSIDERED TO HAVE |
| A "REAL" NUMBER VALUE. |
---------------------------------------------------------------
In a standard ISIS cube file, these core pixel values can be represented
in three different ways, corresponding to different numbers of bytes
used to store the values in the file. When 4-byte format is used, the
stored number is in the format of a native (for the current host computer)
floating-point number that directly
represents the "real" value of the pixel. The other two formats store a
pixel value using 1-byte or 2-byte storage items in the file.
For
these, the stored value is considered to be an integer value and type
conversion
parameters (given by the CORE_BASE and CORE_MULTIPLIER label keywords)
are used to convert the stored integer values into the "real" pixel
values that are being represented. The "real" value being represented
is determined as follows:
"real_value" = CORE_BASE +
(CORE_MULTIPLIER * FLOAT(stored_value))
From the point of view of the user, core pixels always appear to
have these "real" values, i.e., the user can never directly see the
1-byte or 2-byte file values before the application of the type
conversion parameters. (Exceptions to this rule are the histograming
programs HISTGEN, RTGEN and IRT, which have options that allow the
histogram binning to be based on the stored 1-byte or 2-byte core
values.)
In most cases, an application program will
automatically convert 1-byte or 2-byte input pixel values to floating
point and then perform its computations using these floating point
values. It will then automatically convert the computed values to
1-byte or 2-byte format for writing to an output file. Thus, most
application programs are capable of processing files that use any
of the three different formats.
Type CORE_ITEM_BYTES CORE_ITEM_TYPE Type Conversion
Code Parameters
1 1 UNSIGNED_INTEGER Yes
2 2 INTEGER Yes
3 4 REAL No
For 4-byte format the stored values are floating point values that
directly represent the pixel values. In this case, the CORE_BASE and
CORE_MULTIPLIER values are not used. However, they are still required
to be present in the label and should have values of 0.0 and 1.0.5.5.3 - SUFFIX PIXEL DATA TYPES
In a manner similar to core pixel values, several different data
formats can be used for storing suffix pixels. However, unlike
core pixel formats (which can usually be chosen by the user),
suffix pixel formats are usually automatically chosen by the
application programs according to their needs.
Also, unlike core pixel values, suffix pixel values are always stored
in 4-byte items in a standard ISIS cube file. This is indicated by the
SUFFIX_BYTES label keyword, which always has a value of four and is
always required to be present (even if there are no suffixes
stored in the file).
Type axis_SUFFIX_ axis_SUFFIX_ Type Conversion
Code ITEM_BYTES ITEM_TYPE Parameters
4 1 UNSIGNED_INTEGER Yes
5 2 INTEGER Yes
3 4 REAL No
Table of Contents
5.5.4 - BIT-MASKS IN SUFFIX PIXELS
Suffix pixels can be used to store data other than numerical values,
e.g., bit-masks or engineering data that are packed into non-standard
formats.
This is indicated by an axis_SUFFIX_ITEM_TYPE value of "BIT_STRING"
or "BYTE_STRING". The ISIS system design does not put any constraints
on the interpretation of such suffix pixel values. The application
programs can use these data values in any desired manner.5.5.5 - SPECIAL PIXEL VALUES
For each standard core pixel type, a set of stored values is defined
for representing the "special" pixel values. These include the "null"
pixel value and four different "saturated" values. Two of the
saturation values are generated when valid pixel values are being
converted to 1-byte format or 2-byte format and the value being
converted is outside (high or low) the range of values
that can be represented in the
output representation with the given type conversion parameters. The other
two saturation values are used for pixel values that were saturated
(high or low) by
the instrument that generated the data.
These will normally be
identified by the logging program or the translator program that
converts a "foreign" file into standard ISIS cube file format.5.5.6 - SPECIFYING OUTPUT CORE PIXEL DATA TYPES
In most cases, application programs perform their computations
using 4-byte floating point format. If the core pixel values in an input
file are not stored in 4-byte format, then they are first internally
converted to
4-byte format using the type conversion parameters. Most application
programs include the OTYPE TAE parameter, which allows the user to
specify the pixel data type (i.e., type code)
for the output file. The permitted OTYPE
values include 1, 2, and 3, which select 1-byte, 2-byte, and 4-byte
format. In addition, OTYPE=0 may be specified. This value (which is
usually the default) specifies that the data type for the output file
should be the same as the data type of the input file.5.5.7 - DETERMINING RANGE OF VALUES IN A FILE
The pixel data type and the associated type conversion parameters
determine the range of pixel values that can be represented. However,
the range of values actually contained in a file might be much smaller.
The RANGECORE program allows the user to determine the range of pixel
values that are actually contained in the core of a cube file.
This can be done without creating a new output file.
RANGECORE also allows creating a new output file that stores the same
pixel values using a different data type and/or different set of
type conversion parameters. And, the input subcube specifier (see
below) allows RANGECORE to create an output file that is a subarea
of the input file.6.0 - INPUT SUBCUBE SPECIFIER
6.1 - PURPOSE OF THE INPUT SUBCUBE SPECIFIER
The purpose of the input subcube specifier is to allow the user to
specify what parts of an input cube file are to be passed
to the actual
applications code of an application program. This consists of
specifying a list of index values for each region (core and suffix) for
each dimension in the cube. The input subcube specifier allows the
user to specify these index value lists by specifying individual index
values and/or ranges of values. Ranges can optionally be modified by
specifying either an increment value or values within the range that
are to be excluded.6.2 - FORMAT OF INPUT SUBCUBE SPECIFIER
6.2.1 - SUBCUBE SPECIFIER
The input subcube specifier is a string that can contain either the
null string (all blanks) or a list of one or more axis specifiers
separated by colons.
6.2.2 - AXIS SPECIFIER
An axis specifier can contain two parts: a core specifier and a
suffix specifier. Both of these are optional, i.e., a null (blank)
string is permitted as an axis specifier. If both the core
specifier and the suffix specifier are present, then they are
separated by a comma and either one can occur first.6.2.3 - ORDER OF AXIS SPECIFIERS
If the subcube specifier begins with the letter "P" (upper or lower
case), this indicates that the order of the axis specifiers corresponds
to the "physical" storage order of the qube, i.e., fastest varying axis
first. This physical axis mode can be used with any qube file,
including standard ISIS 3D cube files, 3D files with non-standard axis
names or orders, or files with number of dimensions not equal to 3.6.2.4 - CORE SPECIFIER
A core specifier is a list containing any combination of single
element numbers or range specifiers. The elements in the list
are separated by commas.6.2.5 - RANGE SPECIFIER
There are two different forms of range specifier:
Table of Contents
6.2.6 - RANGE MODIFIERS
A range specifier in either of the two possible formats can be
optionally followed by a range modifier. There are two different
forms of range modifiers:
Only one range modifier can be used on a given range.6.2.7 - SPECIAL FORM OF CORE SPECIFIER
A special short-hand form of a core specifier consists of a single
range modifier (an increment or an exclude list) without an explicit
range to be modified. In this case, a range of "1-*" will be assumed.6.2.8 - SUFFIX SPECIFIER
A suffix specifier has exactly the same format as the core specifier
except that it is enclosed in parentheses and the left parenthesis
is preceeded by an upper case or lower case "S" character.6.3 - FORMAL SYNTAX SPECIFICATION
The following is the formal syntax of the subcube
specifier. This uses the syntax notation used in "Standards for
the Preparation and Interchange of Data Sets" (SPIDS), which includes
a specification for the PDS label standards.
[ ] - zero or one occurrence of enclosed item
[ ]* - zero, one, or more occurrences of enclosed item
[ ]+ - one or more occurrence of enclosed item
| - "or"
subcube_spec := [physical_flag] [axis_spec] [: axis_spec]*
physical_flag := P | p
axis_spec := null_string | core_spec | suffix_spec |
core_spec , suffix_spec |
suffix_spec , core_spec
core_spec := core_spec_component [, core_spec_component]* |
range_modifier
core_spec_component := list_element | complex_range
complex_range := range [range_modifier]
range := start_element # count | start_element - end_element
range_modifier := ( increment ) | ~( list )
list := list_component [, list_component]*
list_component := list_element | range
list_element := integer
start_element := integer
end_element := * | integer
count := integer
increment := real
suffix_spec := suffix_flag ( core_spec )
suffix_flag := S | s
6.4 - SEMANTICS AND ADDITIONAL COMMENTS
6.4.1 - USER SPECIFICATION OF INPUT SUBCUBE SPECIFIERS
Input files are selected by TAE parameters that have string values
of length 128. If a program has a single input file, then the file
name will be specified by a TAE parameter named FROM. If there are
multiple input files, the TAE parameter names will be FROM1, FROM2,
etc.6.4.2 - MEANING OF PARTS THAT ARE NOT EXPLICITLY SPECIFIED
If the entire input subcube specifier is the null (blank) string, then
this means that the entire input qube is being selected, including all
of the core and all of any suffix planes that are present. This is
normally the
default value of the TAE parameters that contain the input subcube
specifiers.6.4.3 - INCREMENT
The increment value in a range modifier can be any real number greater
than zero. If an increment value is an exact integer, then the decimal
point is optional. For example, all the following increments have
exactly the same meaning: "(2)", "(2.)", and "(2.0)".
Values less than 1.0 result in pixel replication. This
might be useful for expanding an image in a display program. Increment
values greater than 1.0 result in sub-sampling of the data. If an
increment that is not equal to 1.0 is specified, then the following
algorithm is used for computing the resulting list of indices:
INTEGER LB, UB ! Lower and upper bounds
REAL INC ! Increment
INTEGER L(*) ! List of indices being generated
REAL R ! Temporary real variable
R = FLOAT(LB)
INDEX = 1
100 L(INDEX) = NINT(R) ! Rounding to nearest integer
R = R + INC
IF (NINT(R) .GT. UB) GOTO 200
INDEX = INDEX + 1
GOTO 100
200 CONTINUE
6.4.4 - COUNT AND INCREMENT TOGETHER
If an increment range modifier is used with a range specifier that uses
the start/count format, then the count is used for determining the
upper bound to be used in the above algorithm, i.e., UB = start+count-1.
Note that the count value does not specify the number of index values
in the generated list. For example, "1#10(2)" specifies the
five-element index list "1,3,5,7,9".6.4.5 - DUPLICATING CORE AND SUFFIX INDEX VALUES
There are two ways that duplicate index values can be specified.
First, duplicate values can be specified in an explicit list. Second,
an increment value that is less than 1.0 can be specified. Both
of these are permitted for core index values. However, neither of
these are permitted for suffix index values. The main reason for this
is that it would result in duplicate suffix planes being passed to
the application program (and propagated to an output file). However,
suffix planes are usually identified by the suffix name, which must
be unique within each suffix region.6.4.6 - SUFFIX SPECIFIERS USED WITH MORE THAN THREE DIMENSIONS
The ISIS I/O routines do not support suffixes on qube files that have
more than three dimensions. Thus, suffix specifiers can be used only
when the number of dimensions in the qube file is three or less.6.4.7 - INDEX VALUES
The index values for the core region begin with index value "1" on
each axis.6.4.8 - ORDER OF ITEMS IN A LIST
The index values given in a list must be in strictly increasing order.6.4.9 - WHITE SPACE
Blank characters and tab characters can be included within the subcube
specifier string to improve readability. These "white space"
characters do not effect the meaning of the subcube specifier and they
can be included at any location except between characters that are forming
numbers or file names (see next section).6.4.10 - STORING SUBCUBE SPECIFIER IN A FILE
All or part of a subcube specifier string can be contained in a disk
file that is an ordinary text file created by a text editor. The use
of such a file is indicated by enclosing the file name within corner
bracket characters (<>) and putting it into the user-specified subcube
string at the location at which the file contents are to be used.
The file contents can contain multiple lines of text. However, the
break between different lines does not effect the meaning of the
subcube specifier. This feature is useful when the length of the
subcube specifier string would exceed the 128 character length of the
TAE parameter or when the same subcube specifier is to be used for
several different application programs. The text within the file
cannot contain a reference to another file.6.5 - INPUT SUBCUBE SPECIFIER EXAMPLES
The following examples of the input subcube specifier are assumed to
be used with an input file that is a standard ISIS 3D cube containing
100 samples, 200 lines, 83 bands, and 12 backplanes (suffixes in the
band direction). Also, the input cube file is assumed to be stored in
band interleaved by pixel (BIP) storage order, i.e., the storage order
is (band, sample, line).
1. " " Entire cube file: all of the core
plus all backplanes
2. ":" Same as above
3. "::" Same as above
4. "1-100" Same as above
5. ":1-200" Same as above
6. "::1-83" Same as above
7. "::S(1-12)" Same as above
8. "1-100 : 1-200 : 1-83,S(1-12)" Same as above
9. "1-100 : 1-200 : S(1-12),1-83" Same as above
10. "P1-83,S(1-12) : 1-100 : 1-200" Same as above
11. "1-* : 1-* : 1-*,S(1-*)" Same as above
12. "25-74 : 25#50" 50x50 spatial area, all bands, plus
all backplanes
13. "1-*(2) : (2)" Every other spatial pixel in sample
and line directions; all bands;
all backplanes
14. ":: 3-6, 10-20~(12,16-18)" Core bands 3,4,5,6,10,11,13,14,15,
19, and 20; all backplanes
15. ":: ~(4, 10-12, 25#3)" All bands except 4,10,11,12,25,26,27
16. "::S(3,5,7-12~(9,11))" All of the core; backplanes 3,5,7,8,
10,12
17. "::S(~(1-*))" All of the core; none of the backplanes
18. "<SUBSPEC.TXT>" Entire subcube specifier is contained
in the file
19. ":: 1-*~( <BADBANDS.TXT> )" All bands except the "bad" bands listed
in the file; all backplanes
7.0 - INSTRUMENT SPECTRAL LIBRARY FILES
Instrument spectral library (ISL) files are used for storing
collections of spectra and associated header information that
identifies each spectrum. All the spectra in a given ISL file have the
same set of wavelengths, which corresponds to one of the observing
modes of a given instrument. Different ISL files can contain different
sets of wavelengths. ISL files can be used for storing data obtained
from laboratory spectral measurements. ISL files can also be used
for storing spectra (or average spectra) that are extracted from
cubes of data produced by flight instruments.8.0 - TABLE FILES
One of the major types of data files handled by ISIS is the Table
file. A typical example of a Table file is an average spectrum file
containing data for a given spatial area. Such a data file can be
produced by the CUBESPEC program.
Each row of the table corresponds to one wavelength band of the
spectrum and contains several different data values, e.g., band number,
wavelength, average spectrum value, standard deviation, etc.
Different table files can have different numbers of rows or
columns in order to serve various instrumental and analysis
objectives.8.1 - BASIC TABLE FILE STRUCTURE
ISIS Table files are stored as standard PDS labelled files.
In a manner similar to cube files, the beginning
of the file contains a descriptive label area. Appendix C
contains an example label for an ISIS Table file. A Table file
is required to contain a History data object, which is the same
as the cube file History object.
The actual table data are stored in a binary format in a Table
data object within the Table file.8.2 - TABLE DATA OBJECT FORMAT AND LABEL KEYWORDS
A Table data object contains rows of data stored in a binary
format. The number of rows contained in a Table object is recorded
in the ROWS keyword in the Table data object description in the
label.8.3 - PROTOTYPE TABLE FILE FORMAT
Some of the older ISIS programs make use of tables that are
stored in a prototype ASCII text format. These are
ordinary text files that can be printed or examined with a text
editor. The beginning of the table file is a section that contains
various header and identifying information. This is terminated by
a line that contains "C_END". The remainder of the file contains
the actual table data in the format of one table row per line.8.4 - TRANSLATING TABLE DATA BETWEEN BINARY FORMAT AND ASCII FORMAT
The TBL2ASC program translates table data from a standard
ISIS binary table file into an ASCII text format so that it can
be printed or examined with a text editor. The default operation
of this program will translate all columns of table data using the
default formats that are recorded in the COLUMN_ITEM_FORMAT label
keyword. The user can also specify other desired formats for the
binary to text conversion and/or select a subset of the columns to
be converted. Multiple text lines will be used for each row of
table data if the ASCII format of the converted columns is too long
to fit within the user-specified line length.9.0 - PROCESSING MODES
9.1 - SINGLE INPUT FILE
Some ISIS application programs have a single input cube file
but no output cube file. In this case the input file is specified
by the FROM TAE parameter, and the TO parameter is not used.
An example of this is the LHLIST program, which produces a listing
of the label and/or history of an input cube file.9.2 - SINGLE OUTPUT FILE
Some ISIS application programs create a new output cube file
without reading an input cube file. Such programs use the TO
parameter but do not use the FROM or SFROM parameters.9.3 - SINGLE INPUT FILE PLUS SINGLE OUTPUT FILE
Many of the cube processing application programs read cube data
from an input file and produce a processed version of these data.
There are three basic processing modes in which such programs might
operate:
All three of these processing modes can be found among the various
ISIS applications programs. However, not all programs include all
the modes.9.4 - MULTIPLE INPUT/OUTPUT FILES
Some application programs may have multiple input and/or multiple
output cube files. These make use of parameters such as FROM1 and
FROM2 to specify the input files and parameters such as TO1 and TO2
to specify the output files. In most cases, these programs are only
capable of reading from the input files and writing to the new output
files that are being created.10.0 - SELECTING DIFFERENT ISIS RELEASE VERSIONS
ISIS is undergoing continual development, and periodically a
new release of ISIS is made available. When the user initially
enters TAE, he will be using the set of programs that form the
latest ISIS release. The previous ISIS release is called the
"old" release and can be selected by running the SETOLDISIS program,
which has no TAE parameters. The latest ISIS release is called
the "new" release, and is selected by running the SETNEWISIS program.11.0 - UPDATING THIS USER'S MANUAL
Each new release of ISIS includes a file that contains the
entire current version of this User's Manual, thus incorporating
any new and/or changed program descriptions plus any new versions
of the appendices or this Introduction to ISIS.