ISIS 2 Documentation

fx - Generalized arithmetic operations using multiple cube files fx allows general arithmetic operations to be performed on one to eighteen input ISIS cube files. All data organizations, BSQ, BIL, and BIP, are supported. The arithmetic operation is specified by a FORTRAN or C-like expression which can include the following operators (synonyms connected by an =): + - * / ** unary- LOG = ALOG = LN (all these = natural (base e) log) LOG10 = ALOG10 (all these = common (base 10) log) SQRT ABS AINT = INT SIN COS TAN ASIN ACOS ATAN ATAN2 AMAX1 = MAX AMIN1 = MIN AMOD MOD .AND. .OR. .XOR. .NOT. .LT. .LE. .EQ. .NE. .GT. .GE. as well as the following C-operators: & && | || % ^ ! == != >= <= > < >> << Operands to fx can be : integers floating point numbers F1 F2 F3 F4 ... F18 LINE SAMP BAND NUL LRS LIS HIS HRS PI The function string can include constants, including constants expressed in floating point notation. Lengthy equations that exceed the maximum string length of the FUNCTION variable can be put in a file specfied by the EQFILE parameter. Any line that contains a "#" sign as the first element will be ignored. It can contain any number of lines of which they are simply concatenated together...there is no concatenation operated needed. fx can operate on zero inputs to generate an output using the operands LINE, SAMP, and BAND. fx performs arithmetic operations on image files. The program uses two library routines, KNUTH and XKNUTH, to compile and execute FORTRAN or C-like expressions entered by the parameters in the FUNCTION expression such as: ((F1+F2)*(AINT(ALOG10(F1*F2**2))+3.14+F1/22)+4*(LINE.EQ.SAMP) or: ((f1 + f2) % (3*(line!=samp))) << 3 F1 is an element from the first input and F2 is the corresponding element from the second input. KNUTH compiles the expression into instructions executable by XKNUTH. The expression is applied to the pixels from each input in XKNUTH to produce the output picture. When performing arithmetic, fx converts all integer operands to real and executes single precision floating point computations. The exceptions are the logical operators .AND.(&), .OR.(|), .XOR.(^), as well as the shift operators (>>) and (<<), all of which operate bitwise on the 4-byte integer equivalent to the truncated floating point number. The logical values 'TRUE' and 'FALSE' when produced, are interpreted as 1 and 0 respectively. The logical NOT operates only on the values 0 and 1. Because of the type of calculations done on images, the routine XKNUTH is designed to never abort regardless of input values. Illegal operations result in the generation of a ISIS special pixel values or some "reasonable" substitution. Some result as follows: a) divide by zero causes NULL; b) log of a negative number causes log its absolute value, etc. The routine KNUTH quits processing, prints an error message and returns if a syntax error is detected in the expression string. SFROM may be used to specify subsections of the input files. KNUTH compiles the function expression into instructions that XKNUTH can execute. For example, the expression "IN1*10+IN2" will be decomposed as LOAD 1 MULT 22 ADD 2 RETN 0 The F1 thru F18 are stored in location 1 thru 18, LINE, SAMP, and BAND are stored in later locations. Space is also separately reserved in the executable buffer for static constants, temporary registers and executable code. RESTRICTIONS: The program has no restriction on any dimension. Note that the number of elements in each dimension must match cooresponding axes in all input file OR it must have just one element. This allows for spectrum operations or single band operations on multi-band input files. The expression must not contain more than 30 constants, 20 variables, or roughly 80 operations. Embedded blanks are allowed. The expression is case insensitive. PROGRAMMER: Kris Becker, USGS, Flagstaff, Az.

Parm | Description | Default |
---|---|---|

FROM | Input cube file names. There can be anywhere from 0 to 18. (default extension is .cub) | -- |

SFROM | Input subcube specifiers for each input file in FROM. | -- |

TO | Output cube file name (default extension is .cub) | NONE |

DIMS | Dimensions of output cube if no files are provided in FROM | -- |

FUNCTION | Is the equation that is to be applied to the input files (if given) | -- |

EQFILE | An alternative method to input a function. This is taken to be a file containing the equation. | -- |

LIMITS | Range of values to be included in the function. | -- |

LOWREPL | Value to use when a low limit is encountered. Default is NUL | -- |

HIREPL | Value to use when a high limit is encountered. Default is NUL | -- |

