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 dialog appears. Band Math. The Band Math

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: (float(b1)+float(b2)+float(b3))/3.0 Three variables are used in this expression: B1, B2, and B3. Note that, in this
1

example, the IDL function float() is used to prevent byte overflow errors during calculation. 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. Click Map Variable to Input File.
2

3. Select an input file the Input File dialog, and perform optional Spatial Subsetting, then click OK. 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). 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-1 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-1 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
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-1: Data Type Casting Shortcuts

Data Type

Casting Function byte() fix() uint() long()

Shortcut

Dynamic Range

Bytes per Pixel 1 2 2 4

Byte Integer Unsigned integer Long integer

0 to 255 -32768 to + 32767

U L

0 to 65535 approximately +/- 2 billion 0 to approximately 4 billion approximately +/- 9e18 0 to approximately 2e19 +/- 1e38

Unsigned long integer 64-bit integer

ulong()

UL

long64()

LL

64-bit Unsigned integer Floating-point

ulong64()

ULL

float()

. (decimal point) D

Double precision Complex floating-point Complex double precision

double() complex()

+/- 1e308 same as float

8 8

dcomplex()

same as double

16

The Order of Operation is Important

5

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-2 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 Evaluates to 16 because the parentheses change the order of operation

(5 + 3) * 2

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). If the data type promotion is moved to one of the division variables then the result is 8.3.

5 + 10 / float(3)

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

Order of Precedence First Second Third

Operator

Description

() ^ * # and ## / MOD

Parentheses to group expressions Exponents Multiplication Matrix multiplication Division Modulus (remainder) Addition
6

Fourth

< > NOT Fifth EQ NE LE LT GE GT Sixth AND OR XOR Seventh ?:

Subtraction and negation Minimum Maximum Boolean negation Equal Not equal Less than or equal Less than Greater than or equal Greater than Boolean AND Boolean OR Boolean exclusive OR 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 Image Tile Size (Mb) preference, 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.
7

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-3: IDL Array Handling Functions

Category Basic Arithmetic

Available Functions Addition (+), subtraction (-), multiplication (*), and division (/) sin(x), cos(x), and tan(x) Arcs: asin(x), acos(x), and atan(x) Hyperbolics: sinh(x), cosh(x), and tanh(x)

Trigonometric Functions

Relational and Logical Operators

LT, LE, EQ NE, GE, GT AND, OR, NOT, XOR maximum (>) and minimum (<)

Data Type Conversions Other Math Functions

See Table 3-1 in IDL is Dynamically Typed Exponent (^) and natural exponent (exp(x)) Natural Logarithm: alog(x) Log Base 10: alog10(x)
8

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. uint(b1) * b2 To learn more about the dynamic range of IDL data types, see Table 3-1 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
9

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 Help (April 17, 2008)

10