ISIS 2 Documentation

# 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
MULT 22
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.

```
ParmDescriptionDefault
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
```
`" "`

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