Performing Map Calculations on GRASS Data:
l
a
i
r
o
t
u
T
m
a
r
g
o
r
P
c
l
a
c
p
a
m
.
r
Marji Larson o r i p a h S l e a h c i M Scott Tweddale s r e e n i g n E f o s p r o C y m r A . S . UConstruction Engineering Research Laboratory n o i s i v i D l a t n e m n o r i v n E
Spatial Analysis Systems Team 5 0 0 9 x o B . O . P Champaign, IL 61826-9005 1 9 9 1 r e b m e c e D
Table of Contents
2 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . s t n e t n o C f o e l b a T 1. Introduction ... 3 4 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . n o i t a t n e i r O . 2 3. Syntax ... 4 8 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . s e l p m a x E / n o i s s e S e l p m a S . 45. Conclusions and Recommendations ... 13 3 1 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . s e c n e r e f e R
N O I T C U D O R T N I . 1 1.1. Background
This document details the capabilities of r.mapcalc, a program that allows users to manipulate, analyze, d e d u l c n i s i t I . s r e y a l p a m r e t s a r n o s n o i t a l u c l a c l a c i t a m e h t a m g n i m r o f r e p y b a t a d p a m e t a e r c d n a
among Geographic Resources Analysis Support System (GRASS) software. GRASS is a public domain, e h t n i s r e h c r a e s e r y b d e p o l e v e d y l l a n i g i r o ) S I G ( m e t s y s n o i t a m r o f n i c i h p a r g o e g d n a , g n i s s e c o r p e g a m i
Environmental Division of the U.S. Army Corps of Engineers Construction Engineering Research , e z y l a n a , e t a l u p i n a m , t u p n i o t d e s u s i m e t s y s e h T . s i o n i l l I , n g i a p m a h C n i ) N E -L R E C A S U ( y r o t a r o b a L
and output geographic data by users in both military and non-military and public and private agencies . d l r o w e h t f o s t r a p r e h t o d n a , e p o r u E , a c i r e m A h t r o N n i d e s a b
Although most GRASS development has been conducted at USACERL, system integration, develop -y l e t a v i r p d n a -y l c i l b u p s u o r e m u n y b d e m r o f r e p s i t r o p p u s d n a , g n i n i a r t , n o i t u b i r t s i d , g n i t s e t , t n e m
operated sites throughout the world. GRASS version 4.0 implemented significant additions and t n e r r u c r e f s n a r t o t d e d e e n e r a s m s i n a h c e M . e d o c g n i m m a r g o r p d n a s e i r a r b i l m e t s y s o t s n o i t a c fi i d o m
technology and information about GRASS to user and development sites.
-n o c e h t h g u o r h t r e s u e h t s e d i u g d n a 0 . 4 n o i s r e v S S A R G o t e d a m s n o i t a c fi i d o m s t c e fl e r t n e m u c o d s i h T
struction of raster map analyses using r.mapcalc.
e v i t c e j b O . 2 . 1
The objective of this work is to transfer knowledge of GRASS version 4.0 raster map analysis functions , e t a l u p i n a m o t c l a c p a m . r g n i s u f o s s e c o r p e h t h g u o r h t r e s u e h t s e d i u g t n e m u c o d s i h T . d l e fi e h t o t
create, and analyze raster data layers in GRASS using mathematical expressions.
h c a o r p p A . 3 . 1
Current GRASS r.mapcalc functions are examined in this report.
e p o c S . 4 . 1
This document discusses the 4.0-release version of the GRASS r.mapcalc program, completed in the e r a w t f o s 0 . 4 -t s o p r o f e t a r u c c a n i d n a d e t a d e b l l i w t n e m u c o d s i h t f o s t n e m e l e e m o S . 1 9 9 1 f o r e m m u S releases.
1.5. Mode of Technology Transfer
The information in this report will aid the technical transfer of USACERL’s GRASS image processing g n i w o l l o f e h t h g u o r h t d l e fi e h t o t d e r r e f s n a r t g n i e b s i S S A R G . m e t s y s n o i t a m r o f n i c i h p a r g o e g d n a
mechanisms: training programs, hands-on experience, a user support center, newsletters, extensive , s k r o w t e n n o i t a c i n u m m o c , s l e v e l y c n e g a r e t n i d n a y m r A e h t t a s e r u t c u r t s l a n o i t u t i t s n i , n o i t a t n e m u c o d
and other forums.
User feedback on GRASS program capabilities, documentation, and other technology transfer mechan -d e e f h c u s e t a c i n u m m o c o t d e g a r u o c n e e r a s r e s U . m e t s y s e h t f o t n e m p o l e v e d e h t o t t n a t r o p m i s i s m s i
back to GRASS development staff at USACERL, via existing electronic communication networks and e n o h p ; 5 0 0 9 -6 2 8 1 6 L I , n g i a p m a h C , 5 0 0 9 x o B . O . P , L R E C A S U t a r e t n e C n o i t a m r o f n I S S A R G e h t a i v
N O I T A T N E I R O . 2
This paper describes the use and syntax of the GRASS software tool r.mapcalc. This tool uses o t r e s u a s w o l l a t I . S S A R G n i h t i w s r e y a l p a m g n i t s i x e n o s e s y l a n a m r o f r e p o t x a t n y s l a c i t a m e h t a m
create a new map layer which is the result of a mathematical expression which may contain raster map s i c l a c p a m . r . s n o i t c n u f l a c i t a m e h t a m n w o n k d n a , s t n a t s n o c t n i o p g n i t a o fl r o r e g e t n i , s e m a n r e y a l
designed to act as a calculator for maps. Mathematical calculations are performed for each grid cell of . r e s u e h t y b d e i l p p u s s n o i t c n u f l a c i t a m e h t a m e h t g n i y l p p a , r e y a l p a m r e t s a r a
It is assumed that the reader is familiar with the meanings of raster data format, map layers, the s t p e c n o c S S A R G c i s a b r e h t o d n a e s e h T . S S A R G n i s k s a m d n a , s n o i g e r , n o i t a c o l d n a t e s p a m t n e r r u c
are reviewed in the GRASS hard copy and on-line help facility (accessible through g.help), in the h g u o r h t e l b a l i a v a s t n e m u c o d S S A R G r e h t o n i d n a , ) 2 9 9 1 , . l a t e o r i p a h S ( l a u n a M s ’ r e m m a r g o r P S S A R G
the GRASS Information Center at USACERL.
Land managers are given the job of protecting, maintaining, and developing areas of land. To -r o f n i s i h t f o e m o S . n o i t a m r o f n i l a c i h p a r g o e g f o s e p y t s u o i r a v s d e e n r e g a n a m d n a l a , y t u d s i h t m r o f r e p
mation may be available in the GRASS database, represented by raster map layers. Other information e n o m o r f n o i t a m r o f n i g n i n i b m o c r o / d n a g n i z y l a n a y b d e v i r e d e b n a c t u b , y l t c e r i d e l b a l i a v a e b t o n y a m
or more existing raster map layers. Often, the manner in which information needs to be interpreted or
c l a c p a m . r l o o t S S A R G e h t , e s a c a h c u s n I . n o i t a u q e l a c i t a m e h t a m a y b d e t n e s e r p e r e b n a c d e n i b m o c
provides the user with a means for quickly obtaining the desired resultant geographical information. -l l e c a n o s n o i t a l u c l a c l a c i t a m e h t a m g n i m r o f r e p , s r e y a l p a m r e t s a r r o f r o t a l u c l a c a s i c l a c p a m . r
by-cell basis to obtain a new raster map layer. Calculations are done in the usual precedence of opera-. g n i r e d r o d e r i s e d e s i w r e h t o n a e t a n g i s e d o t d e s u s e s e h t n e r a p h t i w s n o i t 3. SYNTAX
The r.mapcalc command expects input in the form of:
n o i s s e r p x e = t l u s e r
Within the equation "result=expression", result is the name of the new raster map layer to contain the p a m r e t s a r g n i v l o v n i n o i s s e r p x e l a c i t a m e h t a m l a g e l y n a s i n o i s s e r p x e d n a , n o i t a l u c l a c e h t f o t l u s e r
layers, integer or floating point constants, and functions known to the r.mapcalc calculator. Known e h t r o f n o i t a t u p m o c f o r e d r o e h t h t i w g n o l a , s n o i t c e s g n i w o l l o f n i d e t s i l e r a s n o i t c n u f d n a s r o t a r e p o operations.
r.mapcalc will create the resulting raster map layer in the current mapset. It should be noted that
t c e r r o c e r u s n i o t d e s u e b d l u o h s n o i t u a C . s g n i t t e s k s a m d n a n o i g e r t n e r r u c e h t h t i w s k r o w c l a c p a m . r
results. If the user finds that the output from a r.mapcalc equation is not as expected, the current . d e k c e h c e b d l u o h s g n i t t e s k s a m d n a n o i g e r
The r.mapcalc command can be used in one of three ways: e n i l d n a m m o c e h t n o n o i t a u q e e h t g n i r e t n e
-- entering only the command name (no equation), e h t t a , e m i t a t a e n o , s n o i t a u q e g n i r e t n e n e h t d n a
new (MAPCALC) prompt
- passing one or more equations to the map calculator e l fi a m o r f r e h t i e ( t u p n i d r a d n a t s d e t c e r i d e r a i v or across a pipe)
Because the UNIX shell interprets some characters to have special meanings (see the Special Charac-n o i t n a n a l p x e n a , r e v e w o H . s d o h t e m e s e h t f o d n o c e s e h t e s u o t d e s i v d a s i r e s u e h t , ) w o l e b n o i t c e s s r e t
of each input method follows.
If the equation (result=expression) is given on the command line, only one equation can be pro-S S A R G e h t o t d e n r u t e r s i r e s u e h t d n a , d e t a e r c s i r e y a l p a m w e n e h t , d e t a u l a v e s i n o i t a u q e s i h T . d e d i v
. t p m o r p 0 . 4
If the command r.mapcalc is entered alone, then a new (MAPCALC) prompt appears, and the p a m w e n e h t , d e t a u l a v e s i t i , n o i t a u q e h c a e f o y r t n e e h t r e t f A . n o i t a u q e r e t f a n o i t a u q e r e t n e n a c r e s u
layer is created, and the user is returned to the MAPCALC prompt. After all desired equations have y e k N R U T E R e h t g n i t t i h y l p m i s y b t p m o r p 0 . 4 S S A R G e h t o t d e n r u t e r s i r e s u e h t , d e t a u l a v e n e e b
(without entering anything on the line) to denote that no more equations are to be given.
. d e d d a n e e b s a h e r u t a e f n o i t a u n i t n o c e n i l a , n o i s s e r p x e e h t n i s a l u m r o f y h t g n e l f o t n e v e e h t n I
By adding a \ to the end of the input line, r.mapcalc assumes that the formula continues onto the next e t o n e s a e l P . a l u m r o f e h t f o h t g n e l e h t o t r o s e n i l t u p m i f o r e b m u n e h t o t t i m i l o n s i e r e h T . e n i l t u p n i
that the line continuation feature only works when entering formulas from standard input and does not y h t g n e l h t i w g n i k r o w s i r e s u e h t f i , e r o f e r e h T . e n i l d n a m m o c e h t n o t u p n i s r e t n e r e s u e h t f i k r o w
expressions, they should enter the standard input mode by typing r.mapcalc alone on the command line . t u p n i g n i r e t n e e r o f e b n r u t e r t i h d n a
Input can also be provided through redirected standard input (from a file or across a pipe). If one e h t f o e n o n i c l a c p a m . r g n i s u d e t a u l a v e e b n a c y e h t , e l fi a o t n i d e r e t n e n e e b e v a h s n o i t a u q e e r o m r o following ways: r.mapcalc<inputfile r o
cat inputfile | r.mapcalc
The cat command simply types out the contents of a file. The pipe character | tells UNIX to "pipe" the e l fi e h t f o s t n e t n o c e h t , e l p m a x e t s a l s i h t n i , s u h T . d n a m m o c r e h t o n a o t n i d n a m m o c e n o f o s t l u s e r
inputfile are piped to the r.mapcalc command as input. It is not the intention of this document to cover e p i p e h t g n i s u s e l p m a x e r e h t r u f o N . l i a t e d n i X I N U f o s e i t i l i b a p a c g n i p i p e h t r o d n a m m o c t a c e h t r e h t i e
capability will be given.
When equations are sent to the r.mapcalc command via redirected standard input, all entered e h t n e h w t p m o r p 0 . 4 S S A R G e h t o t d e n r u t e r s i r e s u e h t d n a , r e h t o n a r e t f a e n o , d e t a u l a v e e r a s n o i t a u q e
E C N E D E C E R P F O R E D R O D N A S R O T A R E P O . 1 . 3
Operator Meaning Type Precedence
1 c i t e m h t i r A ) n o i s i v i d n o p u r e d n i a m e r ( s u l u d o m % / division Arithmetic 1 1 c i t e m h t i r A n o i t a c i l p i t l u m * + addition Arithmetic 2 2 c i t e m h t i r A n o i t c a r t b u s -== equal Logical 3 3 l a c i g o L l a u q e t o n = !
> greater than Logical 3
3 l a c i g o L l a u q e r o n a h t r e t a e r g = >
< less than Logical 3
3 l a c i g o L l a u q e r o n a h t s s e l = <
&& and Logical 4
4 l a c i g o L r o ||
Division by 0 and modulus by 0 are acceptable and give a 0 result.
d e i l p p a e c n e d e c e r p d e r e b m u n r e w o l f o e s o h t h t i w , t h g i r o t t f e l m o r f d e i l p p a e r a s r o t a r e p o e h T
before those with higher numbered precedence. Parentheses are allowed, and can be used to override . h t p e d y n a o t d e w o l l a e r a s e s e h t n e r a p d e t s e N . e c n e d e c e r p d e t a t s 3.2. FUNCTIONS
The following functions are currently supported:
x f o e u l a v e t u l o s b a n r u t e r ) x ( s b a
eval([x,y,...,]z) evaluate values of listed expr, pass results to z t n i o p g n i t a o fl o t x t r e v n o c ) x ( t a o fl if decision options: e s i w r e h t o 0 , o r e z t o n x f i 1 ) x ( f i
if(x,a) a if x not zero, 0 otherwise e s i w r e h t o b , o r e z t o n x f i a ) b , a , x ( f i if(x,a,b,c) a if x >0, b if x is zero, c if x<0 ] s e t a c n u r t [ r e g e t n i o t x t r e v n o c ) x ( t n i
log(x) natural log of x b e s a b x f o g o l ) b , x ( g o l
max(x,y[,z...]) largest value of those listed d e t s i l e s o h t f o e u l a v n a i d e m ) ] . . . z , [ y , x ( n a i d e m
min(x,y[,z...]) smallest value of those listed r e g e t n i t s e r a e n o t x d n u o r ) x ( d n u o r sqrt(x) square root of x ) s e e r g e d n i s i x ( x f o t n e g n a t ) x ( n a t
The variables x, y, z, a, b, and c above can be replaced by integer or floating point constants, a , s n o i t c n u f r e h t o d n a , s r e y a l p a m r e t s a r , s t n a t s n o c g n i v l o v n i n o i s s e r p x e r e h t o n a r o , e m a n r e y a l p a m r e t s a r
provided the numbers represented are within the allowable domain of the given function. (For instance, ) . s e e r g e d g n i t n e s e r p e r r e b m u n a o t s e t a u l a v e ’ n o i s s e r p x e ’ f i y l n o e s n e s s e k a m ’ ) n o i s s e r p x e ( n a t ’
Note that although functions are available which produce floating point results, the resulting raster g n i t a o fl a s i n o i t a l u c l a c a o t " r e w s n a " l a n fi e h t f i , s u h T . s e u l a v ) y r o g e t a c ( r e g e t n i y l n o d l o h n a c p a m
e h t n i e u l a v a s a d e r o t s g n i e b e r o f e b r e g e t n i t s e r a e n e h t o t d e d n u o r e b l l i w r e b m u n e h t , r e b m u n t n i o p
resulting map layer.
Calculations will be done according to the type of values being used in the expression. For s t n a w r e s u e h t f I . 2 e b l l i w r e w s n a e h t d n a , c i t e m h t i r a r e g e t n i g n i s u d e t a l u c l a c e b l l i w ) 3 / 8 ( , e c n a t s n i
the answer to be a floating point number which is rounded, care should be taken to create floating point , e r e h ( s e u l a v t n i o p g n i t a o fl s a d e t a u l a v e e b d l u o w ) 3 / ) 8 ( t a o fl ( d n a ) 3 / 0 . 8 ( , e l p m a x e r o f ; c i t e m h t i r a
2.66) that are finally rounded to 3 after all calculations are completed, when assigned as map category . r e y a l p a m t n a t l u s e r e h t n i s e u l a v
Anything given in the mathematical expression which is not a constant, an operator, or a known a n e v i g n e e b s a h r e y a l p a m r e t s a r S S A R G a f I . e m a n r e y a l p a m r e t s a r a s a n e k a t e b l l i w e m a n n o i t c n u f
name which could be interpreted as a constant or an arithmetic expression, the raster map layer name e s o p p u s , e c n a t s n i r o F . d n a m m o c c l a c p a m . r e h t h t i w e s u t c e r r o c r o f s e t o u q e l b u o d n i d e s o l c n e e b t s u m
a map layer has been created which is a reclass of a soils map layer, and it has been named soils-n o i s s e r p x e e h T . s s a l c e r newmap=soils-reclass * 2
would attempt to create a raster map layer named newmap which is the raster map layer soils minus the n o i s s e r p x e e h t e l i h w , 2 s e m i t s s a l c e r r e y a l p a m r e t s a r newmap="soils-reclass" * 2
would attempt to create a raster map layer named newmap, which is the raster map layer soils-reclass . 2 s e m i t
Using quotes around the resulting map name is an error.
S H T A P H C R A E S T E S P A M . 3 . 3
The r.mapcalc command will look for the map layer names given in the mathematical expression r e h t o n a n i d n u o f r e y a l p a m r e t s a r a e s u o t e l b i s s o p s i t I . h t a p h c r a e s t e s p a m t n e r r u c e h t o t g n i d r o c c a
mapset by explicitly specifying the mapset (mapname@mapset). For instance, in the following expres-: n o i s newmap = x@PERMANENT / y
the raster map layer x will be looked for specifically in mapset PERMANENT, while the raster map . h t a p h c r a e s t e s p a m S S A R G t n e r r u c s ’ r e s u e h t n i d e d u l c n i s t e s p a m e h t n i r o f d e h c r a e s e b l l i w y r e y a l
The "@mapset" form is not allowed in the name for the resulting map layer, which is automati-. t e s p a m t n e r r u c e h t n i d e t a e r c y l l a c 3.4. SPECIAL CHARACTERS
For evaluating only one equation, it is simplest to enter the equation on the command line. How-t h g i l o t t h g u o r b e b d l u o h s t a h t d n a m m o c c l a c p a m . r e h t f o e g a s u s i h t t u o b a s g n i h t o w t e r a e r e h t , r e v e here.
Since the equation is being given on the command line, care must be taken when using characters -n i s n i n o i t r o p n o i s s e r p x e e h t e s o l c n e o t e l b a s i v d a s i t I . l l e h s X I N U e h t o t g n i n a e m l a i c e p s e v a h h c i h w
gle quotes to avoid unexpected results. These special characters include, among others:
< ] [ | & > ) ( *
For instance, since the * character has special meaning to the UNIX shell, the expression in:
2 * n o i t a v e l e = p a m w e n c l a c p a m . r
would be altered before being sent to the map calculator, and would result in error. Instead, using sin-: n o i t r o p n o i s s e r p x e e h t d n u o r a s e t o u q e l g
’ 2 * n o i t a v e l e ’ = t l u s e r c l a c p a m . r
would let the UNIX shell know that any special characters should not be altered, and the expression -s e r p x e e h t d n u o r a s e t o u q e l g n i s f o e s u e h t t u o h t i W ( . d n a m m o c c l a c p a m . r e h t o t s i s a t n e s e b d l u o w
sion portion, parentheses may also be misinterpreted, and, although the expression may be correct, the ) . n e v i g e b d l u o w " s ’ ) ( d e c a l p y l d a B " e g a s s e m
The second thing to note about this type of usage of the r.mapcalc command is that if the result t a h t d e m u s s a s i t i , r e y a l p a m r e t s a r g n i t s i x e y l t n e r r u c a f o e m a n e h t s i e n i l d n a m m o c e h t n o n e v i g p a m
the user wants to overwrite it, and the raster map layer will be overwritten without warning.
d n a m m o c c l a c p a m . r e h t f o e g a s u t n e r e ff i d a , n o i t a u q e e n o n a h t e r o m t u p n i o t s e h s i w r e s u e h t f I
would be logical. For this case, only the command name is given. A new (MAPCALC) prompt is then t o n e r a d n a , s i s a n e k a t e r a n e v i g s r e t c a r a h c l l A . r e h t o n a r e t f a e n o d e r e t n e e r a s n o i t a u q e d n a , d e d i v o r p
modified by the UNIX shell. If the result raster map layer given at this MAPCALC prompt already . t i g n i t i r w r e v o t u o b a n o i s i c e d a r o f d e k s a d n a , d e n r a w s i r e s u e h t , s t s i x e 3.5. NEIGHBORHOOD MODIFIERS
Maps and images are database files stored in raster format, i.e., two-dimensional matrices of -a l e r a s e fi i c e p s t a h t r e fi i d o m d o o h r o b h g i e n a y b d e w o l l o f e b y a m s p a m , c l a c p a m . r n I . s e u l a v r e g e t n i
tive offset from the current cell being evaluated. The format is map[r,c], where r is the row offset and e h t o t s n m u l o c o w t d n a w o l e b w o r e n o l l e c e h t o t s r e f e r ] 2 , 1 [ p a m , e l p m a x e r o F . t e s ff o n m u l o c e h t s i c
right of the current cell, map[-2,-1] refers to the cell two rows above and one column to the left of the -r e p x a t n y s s i h T . l l e c t n e r r u c e h t f o t h g i r e h t o t n m u l o c e n o l l e c e h t o t s r e f e r ] 1 , 0 [ p a m d n a , l l e c t n e r r u c
mits the development of neighborhood-type filters within a single map or across multiple maps.
S E U L A V Y R O G E T A C . s v S L E B A L Y R O G E T A C . 6 . 3
Sometimes it is desirable to use a value associated with a category’s contents instead of the e h t n i s l e b a l e h t n e h t , r o t a r e p o @ e h t y b d e d e c e r p s i e m a n r e y a l p a m r e t s a r a f I . f l e s t i e u l a v y r o g e t a c
category file for the raster map layer are used in the expression instead of the category value. For -a v e l e l a u t c a e h t d a e r d l u o w t i , n o i t a u q e c l a c p a m . r n a n i " d e t d . n o i t a v e l e @ " d e fi i c e p s u o y f i , e l p m a x e
tion values for each category, rather than the category numbers themselves, which are simply scaled . 5 5 2 -1 n e e w t e b
This use of the "@" symbol is different from that earlier described in the section Mapset Search y b d e w o l l o f s i d n a , e m a n r e y a l p a m S S A R G a y b d e d e c e r p s i l o b m y s " @ " e h t , n o i t c e s t a h t n I . s h t a P
the name of a GRASS mapset. It is used to specify the use of a particular map layer (i.e., the named d e r o t s e m a n e m a s e h t f o r e y a l p a m r e h t o y n a n a h t r e h t a r , ) t e s p a m d e m a n e h t r e d n u d e r o t s r e y a l p a m
under any other mapset listed in the user’s mapset search path.
S E L P M A X E / N O I S S E S E L P M A S . 4
This sample session can be replicated by running the GRASS within the location spearfish. -r o f g n i w o l l o f e h t h t i w t n e m u c o d s i h t n i d e y a l p s i d e r a r e t n e o t d e t s e u q e r e r a u o y t a h t s d n a m m o C : t a m
PROMPT:> your_command
Results that you should see after entering a command are displayed in this document with the following : t a m r o f _______________________ e r e h d e y a l p s i d t l u s e r e m o S _______________________
you have typed in the r.mapcalc command alone (without arguments) and are therefore at a MAP-. t p m o r p C L A C 4.1. COMMAND-LINE EXAMPLES
Suppose that you have a raster map layer describing elevation in which the category values are e h t t n a w u o y t u b , n o i t a v e l e e h t s t c i p e d o s l a h c i h w r e y a l p a m a e v a h o t d e e n u o y f I . s n o i t a v e l e e u r t e h t
numbering to start at 1 (instead of at the minimum elevation value for that geographic region), you d l u o h s u o y , t s r i F . p a m w e n e h t e t a e r c o t n o i t c a r t b u s e l p m i s a h t i w d n a m m o c c l a c p a m . r e h t e s u d l u o c
find out the range of elevation values contained in the original map layer. This can be done using the . e b i r c s e d . r d n a m m o c S S A R G
GRASS 4.0> r.describe elevation.dem
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
READING [elevation.dem in PERMANENT] ... 100% 0 4 8 1 -6 6 0 1 0 _______________________________________________ s A . r e y a l p a m a g n i d a e r t u o b a t n e m e t a t s e h t r e t f a n e v i g s i % 0 0 1 , e v o b a n o i t c e s t l u s e r e h t n i t a h t e t o N (
the command is actually executing, this will start as 0% and be updated as the execution progresses.) n i s r e b m u n e h t t r a t s o t 5 6 0 1 t u o t c a r t b u s d l u o w u o y , 6 6 0 1 s i e u l a v n o i t a v e l e m u m i n i m e h t e c n i S
the new map layer at 1.
GRASS 4.0>r.mapcalc new.elev = elevation.dem - 1065
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __
PARSING EXPRESSION elevation.dem - 1065 5 6 0 1 -m e d . n o i t a v e l e = v e l e . w e n G N I T U C E X E complete: 100%
CREATING SUPPORT FILES FOR new.elev 5 7 7 e u l a v m u m i x a m , 5 6 0 1 -e u l a v m u m i n i m ________________________________________
The map calculator has to first parse the expression given, and see if it makes sense mathemati -u c l a c e h t o t n w o n k t o n s i d e s u n o i t c n u f a ( g n i h t e m o s d n a t s r e d n u t o n s e o d r o t a l u c l a c p a m e h t f I . y l l a c
lator, a parenthesis is unmatched, or the expression is mistyped), a message will be given that the calcu -u c l a c s i n o i t a u q e e h T . n i g e b s n o i t a l u c l a c e h t , d o o t s r e d n u s i n o i s s e r p x e e h t f I . d e s u f n o c n e e b s a h r o t a l
lated for each grid cell location in the current region, substituting the category value from that grid p a m w e n e h t , e t e l p m o c e r a s n o i t a l u c l a c l l a e c n O . n o i s s e r p x e e h t n i e m a n r e y a l p a m h c a e r o f n o i t a c o l
layer is created, and the minimum and maximum values in the new map layer are reported.
-a c o l l l e c d i r g e h T . t l u s e r d e r i s e d e h t e b t o n y a m d n a m m o c e v o b a e h t m o r f t u p t u o e h t t a h t e t o N
tions which contained a "0" (no data) value in the original map layer now contain a value of -1065. To t a h t s e u l a v l l e c e h t g n i g n a h c t u o h t i w ) 1 t a t r a t s o t s e u l a v e h t g n i r e b m u n e r ( t l u s e r d e r i s e d e h t n i a t b o
were originally 0, we will use a slightly more complex equation, given below. Single quotes should be l a i c e p s a n i s e s e h t n e r a p e h t t e r p r e t n i o t s e i r t l l e h s X I N U e h t , e s i w r e h t O . n o i s s e r p x e e h t d n u o r a d e s u
manner, and the command will not complete.
’ ) 5 6 0 1 -m e d . n o i t a v e l e , m e d . n o i t a v e l e ( f i ’ = v e l e . w e n c l a c p a m . r > 0 . 4 S S A R G ______________________________________________________ ) 5 6 0 1 -m e d . n o i t a v e l e , m e d . n o i t a v e l e ( f i N O I S S E R P X E G N I S R A P
EXECUTING new.elev = if(elevation.dem, elevation.dem-1065) % 0 0 1 : e t e l p m o c
CREATING SUPPORT FILES FOR new.elev 5 7 7 e u l a v m u m i x a m , 0 e u l a v m u m i n i m ______________________________________________________ e u l a v y r o g e t a c e h t f i : s a d e t e r p r e t n i s i r o t a l u c l a c p a m e h t n i h t i w d n a m m o c " f i " e h t f o m r o f s i h T
of "elevation" is non-zero, then set the result equal to "elevation-1065". Otherwise, set the result equal s i n o i t p m u s s a e h T . v e l e . w e n e l fi l l e c e h t e t i r w r e v o o t d e r i s e d u o y f i d e k s a t o n e r e w u o y t a h t e t o N . 0 o t
S E L P M A X E T U P N I D R A D N A T S . 2 . 4
Next we will perform a few more calculations, and to simplify the process, we will type the a t a e n o , s n o i t a u q e r u o g n i r e t n e n e h t , n o i t a u q e g n i y n a p m o c c a y n a t u o h t i w e n o l a d n a m m o c c l a c p a m . r
time, at the MAPCALC prompt. (This will simplify the need for quotes around the expression portion t o n l l i w e r e h t , o s l A . t s i x e y d a e r l a t a h t s e l fi r e t s a r g n i t i r w r e v o t u o b a s u n r a w l l i w d n a , n o i t a u q e e h t f o
be a need to re-enter the command name each time, only the new equation.)
c l a c p a m . r > 0 . 4 S S A R G ___________ > C L A C P A M ___________
A new (MAPCALC) prompt is given, and now we can enter equations one after another.
l l i w e W . d e d o o fl y l e r e v e s n e e b s a h h c i h w a e r a n a g n i t c i p e d r e y a l p a m a e k i l d l u o w u o y e s o p p u S
alter the elevation file from the spearfish data set so that only elevations below 1200 feet will be e h t e t a r t s u l l i l l i w t u b , g n i d o o fl r o f h g i h t i b a s i s i h T ( . t e e f 0 0 2 1 o t g n i d o o fl a g n i m u s s a , d e t n e s e r p e r
technique to be used.) Enter the following equation:
) 0 0 2 1 = < m e d . n o i t a v e l e ( f i = v e l e . w e n > C L A C P A M ___________________________________________ ) 0 0 2 1 = < m e d . n o i t a v e l e ( f i N O I S S E R P X E G N I S R A P
new.elev - already exists. ok to overwrite? [n] y ) 0 0 2 1 = < m e d . n o i t a v e l e ( f i = v e l e . w e n G N I T U C E X E complete: 100%
CREATING SUPPORT FILES FOR new.elev 1 e u l a v m u m i x a m , 0 e u l a v m u m i n i m ___________________________________________
The color assigned to category 1 should be made a blue color to represent the water level at this . n o i t a v e l e
Note that since the equation is being entered at the MAPCALC prompt, a warning is given that t o n o d u o y f I . t o n r o e t i r w r e v o o t d e d i v o r p s i e c i o h c e h t d n a , s t s i x e y d a e r l a v e l e . w e n r e y a l p a m e h t
wish to overwrite the map layer new.elev, enter n in response to the question (or simply hit RETURN a h t i w n o i t a u q e e h t r e t n e -e r t s u m u o y n e h T . ) s t e k c a r b n i n w o h s ’ n ’ f o e s n o p s e r t l u a f e d e h t t p e c c a o t
new resulting map layer name.
Now, suppose we want to determine the depth of flooding.
) m e d . n o i t a v e l e -0 0 2 1 , v e l e . w e n ( f i = h t p e d > C L A C P A M _________________________________________________ ) m e d . n o i t a v e l e -0 0 2 1 , v e l e . w e n ( f i N O I S S E R P X E G N I S R A P
EXECUTING depth = if(new.elev,1200-elevation.dem) % 0 0 1 : e t e l p m o c
CREATING SUPPORT FILES FOR depth_________________________________________________
4.3. CREATING NEW DATA LAYERS
In the spearfish data set, raster map layers exist representing aspect and streams. It would be e n i l o t m e e s s m a e r t s e h t f i e e s o t r e y a l p a m t c e p s a e h t n o d i a l r e v o e l fi s m a e r t s e h t y a l p s i d o t g n i t s e r e t n i
up with changes in aspect direction. This could be done by displaying the aspect map layer, and then a e t a e r c y l l a u t c a o t d e t n a w u o y f I . s m a e r t s r e y a l p a m e h t h t i w o -t s a r . d d n a m m o c S S A R G e h t g n i s u
new map layer representing the two map layers together, you could use r.mapcalc.
-t n e s e r p e r 5 2 y r o g e t a c s u l p , t c e p s a f o s n o i t c e r i d 4 2 -s e i r o g e t a c 5 2 s n i a t n o c r e y a l p a m t c e p s a e h T
ing "no aspect". (The category range of the aspect map layer can be obtained using the GRASS com-r e y a l p a m t c e p s a e h t m o r f s e i r o g e t a c 5 2 e h t g n i n i a t e r r e y a l p a m w e n a e t a e r c l l i w e W ) . e b i r c s e d . r d n a m
and assigning the streams data to category number 26. Enter the following equation:
) t c e p s a , 6 2 , s m a e r t s ( f i = r t s . t c e p s a > C L A C P A M
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
PARSING EXPRESSION if(streams,26,aspect) ) t c e p s a , 6 2 , s m a e r t s ( f i = r t s . t c e p s a G N I T U C E X E complete: 100%
CREATING SUPPORT FILES FOR aspect.str 6 2 e u l a v m u m i x a m , 0 e u l a v m u m i n i m MAPCALC> _______________________________________
When the streams file contains a non-zero value, the new map layer is assigned a value of 26. r e y a l p a m w e n e h T . r e y a l p a m t c e p s a e h t f o e u l a v y r o g e t a c e h t s e v i e c e r r e y a l p a m w e n e h t , e s i w r e h t O
aspect.str will not have any assigned color table. One should be assigned using the GRASS command y r o g e t a c y b d e t n e s e r p e r ( s m a e r t s e h t r o F . ) " t c e p s A " d e l e b a l e p y t e l b a t r o l o c e h t y l b a b o r p ( t r o p p u s . r
26) to stand out against the rest of the map, the color for category 26 should then be altered. This can . m a r g o r p s r o l o c . d e h t g n i s u e n o d e b
Hit the RETURN key now to return to the GRASS 4.0 prompt.
s u o i r a v n o s i s y l a n a n a m r o f r e p o t d e s u e b n a c c l a c p a m . r w o h e t a r t s u l l i l l i w e l p m a x e t x e n e h T
raster map layers. Given the following information about the categories for map layers transport.misc, e r e h w n o i t a c o l h s fi r a e p s e h t n i h t i w s a e r a l l a t n e s e r p e r o t e n o d e b n a c s i s y l a n a n a , s d a o r l i a r d n a , s d a o r
transport lines are available.
________________________________________________________________________ s d a o r l i a r s d a o r c s i m . t r o p s n a r t : p a m ________________________________________________________________________ a t a d o N 0 a t a d o N 0 a t a d o N 0 c
a 1 Power transmission 1 Interstate highway 1 railroad line 2 e c a f r u s d r a h , y a w h g i h y r a m i r P 2 p i r t s g n i d n a L 2 t
e 3 Secondary highway, hard surface
e c a f r u s d e v o r p m i , d a o r y t u d t h g i L 4 g o 5 Unimproved road r y ________________________________________________________________________
We will say that transport lines are available when transport.misc has category value 2, when p a m r e t s a r t l u s e r e h T . 1 e u l a v y r o g e t a c s a h s d a o r l i a r n e h w r o , 3 r o , 2 , 1 s e u l a v y r o g e t a c s a h s d a o r
layer (trans.avail) will have only the one category, denoting that one of the above was true and there-t i , d e t a c i l p m o c e l t t i l a s i s i h t r o f n o i t a u q e e h t e c n i S . e l b a l i a v a s i t r o s e m o s f o e n i l n o i t a t r o p s n a r t a e r o f
might be easiest to create a text file which can be used to provide the input to r.mapcalc. This makes t u o d e t n i r p s i d n a t u p n i . p a m d e l l a c s i t u p n i r o f d e t a e r c e l fi e h T . s r o r r e g n i p y t y n a t c e r r o c o t r e i s a e t i
below using the UNIX command cat.
t u p n i . p a m t a c > 0 . 4 S S A R G ___________________________________________________________________ 1 = = s d a o r l i a r || 3 = = s d a o r || 2 = = s d a o r || 1 = = s d a o r || 2 = = c s i m . t r o p s n a r t = l i a v a . s n a r t ___________________________________________________________________ T U P N I G N I T C E R I D E R . 4 . 4
We will evaluate this equation using the redirected input format of the r.mapcalc command as . w o l e b n w o h s
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ __ PARSING EXPRESSION
transport.misc==2 || roads==1 || roads==2 || roads==3 || railroads==1 G N I T U C E X E
trans.avail = transport.misc==2 || roads==1 || roads==2 || roads==3 || railroads==1 % 0 0 1 : e t e l p m o c
CREATING SUPPORT FILES FOR trans.avail 1 e u l a v m u m i x a m , 0 e u l a v m u m i n i m EOF _____________________________________________________________________ 1 r o 0 o t s e t a u l a v e h c i h w n o i s s e r p x e l a c i g o l a s i ) " 2 = = c s i m . t r o p s n a r t " e k i l ( y t i l a u q e r o f t s e t h c a E
(false or true). The tests are joined with logical or’s, ||, so that the result of the expression will evaluate -o r e z a e b l l i w c s i m . t r o p s n a r t r e y a l p a m g n i t l u s e r e h T . e u r t s i y t i l a u q e r o f s t s e t e h t f o e n o y n a f i 1 o t
one map, where category 1 represents the fact that one of the above conditions is true.
m o r f d e v i r e d , n o i t a m r o f n i f o s e p y t w e n h t i w s r e y a l p a m e t a e r c o t d e s u e b n a c l o o t c l a c p a m . r e h T
information contained in other map layers. Whenever an equation exists that calculates a value from s a e l b a l i a v a e r a n o i t a u q e e h t n i s e l b a i r a v l a n i g i r o e h t d e d i v o r p l u f e s u e b l l i w c l a c p a m . r , s e u l a v r e h t o
existing raster map layers. For instance, given a drainage accumulation map layer (where category -a c o l d i r g n e v i g e h t o t n i a r d d l u o w h c i h w d e h s r e t a w n e v i g a n i h t i w s l l e c f o r e b m u n e h t t n e s e r p e r s e u l a v
tion) and a map layer depicting slope values, a map layer can be derived which approximates the distri-s i x e d n i e h T . e l t n a m l i o s e h t n i n o i t a r u t a s f o e e r g e d e h t g n i z i r e t c a r a h c x e d n i c i h p a r g o p o t a f o n o i t u b
mathematically expressed as the
ln (drainage_accumulation/tan(slope_magnitude) )
n a t d n a g o l e h t g n i s u n e t t i r w e b n a c a l u m r o f l a c i t a m e h t a m s i h t g n i s s e r p x e t n e m e t a t s c l a c p a m . r n A
functions. High saturation areas are flat and have large contributing areas. A drainage accumulation S S A R G e h t g n i s u a t a d n o i t a v e l e m o r f d e v i r e d e b n a c n o i t a c o l h s fi r a e p s e h t n i h t i w d e h s r e t a w a r o f e l fi
program r.watershed. A slope map layer can be derived from elevation data using the GRASS pro-d l u o h s u o Y . e s a b a t a d h s fi r a e p s e h t n i e l b a l i a v a e b y d a e r l a d l u o h s p a m e p o l s A . t c e p s a . e p o l s . r m a r g
check to be sure this is not a reclassed version of the slope map, but instead represents degrees of slope. d n a " , a t a d o n " t n e s e r p e r o t 0 y r o g e t a c s e v r e s e r m a r g o r p t c e p s a . e p o l s . r e h t m o r f d e v i r e d p a m e p o l s e h T
so zero degrees is represented as category 1, one degree by category 2, and so on. In developing our e h t n i " e p o l s " r o f " 1 -e p o l s " e t u t i t s b u s e r o f e r e h t d l u o h s e w , c l a c p a m . r r o f n o i s s e r p x e l a c i t a m e h t a m
equation given above. We do not want to subtract 1 when the slope map layer contains a zero value p a m e h T " . ) 1 -e p o l s , e p o l s ( f i " n o i s s e r p x e e h t e s u d l u o h s e w o s , ) 5 6 0 1 -n o i t a v e l e h t i w e l p m a x e e h t l l a c e r (
calculator for r.mapcalc represents the natural log by "log" (not "ln"), so the expression would look e p o l s a d n a n i a r d d e m a n r e y a l p a m n o i t a l u m u c c a e g a n i a r d a r o f ) ) ) 1 -e p o l s , e p o l s ( f i ( n a t / n i a r d ( g o l : e k i l
map layer named slope. The last adjustment to make is to take into consideration what happens when e u l a v y r o g e t a c ( " a t a d o n " s n i a t n o c r e y a l p a m e p o l s e h t r o r e y a l p a m n o i t a l u m u c c a e g a n i a r d e h t r e h t i e
0). This would result in a calculated value that is negative and large. We will take care of this case of s t l u s e r g n i v o m e r ( n o i t a u q e e h t f o s t l u s e r e v i t a g e n l l a g n i t a n i m i l e y b " a t a d o n " g n i s u g n i t a u l a v e
representing a negative soil saturation index). This can be done using the max function as shown p a m w e n e h t o t d e n g i s s a e b l l i w t l u s e r s t i , o r e z n a h t r e t a e r g s i n o i s s e r p x e e h t f o t l u s e r e h t f I . w o l e b
layer. However, if the result is less than zero, then zero will be the result of the max function. The : e b d l u o w p a m t c u d o r p s i h t e c u d o r p o t d e s u n o i t a u q e c l a c p a m . r
GRASS 4.0>r.mapcalc index.sat=’max(0, log( drain / tan(max(0,slope-1)) ) )’
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
PARSING EXPRESSION max(0, log( drain / tan(max(0,slope-1)) ) ) ) ) ) ) 1 -e p o l s , 0 ( x a m ( n a t / n i a r d ( g o l , 0 ( x a m = t a s . x e d n i G N I T U C E X E complete: 100%
CREATING SUPPORT FILES FOR index.sat 2 1 e u l a v m u m i x a m , 0 e u l a v m u m i n i m _________________________________________________________
You are now finished with the examples and the sample session. See the entry for r.mapcalc in p a m w e n e h t p e e k o t t n a w u o y s s e l n U . s e l p m a x e l a n o i t i d d a r o f l a u n a M e c n e r e f e R s ’ r e s U S S A R G e h t
layers created with this tutorial, you may want to remove them now to conserve disk space.
S N O I T A D N E M M O C E R D N A S N O I S U L C N O C . 5
This manual is part of an ongoing process to document Geographic Resources Analysis Support System o t d e t n e m e l p m i g n i e b s m s i n a h c e m r e f s n a r t y g o l o n h c e t y n a m f o e n o s i t I . s n o i t c n u f m a r g o r p ) S S A R G (
explain current, and future, GRASS program capabilities to resource managers and system users. -u t i t s n i , s r e t t e l s w e n , r e t n e c t r o p p u s -r e s u a , e s u n o -s d n a h , s m a r g o r p g n i n i a r t h t i w g n o l a , n o i t a t n e m u c o D
tional structures at the Army and interagency levels, communication networks, and other forums, can be . t r o ff e r e f s n a r t y g o l o n h c e t g n i o g n o s i h t d i a o t d e s u
User feedback on GRASS program capabilities, documentation, and other technology transfer mechan-ff a t s t n e m p o l e v e d S S A R G o t k c a b d e e f h c u s e t a c i n u m m o c o t d e g a r u o c n e e r a s r e s U . d e d e e n o s l a s i s m s i
at USACERL, via existing electronic communication networks and via the GRASS Information Center -e ; 2 2 2 7 -3 7 3 -7 1 2 x a f ; 0 2 2 7 -3 7 3 -7 1 2 e n o h p ; 5 0 0 9 -6 2 8 1 6 L I , n g i a p m a h C , 5 0 0 9 x o B . O . P , L R E C A S U t a mail [email protected]. REFERENCES l a t i g i D a f o t n e m p o l e v e D e h t n i s e u s s I c i h p a r g o t r a C , h t i m s r e s s e M . M n a e J d n a , . S n y l i r a M , z i u R
GRASS Database, USACERL Special Report N-90/16 (U.S. Army Construction Engineering . ) 0 9 9 1 r e b m e t p e S , ] L R E C A S U [ y r o t a r o b a L h c r a e s e R
Shapiro, Michael and James Westervelt, r.mapcalc: An Algebra for GIS and Image Processing, Draft . ) 2 9 9 1 r e m m u S , L R E C A S U ( t r o p e R P D A
Westervelt, James, and William D. Goran, Introduction to GRASS 4, Draft ADP Report (USACERL, . ) 1 9 9 1 y l u J
Westervelt, James, Mary Martin, and Deborah Brinegar, "GRASS 4.0 Programs," in GRASS User’s d e s i v e r t s a l , 8 8 9 1 r e b m e t p e S , L R E C A S U ( v e r 2 2 / 7 8 -N t r o p e R P D A , l a u n a M e c n e r e f e R December 1991).
Westervelt, James, Michael Shapiro, William D. Goran, et al., GRASS User’s Reference Manual, ADP . ) 1 9 9 1 r e b m e c e D d e s i v e r t s a l , 8 8 9 1 r e b m e t p e S , L R E C A S U ( v e r 2 2 / 7 8 -N t r o p e R
