ISIS Application Documentation
fx  Standard View  TOC  Home 
Apply generalized arithmetic operations using multiple cube files
Description
Categories
Groups
Examples
History
Fx allows general arithmetic operations to be performed on an arbitrary number of input cubes. Fx loads whatever input files are specified, applies a user defined equation to those files and writes the results to an output file. The input file can be a single band or multiple band cube file. If the band number is not specified for the multiple band cube file, then the equation is applied to all the bands within the file.
Five files or fewer can be entered for parameters F1 to F5 under the "Input Cube Files" section to specify the input data. A second method to specify data is to include an arbitrary number of files in a file list and enter the list name in the fromlist parameter that is only visible upon selecting the MODE list located under "File I/O Mode." If the user selects "OUPUTONLY" under "File I/O Mode" then an output file is created based on an equation provided by the user. The user will also need to specify the number of lines, samples, and bands of the output file.
The command line parsing has been improved to handle escape sequences and support arrays better. The equation parser is case insensitive, ignores whitespace, and converts all braces to parentheses. Parameter values, when quoted, no longer need the quotes escaped.
The command line syntax changes are as follows (with TCSH/BASH examples):
TCSH/BASH
Before: crop from=\"some file.cub\" to=\"output file.cub\"
Now: crop from="some file.cub" to="output file.cub"
Please note that the dollar sign ($) still requires a backslash for batchlist variables. Array values, for programs such as spiceinit, will be the same.
TCSH
Before: spiceinit from=input.cub ck='(file1.bc,file2.bc)'
Now: spiceinit from=input.cub ck='(file1.bc,file2.bc)'
BASH
Before: spiceinit from=input.cub ck='(file1.bc,file2.bc)'
Now: spiceinit from=input.cub ck='(file1.bc,file2.bc)'
An escape character "\" has been added to differentiate a first parenthesis from the beginning of an array sequence.
TCSH
Before: fx equation='"(1+2)/2"'
Now: fx equation='\(1+2)/2'
BASH
Before: fx equation='"(1+2)/2"'
Now: fx equation=\(1+2)/2
The equation string entered within a GUI interface may not work if the entire string is copied, pasted, and executed at the command line. If the first character in the equation is a "(" then it must be prefixed by a "\" when executing as a command line, but the remaining parentheses do not need to be prefixed with a backslash.
Example:
This equation string works inside the fx GUI:
fx f1=BIFQF23N004_D218_T069S02_V02_I3.cub to=tt.cub equation=(f1*(f1>.004))These equation strings fail on the command line:
fx f1=BIFQF23N004_D218_T069S02_V02_I3.cub to=tt.cub equation=(f1*(f1>.004))
fx f1=BIFQF23N004_D218_T069S02_V02_I3.cub to=tt.cub equation="(f1*(f1>.004))"This equation string works on the command line:
fx f1=BIFQF23N004_D218_T069S02_V02_I3.cub to=tt.cub equation="\(f1*(f1>.004))"
Note: The use of negative numbers within an equation could cause problems in the latest version of ISIS. The "" or "neg" operators are specifically designed to handle negative numbers within an equation. If an equation includes a negative number, prefix the value with a "" instead of "" in the equation.
Example:
equation="f1*(0.018*sec*(f3*pi/180)^2+f2+4.4234)"
or
equation="f1*(neg(0.018)*sec*(f3*pi/180)^2+f2+4.4234)"
For additional information see Command Line Usage under the User Documentation web pages for ISIS.
Note: Some instructions may be outdated.
The equation parser is case insensitive and all braces, such as "[{[{ }]}]" are converted to parentheses "(((( ))))" first. Whitespace is ignored. Currently, you must explicitly state all multiplication operations (e.g. 2pi will not work, but 2*pi will). The modulus (%), AND, and OR operators are not implemented yet. Functions such as pha, ina, ema, lat, lon, radius, and resolution require a Level1 input file with SPICE information in the image labels. That is, the program spiceinit should be executed on the input files before using these functions. For Level2 images, the backplanes containing the photometric and spatial information must be present. This is normally performed with the program phocube before the image is projected to a map projection.
Requirements and result of operators
The following operators return a "0" or "1" DN value when they are used
in the equations:
< , >, <=, >=, ==, !=
The following operators are used to shift pixels left or right, and move the entire image to different sample and line positions:
<<, >>
Example:
Some pixels are set to NULL depending on whether the left or right pixel shift operation is used. For example, the left image below is the input file, and the right image is the result of "equation = f1 << 10", which shows a 10 pixel shift to the left.
Sample 1 line 1 of the left image maps outside the image area of the right image; therefore, sample 11 line 1 of the left image maps to sample 1 line 1 of the right image, and sample 12 line 1 of the left image maps to sample 2 line 1 of the right image. The remaining pixels that do not have an assigned pixel value are set to NULL.
The following operators use the input image statistics to apply the equations:
linemin, linemax, cubemin, cubemax, cubeavg, cubestd
The min and max operators are used to compare two pixel values. The pixel values can be obtained from input files or manually entered by the user. The two values are compared against each other and the one that meets the equation criteria is used.
min, max
In order to use the camera operators, images must be processed through spiceinit so that the NAIF camera model information is stored in the image labels. These operators calculate values on a bandbyband basis so that banddependent images have correctly calculated camerarelated values.
pha, phal, phac, ina, inal, inac, ema, emal, emac
lat, lon, radius, resolution
The following operators are used to convert between degrees and radians:
rads, degs
All trigonometric functions expect angles in radians, not degrees. However, all camera functions return angles in degrees and therefore should be converted to radians.
The following table shows all currently supported scalars and special tokens:
SCALARS  
Scalar  Description  Example 

