Isis 2 Documentation
ISIS Appendix D - Subcube Specifier
Table of Contents
1.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. It is a tool to specify a "sub-area" of your cube. This consists
of specifying a list of index values and/or ranges of index values for
each dimension (sample,line,band) of each region (core and suffix). All
examples shown below can be used for any dimension, including suffixes.
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.
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.
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.
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.
There are two different forms of range specifier:
- Start/count form - contains a starting element number
and a count of elements separated by a number sign (#),
e.g., 6#4 indicates elements 6, 7, 8 and 9.
- Start/end form - contains a starting element number and an
ending element number separated by a dash (minus sign).
An asterisk (*) can be used as the ending element number
and is equivalent to the highest index number that occurs
in the file for the corresponding axis.
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:
- Increment - indicated by specifying the increment
value enclosed in parentheses.
- Exclude values - indicated by enclosing the list of values
to be excluded from the range within parentheses. The
left parenthesis must be preceeded by a "~" character.
The values being excluded can be specified as a list
containing any combination of single elements or ranges
(either start/count form or start/end form). However, these
ranges cannot be further modified by increments or values to
be excluded.
Only one range modifier can be used on a given range.
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.
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.
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
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.
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 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.
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 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
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".
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.
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.
The index values for the core region begin with index value "1" on
each axis.
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.
The index values given in a list must be in strictly increasing order.
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).
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.
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
Last updated: Oct 24 2003
File: isis_apd.html
Contact us online at the Isis Support Center: http://isisdist.wr.usgs.gov
ISIS Documentation Home Page