1r.mfilter(1)                GRASS GIS User's Manual               r.mfilter(1)
2
3
4

NAME

6       r.mfilter  - Performs raster map matrix filter.
7

KEYWORDS

9       raster, algebra, statistics, filter, parallel
10

SYNOPSIS

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
18   Flags:
19       -z
20           Apply filter only to null data values
21
22       --overwrite
23           Allow output files to overwrite existing files
24
25       --help
26           Print usage summary
27
28       --verbose
29           Verbose module output
30
31       --quiet
32           Quiet module output
33
34       --ui
35           Force launching GUI dialog
36
37   Parameters:
38       input=name [required]
39           Name of input raster map
40
41       output=name [required]
42           Name for output raster map
43
44       filter=name [required]
45           Path to filter file
46
47       repeat=integer
48           Number of times to repeat the filter
49           Default: 1
50
51       title=string
52           Output raster map title
53
54       nprocs=integer
55           Number of threads for parallel computing
56           Default: 1
57

DESCRIPTION

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
62       Figure: Illustration for a custom 3x3 filter
63
64       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
68       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
76       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
81       The  repeat  parameter  defines the number of times the filter is to be
82       applied to the input data.
83
84   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
95       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
101       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
107       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
112       TYPE
113           The  filter  type.   S means sequential, while P mean parallel.  If
114           not specified, the default is S.
115
116       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
121       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
124       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
128   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
145   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
154       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
163   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
171       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

NOTES

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

SEE ALSO

182        g.region, r.clump, r.neighbors, r.resamp.filter,
183       Raster Parallelization with OpenMP
184

AUTHORS

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

SOURCE CODE

191       Available at: r.mfilter source code (history)
192
193       Accessed: Saturday Jan 21 21:14:47 2023
194
195       Main  index  | Raster index | Topics index | Keywords index | Graphical
196       index | Full index
197
198       © 2003-2023 GRASS Development Team, GRASS GIS 8.2.1 Reference Manual
199
200
201
202GRASS 8.2.1                                                       r.mfilter(1)
Impressum