F#  File operator  f3 denotes third file 
# or #.# or .#  Any integer or double  12, 3.14, .007 are all valid 
band  Current band number  f1 * band 
line  Current line number  line + f1 
sample  Current sample number  sample / line + f1 
pi  Pi (3.14159...)  f1 > (e^pi) 
e  Euler's number (2.71828...)  f1 == ln(e) 
The following table shows all currently supported operators sorted by precedence (0 = highest precedence). All examples are valid equations that assume one or more files (F1, F2, etc.) are loaded:
OPERATORS  
Precedence Level 
Operator  Description  Example 

0  { [ ( ) ] }  Parentheses, brackets, or braces  f2*(f1+[30{line/pi}]) 
1   or neg  Negative sign  f1 + f2 or neg(f1) + f2 
1  abs  Absolute value  abs(f2  f1) 
1  min  Minimum of two DNs  f1 + min(5, f2) + min(f2, f3) 
1  max  Maximum of two DNs  20 * max(f1,f2) 
1  linemin  Minimum of DNs on the current line  f1 + linemin(f2) 
1  linemax  Maximum of DNs on the current line  f1 + linemax(f2) 
1  cubemin  Minimum of a cube  f1 + cubemin(f2) 
1  cubemax  Maximum of a cube  f1 + cubemax(f2) 
1  cubeavg  Average of a cube  f1 / cubeavg(f1) 
1  cubestd  Standard deviation of a cube  f1 * (abs(f1cubeavg(f1)) < 2*cubestd(f1)) 
1  sin  Sine  f1 * sin(123/321) 
1  cos  Cosine  cos(.02*50) 
1  tan  Tangent  tan(f1/f2) 
1  csc  Cosecant  12.3 + csc(f1) 
1  sec  Secant  sin(pi/60) + (sec(f2))^2 
1  cot  Cotangent  line + cot(f1)  42 
1  asin  Arcsine  0.006 ^ asin(f1*5) 
1  acos  Arccosine  acos(1/[2*pi]) 
1  atan  Arctangent  atan(f1/e) 
1  atan2  Arctangent2  atan2(10 5.5) 
1  sinh  Hyperbolic sine  55 + sinh(f2) 
1  cosh  Hyperbolic cosine  cosh(sample^pi) 
1  tanh  Hyperbolic tangent  tanh(f1) 
1  log or ln  Natural log  ln(abs(1/[f2f1])) 
1  log10  Log base 10  99 + log10(f1160) 
1  sqrt  Square root  sqrt(abs[1000  f2]) 
1  pha  Phase angle on the ellipsoid  pha(f1) 
1  ina  Incidence angle on the ellipsoid  ina(f1) 
1  ema  Emission angle on the ellipsoid  ema(f1) 
1  phal  Local phase angle on DTM  phal(f1) 
1  inal  Local incidence angle on DTM  inal(f1) 
1  emal  Local emission angle on DTM  emal(f1) 
1  phac  Phase angle on the ellipsoid at image center  phac(f1) 
1  inac  Incidence angle on the ellipsoid at image center  inac(f1) 
1  emac  Emission angle on the ellipsoid at image center  emac(f1) 
1  rads  Convert degrees to radians  f1 / cos(rads(pha(f1))) 
1  degs  Convert radians to degrees  degs(acos(f1)) 
1  lat  Latitude  lat(f1) 
1  lon  Longitude  lon(f1) 
1  radius  Radius of DTM in meters  radius(f1) 
1  res  Pixel resolution in meters  res(f1) 
2  ^  Exponent  f1 ^ 3 
3  *  Multiplication  10 * f1 
3  /  Division  f2 / f1 
4  <<  Left shift (Note: pixel shift, not bitwise)  f1 << 250 
4  >>  Right shift (Note: pixel shift, not bitwise)  f2 + (f1 >> 500) 
5  +  Addition  123 + 0.004 + f1 
5    Subtraction  10  (f1) 
6  >  Greater than (Note: result is 0 or 1)  f1 > f2 
6  <  Less than (Note: result is 0 or 1)  f1 * (f1 < cubeavg(f1)) 
6  <=  Less than or equal (Note: result is 0 or 1)  f1 <= 0.505 
6  >=  Greater than or equal (Note: result is 0 or 1)  f1 * (f1 >= 101) 
6  ==  Equal to (Note: result is 0 or 1)  f1 == (f2/2) 
6  !=  Not equal to (Note: result is 0 or 1)  f1 != f2 
Name  Description 

