USGS

ISIS 2 Documentation


Isis ISIS Appendix D - Subcube Specifier

----

Table of Contents

1.0 - FORMAT OF INPUT SUBCUBE SPECIFIER

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.

1.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.

1.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.

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.

1.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.

1.5 - RANGE SPECIFIER

There are two different forms of range specifier:

  1. 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.

  2. 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.

1.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:

  1. Increment - indicated by specifying the increment value enclosed in parentheses.

  2. 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.

1.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.

1.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.

2.0 - 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

3.0 - SEMANTICS AND ADDITIONAL COMMENTS

3.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.

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.

3.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.

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.

3.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

3.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".

3.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.

3.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.

3.7 - INDEX VALUES

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.

3.8 - ORDER OF ITEMS IN A LIST

The index values given in a list must be in strictly increasing order.

3.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).

3.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.

4.0 - 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

----
Documentation | Tutorials | Technical Documents | Isis Support Center (URL: http://isis.astrogeology.usgs.gov/IsisSupport/) | Home

Last updated: Oct 24 2003