1r.mfilter(1) GRASS GIS User's Manual r.mfilter(1)
2
6 r.mfilter - Performs raster map matrix filter.
7
9 raster, algebra, statistics, filter, parallel
10
12 r.mfilter
13 r.mfilter --help
14 r.mfilter [-z] input=name output=name filter=name [repeat=integer]
15 [title=string] [nprocs=integer] [--overwrite] [--help] [--ver‐
16 bose] [--quiet] [--ui]
17 Flags:
19 -z
20 Apply filter only to null data values
21 --overwrite
23 Allow output files to overwrite existing files
24 --help
26 Print usage summary
27 --verbose
29 Verbose module output
30 --quiet
32 Quiet module output
33 --ui
35 Force launching GUI dialog
36 Parameters:
38 input=name [required]
39 Name of input raster map
40 output=name [required]
42 Name for output raster map
43 filter=name [required]
45 Path to filter file
46 repeat=integer
48 Number of times to repeat the filter
49 Default: 1
50 title=string
52 Output raster map title
53 nprocs=integer
55 Number of threads for parallel computing
56 Default: 1
57
59 r.mfilter filters the raster input to produce the raster output accord‐
60 ing to the matrix filter designed by the user (see FILTERS below).
61 Figure: Illustration for a custom 3x3 filter
63 The filter is applied repeat times (default value is 1). The output
65 raster map layer can be given a TITLE if desired. (This TITLE should
66 be put in quotes if it contains more than one word.)
67 With -z flag the filter is applied only to null values in the input
69 raster map layer. The non-null category values are not changed. Note
70 that if there is more than one filter step, this rule is applied to the
71 intermediate raster map layer -- only null category values which result
72 from the first filter will be changed. In most cases this will NOT be
73 the desired result. Hence -z should be used only with single step fil‐
74 ters.
75 The filter parameter defines the name of an existing, user-created UNIX
77 ASCII file whose contents is a matrix defining the way in which the in‐
78 put file will be filtered. The format of this file is described below,
79 under FILTERS.
80 The repeat parameter defines the number of times the filter is to be
82 applied to the input data.
83 FILTERS
85 The filter file is a normal UNIX ASCII file designed by the user. It
86 has the following format:
87 TITLE TITLE
88 MATRIX n
89 .
90 n lines of n values
91 .
92 DIVISOR d
93 TYPE S/P
94 TITLE
96 A one-line TITLE for the filter. If a TITLE was not specified on
97 the command line, it can be specified here. This TITLE would be
98 used to construct a TITLE for the resulting raster map layer. It
99 should be a one-line description of the filter.
100 MATRIX
102 The matrix (n x n) follows on the next n lines. n must be an odd
103 integer greater than or equal to 3. The matrix itself consists of
104 n rows of n values. The values must be separated from each other
105 by at least 1 blank.
106 DIVISOR
108 The filter divisor is d. If not specified, the default is 1. If
109 the divisor is zero (0), then the divisor is dependent on the cate‐
110 gory values in the neighborhood (see HOW THE FILTER WORKS below).
111 TYPE
113 The filter type. S means sequential, while P mean parallel. If
114 not specified, the default is S.
115 Sequential filtering happens in place. As the filter is applied to the
117 raster map layer, the category values that were changed in neighboring
118 cells affect the resulting category value of the current cell being
119 filtered.
120 Parallel filtering happens in such a way that the original raster map
122 layer category values are used to produce the new category value.
123 More than one filter may be specified in the filter file. The addi‐
125 tional filter(s) are described just like the first. For example, the
126 following describes two filters:
127 EXAMPLE FILTER FILE
129 TITLE 3x3 average, non-null data only, followed by 5x5 average
130 MATRIX 3
131 1 1 1
132 1 1 1
133 1 1 1
134 DIVISOR 0
135 TYPE P
136 MATRIX 5
137 1 1 1 1 1
138 1 1 1 1 1
139 1 1 1 1 1
140 1 1 1 1 1
141 1 1 1 1 1
142 DIVISOR 25
143 TYPE P
144 HOW THE FILTER WORKS
146 The filter process produces a new category value for each cell in the
147 input raster map layer by multiplying the category values of the cells
148 in the n x n neighborhood around the center cell by the corresponding
149 matrix value and adding them together. If a divisor is specified, the
150 sum is divided by this divisor. (If a zero divisor was specified, then
151 the divisor is computed for each cell as the sum of the MATRIX values
152 where the corresponding input cell is non-null.)
153 If more than one filter step is specified, either because the repeat
155 value was greater than one or because the filter file contained more
156 than one matrix, these steps are performed sequentially. This means
157 that first one filter is applied to the entire input raster map layer
158 to produce an intermediate result; then the next filter is applied to
159 the intermediate result to produce another intermediate result; and so
160 on, until the final filter is applied. Then the output cell is writ‐
161 ten.
162 PERFORMANCE
164 By specifying the number of parallel processes with nprocs option,
165 r.mfilter can run significantly faster, see benchmarks below.
166 Figure: Benchmark on the left shows execution time for different number
167 of cells for 9x9 matrix, benchmark on the right shows execution time
168 for 16 billion cells for different matrix sizes. (Intel Core i9-10940X
169 CPU @ 3.30GHz x 28)
170 Note that parallelization is implemented only for the parallel filter,
172 not the sequential one. To take advantage of the parallelization,
173 GRASS GIS needs to compiled with OpenMP enabled.
174
176 If the resolution of the geographic region does not agree with the res‐
177 olution of the raster map layer, unintended resampling of the original
178 data may occur. The user should be sure that the geographic region is
179 set properly.
180
182 g.region, r.clump, r.neighbors, r.resamp.filter,
183 Raster Parallelization with OpenMP
184
186 Glynn Clements. Based upon r.mfilter, by Michael Shapiro, U.S.Army
187 Construction Engineering Research Laboratory.
188 Aaron Saw Min Sern (OpenMP support).
189
191 Available at: r.mfilter source code (history)
192 Accessed: Saturday Jan 21 21:14:47 2023
194 Main index | Raster index | Topics index | Keywords index | Graphical
196 index | Full index
197 © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
199GRASS 8.2.1 r.mfilter(1)