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

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

--

Input subcube specifiers for
each input file in FROM.

--

Output cube file name
  (default extension is .cub)

NONE

Dimensions of output cube if
no files are provided in FROM

--

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

--

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

--

Range of values to be included
in the function.

--

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

--

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

--

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

--

Do a symbolic dump of the
compiled code.

"NO"

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

1

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

--

Output min/max data range

--

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.