ENVI User's Guide: Basic Tools

Band Math
ENVI Band Math is a flexible image processing tool with many capabilities not available in
any other image processing system. You can use ENVI's Band Math dialog to define bands
or files used as input, to call a user Band Math function, and to write the result to a file or
memory. ENVI's Band Math function accesses data spatially by mapping variables to
bands or files. Spatial data that are too large to read entirely into memory are automatically
accessed using ENVI's data tiling.
The following figure depicts Band Math processing that adds three bands. Each band in the
expression is mapped to an input image band, summed, and output as the resulting image
data. You can map one or more of the expression's variables to a file instead of mapping
each variable to a single band. The resulting output is a new image file. For example, in the
expression b1 + b2 + b3, if b1 is mapped to a file and b2 and b3 are mapped to a single
band, then the resulting image file contains the bands of the b1 file summed with b2 and b3.
Figure 3-8: Band Math Processes — Addition of Three Bands

Some common image summing operations are easier to perform using the Basic Tools 
Statistics  Sum Data Bands selection (see Summing Data Bands).

Entering Mathematical Expressions

1. From the ENVI main menu bar, select Basic Tools  Band Math. The Band Math
dialog appears.
 
2. In the Band Math dialog, enter the desired mathematical description, including variable
names, into the Enter an expression field. Use variables in place of band names or
filenames (the variables will be assigned in the next step). Variable names must begin
with the character "b" or "B" followed by up to 5 numeric characters.
 
For example, to calculate the average of three bands, use the following equation:
1
 (float(b1)+float(b2)+float(b3))/3.0

Three variables are used in this expression: B1, B2, and B3. Note that, in this
example, the IDL function float() is used to prevent byte overflow errors during
calculation. Please see Band Math Requirements for further details.
 
The Band Math dialog also contains the following functionality:
Previous Band Math Expressions — This list shows previously applied
mathematical expressions. To apply an expression to a new set of bands, select
it from the list and enter it into the Enter an expression field. Click OK.
 
Save — Save mathematical expressions to a file. The Save Expressions to a
File dialog appears. Enter an output filename with an .exp extension. Click OK.
You can save expressions to a file without having to first run them through the
Band Math function.
 
Restore — Restore previously saved mathematical expressions. The Enter
Expressions Filename dialog appears. Select a filename and click OK.
 
Clear — Clear all expressions from the Previous Band Math Expressions list.
 
Delete — Delete a single expression from the Previous Band Math
Expressions list.
 
Add to List — To add an individual expression to the Previous Band Math
Expressions list, enter it in the Enter an expression field and click Add to
List.
 
3. After entering a mathematical expression in the Enter an expression field, click OK.
The Variables to Bands Pairings dialog appears.
Assigning Values to Variables
Use the Variables to Bands Pairings dialog to assign bands from a list of input bands to
variable names you entered in the Enter an expression field of the Band Math dialog.
Using the example mathematical expression
(float(b1)+float(b2)+float(b3))/3.0,

1. In the Variables used in expression field, select the variable

B1 - [undefined].
 
2. Select the band in the Available Bands List. When the first band is selected, only
those bands with the same spatial dimensions are shown in the band list.
 
3. Continue to assign a value to B2, B3, and so forth in the same manner.
Mapping Variables to Multiband Images

You can assign a multiband image as one or all of the variables (using an image file as a
variable is considered File Math).
1. In the Variables to Bands Pairings dialog, select a variable in the Variables used in
expression field. 2
 1.
expression field.
 
2. Click Map Variable to Input File.
 
3. Select an input file the Input File dialog, and perform optional spatial subsetting, then
click OK. For subsetting details, see Selecting a Spatial Subset.
 
4. Continue to assign a value to B2, B3, and so forth in the same manner. If more than
one file is used, they must have the same number of bands.
 
5. Select output to File or Memory.
 
6. Click OK. A multiband output image is produced for File Math modified by the math
expression.

Band Math Requirements

The Band Math routine has four basic requirements:
1. The Band Math expression must be a single IDL statement — The syntax for
defining your processing algorithm, or Band Math expression, is that of IDL. However,
simple Band Math expressions do not require prior knowledge of IDL. If you plan to
perform complex processing, you should review IDL Tips for Use in Band Math.
 
A Band Math expression must be a single IDL statement in the form of a function:

result = expression

In the Band Math dialog, enter only the expression part of the function. Your
expression can include any valid IDL function, including those that you write yourself. If
you are using your own custom IDL functions, be sure to properly compile the function
before using it in Band Math (see Writing Band Math User Functions).
 