F1  Input filename 
F2  Input filename 
F3  Input filename 
F4  Input filename 
F5  Input filename 
TO  Output cube filename 
Name  Description 

FROMLIST  Input list filename 
Name  Description 

EQUATION  Image processing equation 
Name  Description 

MODE  File I/O options 
Name  Description 

LINES  Number of lines 
SAMPLES  Number of samples 
BANDS  Number of bands 
Input ISIS cube filename.
Type  cube 

File Mode  input 
Filter  *.cub 
Input ISIS cube filename.
Type  cube 

File Mode  input 
Internal Default  None 
Filter  *.cub 
Input ISIS cube filename.
Type  cube 

File Mode  input 
Internal Default  None 
Filter  *.cub 
Input ISIS cube filename.
Type  cube 

File Mode  input 
Internal Default  None 
Filter  *.cub 
Input ISIS cube filename.
Type  cube 

File Mode  input 
Internal Default  None 
Filter  *.cub 
This is the output file created based on a user defined equation.
Type  cube 

File Mode  output 
Pixel Type  real 
Filter  *.cub 
This file contains a list of all the cube files to be processed. Each file will be assigned F1 to F##(number of images in the input list).
Type  filename 

File Mode  input 
Filter  *.txt *.lis 
This equation will be parsed and used to perform the specified calculations.
Type  string 

Select one of the following options: CUBES to input cubes directly, LIST to enter a text file containing a list of filenames, or OUTPUTONLY to create output data only.
Type  string  

Default  CUBES  
Option List: 

This is the number of lines the output cube will have.
Type  integer 

Default  1 
Minimum  1 (inclusive) 
This is the number of samples the output cube will have.
Type  integer 

Default  1 
Minimum  1 (inclusive) 
This is the number of bands the output cube will have.
Type  integer 

Default  1 
Minimum  1 (inclusive) 
Add two images
Example GUI Screenshot of GUI with parameters filled in to perform a calculation on the input image. 
Input file band 1
Parameter Name:
F1 This is the first input image for the fx example. 

Input file band 2
Parameter Name:
F2 This is the second input image for the fx example. 
Output file
Parameter Name:
TO This is the 500 by 500 output image containing the results.

Create output only
cos(rads(line))The line number is input as degrees and converted to radians first in order to output the correct cosine values.
Example GUI Screenshot of GUI with parameters filled in to perform a calculation to create an output image. 
Output file
Parameter Name:
TO
This is the output file created based on a user defined equation without
specifying input filenames.

Create output only
Example GUI Screenshot of GUI with parameters filled in to perform a calculation to create an output image. 
Output file
Parameter Name:
TO
This is the output file created based on a user defined equation
without specifying input filenames.

Apply a gamma stretch
Example GUI Screenshot of GUI with parameters filled in to perform a calculation on the input image. 
Input file
Parameter Name:
F1
This is the input image for the fx example. 
Output file
Parameter Name:
TO
This is the output image where the bright and dark tones in the input
image are adjusted based on the input image statistics that are incorporated
into the equation that is applied to calculate new output values.

Create mask file
Example GUI Screenshot of GUI with parameters filled in to perform a calculation on the input image. 
Input file
Parameter Name:
F1
This is the input image for the fx example. 
Output file
Parameter Name:
TO
This is an image consisting of "0" and "1" DN values based on
the equation provided.

Extract desired data
Example GUI Screenshot of GUI with parameters filled in to perform a calculation on the input image. 
Input file
Parameter Name:
F1
This is the input image for the fx example. 
Output file
Parameter Name:
TO The pink areas in this image were set to "0.0" based
on the equation entered. All other values retained the original values
because the input value was multiplied by 1.0 when the calculations
were performed.

Kris Becker  19970424  Original version 
Sean Crosby  20070214  Converted to Isis 3 
Steven Lambright  20070618  Added single line and sample functionality 
Steven Lambright  20080416  Upgraded to work with new Calculator classes 
Steven Lambright  20081217  Renamed parameter FILELIST to FROMLIST 
Steven Lambright  20090417  Updated documentation to reflect the units of the trig functions 
Steven Lambright  20100408  Min, max capabilities have been expanded to include line and cube min/max 
Jeff Anderson  20120209  Added cubeavg, cubestd, rads, degs, neg, pha, ina, ema, phac, inac, inal, phal, emal, res, lat, lon, and radius functions 
Ella Mae Lee  20121022  Improved documentation and added examples, reference Mantis issue #977 and #992 
Lynn Weller  20130225  Removed links to applications imbedded in text and replaced with italicized application name. Added application links to the "Related Objects and Documents" section of the documentation. Fixes mantis ticket #1525. 
Tracie Sucharski  20131211  Fixed bug where the cube attributes on files in the fromlist were ignored. Fixes #1926." 
Moses Milazzo and Ian Humphrey  20161013  Fixed bug where camera related operators produce incorrect calculations for banddependent images. The camera operators now make calculations on a bandbyband basis, meaning banddependent images are now supported with correct calculations. Fixes #1301. Backward Compatibility Issue: The changes made will impact any scripts that use the fx camera operators on banddependent images, producing different output for each band. 