REPLACE | Value used when a value cannot be calculated. Default is NUL | -- |

DUMP | Do a symbolic dump of the compiled code. | "NO" |

PROPFILE | Allows user to select which input file is used to create output file. Should be 1 to 18 or none. | 1 |

OTYPE | Output pixel type NULL = input type 1 = 8 bit 2 = 16 bit 3 = 32 bit | -- |

ORANGE | Output min/max data range | -- |

USERNOTE | User comment | " " |

**ADDITIONAL NOTES:
**

Parm | Description |
---|---|

FROM | The list of input files used in the function. There should be a file for every Fx in the specified function where x is 1 to the number of files. If 2 files are given, then only F1 and F2 may appear in the function. Note that the same file may appear more than one time in the FROM list. This will result in the same file being opened and accessed more than once. |

SFROM | SFROM is the subcube specifier for each input file. It allows the user to specify the subcube using a single string for all three dimensions of the cubes. 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 | Name of output image. |

DIMS | This parameter is only relevant when no files are provided in FROM. This tells fx the dimensions of each axis in the output file. DIMS(1) is the number samples, DIMS(2) is the number of lines and DIMS(3) is the number of bands that will be allocated to the output cube file resulting from the fx equation specified in FUNCTION. |

FUNCTION | FUNCTION specifies the equation that will be applied to the input files. Files are referenced in the equation as F1 thru F18, where F1 corresponds to the file specified in FROM(1), F2 to FROM(2) and so on. When no files are provided in FROM, then fx will generate an output file based upon the equation. In this mode, there can be no references to input files using the "F" designation since there were none given. Generally, there are almost endless possible functions that fx can process. See general help as it contains a lengthy discussion on function construction. |

EQFILE | This optional argument is provided for very lengthy or complicated functions. Should the user interface, TAE for instance, have a limit on input character length, this argument provides a way to pass along these types of equations fx and parsing can take place as normal. Note that any line that begins with a # is ignored. The equation is allowed to span lines and no special continuation characters are required...it is free form. Function equations are limited to 32767 characters. |

LIMITS | Allows the user to limit the data range of all input values. The input values are scanned prior to executing the function for values outside the range specified by LIMITS. LIMITS(1) is the minimum allowed value and LIMITS(2) is the maximum. Values outside this range are replaced by the value of LOWREPL and HIREPL, respectively. |

LOWREPL | This value will be used to replace values that are less than LIMITS(1). It can be the special ISIS monikers for special pixels, "LIS", "LRS", "HIS", "HRS" or "NUL". Otherwise it can be any real value. |

HIREPL | This value will be used to replace values that are greater than LIMITS(2). It can be the special ISIS monikers for special pixels, "LIS", "LRS", "HIS", "HRS" or "NUL". Otherwise it can be any real value. |

REPLACE | This value will be used to replace values that cannot be computed for some reason. It can be any one of the ISIS monikers for special pixels, "LIS", "LRS", "HIS", "HRS" or "NUL". Otherwise it can be any real value. |

DUMP | This parameter tells fx to generate a dump of the Knuth compiler instructions that will be used to execute the function provide in the FUNCTION parameter. Its pretty obfuscated and generally isn't too useful except for those familiar with such things. It aids in debugging the equation. |

PROPFILE | Specify the index of the FROM file that will have all its label information propagated to the TO file when created. If no file is desired for propagation of labels set this parameter to the TAE null value "--". |

OTYPE | Output pixel data type. Permitted values are: NULL = output type is same as input file pixel type 1 = 8-bit (integer with type conversion parameters) 2 = 16-bit (integer with type conversion parameters) 3 = 32-bit (floating point) When processed data are being written back into the input file, the output pixel type must be the same as the existing pixel type in the input file. |

ORANGE | Output pixel data range. If ORANGE is NULL, then the CORE_BASE and CORE_MULTIPLIER in the output file will be set to represent the same range of data as the input file. If OTYPE=1 (8-bit) or OTYPE=2 (16-bit), then the CORE_BASE and CORE_MULTIPLIER in the output file will be set to values that allow representing the specified range of output values. Output values outside this range will be stored as a special "representation saturation" value. The ORANGE parameter is ignored if OTYPE=3 (32-bit) since the CORE_BASE and CORE_MULTIPLIER are not applicable to floating point pixel values. **NOTE** For a more detailed explanation of ORANGE, tutor the orange.pdf. |

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

**
****
**