2. All input bands must have identical dimensions — The expression is applied on
a simple pixel-by-pixel basis. Therefore, the input bands (to which your expression is
applied) must all have the same spatial dimensions in samples and lines.
Furthermore, Band Math does not automatically coregister images that are
georeferenced. To automatically coregister images prior to using Band Math, use the
Basic Tools  Layer Stacking utility (see Layer Stacking for more information).
 
3. All variables in the expression must be named Bn (or bn) — The variables in the
expression that represent input bands must begin with the character "b" or "B"
followed by up to 5 numeric characters. For example, all of the following expressions
are valid when adding three bands:

b1 + b2 + b3
B1 + B11 + B111
B1 + b2 + B3
 
4. The result must be a band of the same dimension as the input bands — The
expression must produce a result with the same spatial dimensions in samples and
lines as the input bands.

IDL Tips for Use in Band Math

3
The power of the Band Math routine is provided by the power, speed, and flexibility of IDL.
You do not need to be an expert IDL programmer to be successful with Band Math. The
following tips will help you make the most of Band Math and avoid common problems.
Pay Attention to the Data Type
Doing arithmetic in IDL is a bit different than using a calculator. The data type of your input
bands and any constants you use in your expression are very important. Each data type—
especially the non-floating-point integer data types— has a limited dynamic range, meaning
that they can only represent a limited set of numbers. For example, a byte data type can
only represent values between 0 and 255. If you were to add two byte bands together (b1
+ b2) and the sum was greater than 255, the result would not be what you expect. When
a value becomes bigger than the data type can hold, it overflows and starts counting from
the beginning again. For example, adding the bytes 250 + 10 would produce a result of 4.
This situation is commonly encountered in Band Math because remote sensing images are
frequently stored as bytes or integers. To avoid data type overflow, you should promote the
data type of input bands using one of the IDL data type casting functions (see Table 3-2 for
a full list of these functions). For example, when adding two-byte image bands together (as
above), you will get the correct answer if you promote the data type to an integer using the
IDL function FIX().
fix(b1) + b2

Tip
To find out the data type of your images, highlight them in the Available Bands List and
their data type will be listed in the DIMS box at the bottom of the dialog.

You might ask, why not just carry out all computations in a floating-point data type since it
can represent any value? The answer is disk space. The greater the dynamic range a data
type can represent, the more disk space it consumes. For example, byte data types use
only 1 byte for every pixel, integers use 2 bytes for every pixel, while floating-point data
types use 4 bytes for every pixel. Thus a floating-point result will consume twice as much
disk space as an integer result. See Table 3-2 to learn more about the disk space usage
and dynamic ranges of the IDL data types.
IDL is Dynamically Typed
Using the IDL data type casting functions, like fix(), is not the only way that the data type of
your Band Math result can get promoted. This is because IDL is Dynamically Typed, which
means that the data type of an IDL statement is automatically promoted to the largest data
type it encounters in the expression. Because certain numbers (such as small integers) can
be represented by several different data types, IDL must apply some default rules about
how these numbers are interpreted. For example, numbers without decimal points are
always interpreted as integers, even if they are within the dynamic range of a byte data
type. For example, if you wanted to add the value 5 to a byte image and you used the Band
Math expression:
b1 + 5
the number 5 is interpreted as a 2-byte integer, so the result would be promoted to an
integer image (which uses twice as much disk space as a byte image). If you wanted to 4
integer image (which uses twice as much disk space as a byte image). If you wanted to
keep the result a byte image, you could either use the data type casting function byte():
b1 + byte(5)
or, use an IDL shortcut for casting an integer as a byte:
b1 + 5B
Adding a B (upper or lowercase) immediately following a number ensures that it is
interpreted as a byte data type. There are several other shortcuts like this that are quite
useful if you use constants in your Band Math expressions. See the following table for
details.
 
Table 3-2: Data Type Casting Shortcuts 

Data Type Casting Shortcut Dynamic Range Bytes

Function per Pixel

Byte byte() B 0 to 255 1

Integer fix()   –32768 to + 32767 2

Unsigned integer uint() U 0 to 65535 2

Long integer long() L approximately 4

+/– 2 billion

Unsigned long ulong() UL 0 to approximately 4

integer 4 billion

64-bit integer long64() LL approximately 8

+/– 9e18

64-bit Unsigned ulong64() ULL 0 to approximately 8

integer 2e19

Floating-point float() . (decimal +/– 1e38 4

point)

Double precision double() D +/– 1e308 8

Complex complex()   same as float 8

floating-point

5
 Complex double dcomplex()   same as double 16
precision

The Order of Operation is Important

Mathematical operators are not necessarily carried out in the order they appear in the
expression, but instead according to a hierarchy of precedence. Using parentheses can
change the order of operations, with the most deeply nested part of the expression being
carried out first. Table 3-3 lists the order of precedence for IDL operators. Operators that
have the same precedence will be carried out in the order they appear in the expression.
For example, consider the following expressions (with constants used in place of bands):

5 + 3 * 2 Evaluates to 11 because the multiplication operator takes

precedence

(5 + 3) * 2 Evaluates to 16 because the parentheses change the order of

operation

The order of precedence combined with the dynamic typing can also change the outcome of
your expression. Be sure to promote the data type in the proper place in the expression to
avoid data type overflow or integer division errors. For example, consider the following
case:

Float(5) + 10 / 3
All of the constants are integers but the float() function
promotes the result into a floating-point data type. However,
because the division operator has precedence over the
addition, it is applied first and the division is carried out as
integers, then added to 5 as a floating-point operation. The
result is 8.0 (instead of the expected 8.3).

5 + 10 / float(3) If the data type promotion is moved to one of the division

variables then the result is 8.3.

The following table describes the order of precedence for each operator:
Table 3-3: Operator Precedence 

Order of Operator Description

Precedence

First () Parentheses to group expressions

Second ^ Exponents

Third * Multiplication
6
 Third * Multiplication

# and ## Matrix multiplication

/ Division

MOD Modulus (remainder)

Fourth + Addition

– Subtraction and negation

< Minimum

> Maximum

NOT Boolean negation

Fifth EQ Equal

NE Not equal

LE Less than or equal

LT Less than

GE Greater than or equal

GT Greater than

Sixth AND Boolean AND

OR Boolean OR

XOR Boolean exclusive OR

Seventh ?: Conditional expression (rarely used in Band

Math)

Avoid Using IDL Functions That Require All of the Image Data at Once
Like all other ENVI routines, the Band Math processing is tiled. This means that if the
images being processed are larger than the tile size defined in your preferences (see ENVI
Preferences), which is set to 1 MB by default, then it will be broken into smaller pieces, 7
Preferences), which is set to 1 MB by default, then it will be broken into smaller pieces,
each piece processed separately, then reassembled. This can cause problems if you use
an IDL function that requires all of the image data at once, because the Band Math
expression is applied individually to each tile of data. For example, consider using the IDL
function MAX(), which determines the maximum value in an array:
b1 / max(b1)
If the Band Math processing is tiled, then each tile will be divided by the tile's maximum
value, instead of the maximum value of the whole band. If you find that your Band Math
result has broad horizontal stripes in it, tiling may be the cause of the problem (because the
tiles are horizontal sections of the image). IDL functions to avoid include FFT, MAX, MIN,
MEAN, MEDIAN, STDDEV, VARIANCE, and TOTAL. In most cases it is also difficult to use
the BYTSCL function, but if you know beforehand the data range of your input bands then
you can use BYTSCL as long as you include the MIN and MAX keywords.
Take Advantage of IDL's Powerful Array Operators
IDL's array operators are very easy to use and enormously powerful for Band Math. They
allow you to examine and treat every pixel in an image individually without having to do a
FOR loop (which is not allowed in Band Math). The array operators include the relational
operators (LT, LE, EQ, NE, GE, GT), the Boolean operators (AND, OR, NOT, XOR), and
the minimum and maximum operators (<, >). These operators are special because they
operate simultaneously on every pixel in an image, and thus return an image of the same
dimensions as that passed into them (a Band Math requirement). For example, to find all
pixels with a negative value and replace them with the value –999, you could use the
following Band Math expression:
(b1 lt 0) * (-999) + (b1 ge 0) * b1
The relational operators return a one for true and a zero for false, so the portion of the
expression that reads (b1 lt 0) will return an array of the same dimensions as b1 filled with
ones where b1 was negative and zeros everywhere else. Multiplying this by the
replacement value (-999) affects only those pixels that met the criterion of being negative.
The second relational operator (b1 ge 0) is the complement to the first, finding all of the
pixels that are positive or zero, which is multiplied by their original value and added to the
replacement value array. Constructing Band Math expressions with array operators like this
provides a great deal of flexibility. See Sample Band Math Expressions for more examples.
The following table describes selected IDL array handling functions. For a complete listing,
see the IDL Reference Guide.
Table 3-4: IDL Array Handling Functions 

Category Available Functions

Basic Arithmetic Addition (+), subtraction (–), multiplication (*), and

division (/)

Trigonometric Functions sin(x), cos(x), and tan(x)

Arcs — asin(x), acos(x), and atan(x)

8
 Trigonometric Functions

Hyperbolics — sinh(x), cosh(x), and tanh(x)

Relational and Logical LT, LE, EQ NE, GE, GT

Operators
AND, OR, NOT, XOR

maximum (>) and minimum (<)

Data Type Conversions See Table 3-2 in IDL is Dynamically Typed

Other Math Functions exponent (^) and natural exponent (exp(x))

Natural Logarithm — alog(x)

Log Base 10 — alog10(x)

Integer rounding — round(x), ceil(x), and floor(x)

Square Root — sqrt(x)

Absolute Value — abs(x)

Sample Band Math Expressions

Avoiding Integer Division

When performing division on bands that are not a floating-point data type, the results are
not rounded up or down, but simply truncated (the part of the number following the decimal
point is dropped). To avoid integer division, always promote the data type to a floating-point.
b1 / float(b2)
If you want to keep the results of the division as an integer, it is usually better to carry out
the division as a floating-point operation then convert the results back to your desired data
type. For example, if your input bands are both byte data type and you want to round up the
result and store it as an integer, use the following expression:
fix( ceil( b1/float(b2) ) )
Avoiding Integer Overflow

Integers have a limited dynamic range. If the Band Math operation is likely to produce a
number that is too large or small to be represented by the data type of your input bands,
then be sure to promote the data type accordingly. For example, if bands b1 and b2 for this
sample expression are byte data types, then the maximum possible result could be as
large as (255 * 255) = 65,025. Because bytes can only represent values up to 255, the
result should be promoted to an unsigned integer to ensure that the correct values are
returned, otherwise values larger than 255 will overflow and be reported incorrectly. 9
returned, otherwise values larger than 255 will overflow and be reported incorrectly.
uint(b1) * b2
To learn more about the dynamic range of IDL data types, see Table 3-2 in IDL is
Dynamically Typed.
Creating a Blended Image

Band Math is an easy way to experiment with blending multiple images together. For
example, if b1 and b2 are both byte data types, the above expression will produce a new
byte image that is weighted 80% by b2 and 20% by b1.
byte( round( (0.2 * b1) + (0.8 * b2) ) )
Using Array Operators to Selectively Modify an Image

Using IDL's array operators its easy to selectively modify an image or combine data from
multiple image sources. In the following example, two images are combined to remove
clouds from a scene. Pixels in the image b1 with values greater than 200 are assumed to
be clouds and are replaced by the corresponding pixels from image b2.
(b1 gt 200)*b2 + (b1 le 200)*b1
The next example is a slightly more complicated expression but its use of array operators is
quite similar to the previous example. This expression uses several criteria to create a
binary mask identifying pixels that are predominantly clouds. This algorithm can actually be
used to create cloud masks from calibrated daytime imagery from the Advanced Very High
Resolution Radiometer (AVHRR) sensor. In the expression, b4 (a thermal band) must be
negative or b2 (a reflectance band) must exceed 0.65 and the difference between bands
b3 and b4 (a mid IR and thermal band) must exceed 15 degrees. Because relational
operators return a one for true, the mask will have a value of one where there are clouds
and zeros elsewhere.
(b4 lt 0) or ( b2 gt 0.65 AND (b3 - b4) gt 15 )
Using the Maximum and Minimum Operators

The minimum and maximum operators are also array based operators, but unlike the
relational or Boolean operators they do not return true or false, but instead the actual MAX
or MIN value. In the following example, for every pixel in the image, the greater of zero, b2
or b3 is added to b1. This ensures that the value that is added to b1 is always positive.
b1 + (0 > b2 > b3)
In the next example, the use of both the minimum and maximum operators clips the data
values in b1 at zero and one — no value in b1 will exceed one or fall below zero.
0 > b1 < 1

Writing Band Math User Functions

You can write a custom function in IDL, save it to a.pro or .sav file in the save_add
directory, and call it from the Enter an expression field of the Band Math dialog. See Writing
Band Math User Functions for further details and examples.
  ENVI Online Help (July 17, 2006)

10