Debian Codegraph @

raster/r.resamp.filter/r.resamp.filter.html

raw
1 <h2>DESCRIPTION</h2>
2
3 <em>r.resamp.filter</em> resamples an input raster, filtering the
4 input with an analytic kernel. Each output cell is typically calculated
5 based upon a small subset of the input cells, not the entire input.
6 <em>r.resamp.filter</em> performs convolution (i.e. a weighted sum is
7 calculated for every raster cell).
8
9 <p>
10 The radii must be given in map units. In order to consider more than
11 one input cell, at least one finite radius must be larger than half the
12 resolution of the input map, otherwise the selected kernels will have
13 no effect.
14
15 <p>
16 The module maps the input range to the width of the window function, so
17 wider windows will be "sharper" (have a higher cut-off frequency), e.g.
18 lanczos3 will be sharper than lanczos2.
19
20 <p>
21 <em>r.resamp.filter</em> implements FIR (finite impulse response) filtering. All
22 of the functions are low-pass filters, as they are symmetric. See
23 <a href="https://en.wikipedia.org/wiki/Window_function">Wikipedia: Window function</a>
24 for examples of common window functions and their frequency responses.
25
26 <p>
27 A piecewise-continuous function defined by sampled data can be considered
28 a mixture (sum) of the underlying signal and quantisation noise. The
29 intent of a low pass filter is to discard the quantisation noise while
30 retaining the signal.
31
32 The cut-off frequency is normally chosen according to the sampling
33 frequency, as the quantisation noise is dominated by the sampling
34 frequency and its harmonics. In general, the cut-off frequency is
35 inversely proportional to the width of the central "lobe" of the window
36 function.
37
38 <p>
39 When using <em>r.resamp.filter</em> with a specific radius, a specific
40 cut-off frequency regardless of the method is chosen. So while lanczos3
41 uses 3 times as large a window as lanczos1, the cut-off frequency remains
42 the same. Effectively, the radius is "normalised".
43
44 <p>
45 All of the kernels specified by the <b>filter</b> parameter are
46 multiplied together. Typical usage will use either a single finitie
47 window or an infinite kernel along with a finite window.
48
49 <h3>Usage hints</h3>
50 <p>
51 To smooth a map, keeping its resolution, a good starting point is to
52 use the filters <b>gauss,box</b> with the radii <em>0.5 * input
53 resolution</em>, <em>2 * input resolution</em>. See also <a
54 href="r.neighbors.html">r.neighbors</a>
55
56 <p>
57 When resampling a map to a higher resolution (alternative to
58 interpolation, e.g. <a
59 href="r.resamp.interp.html">r.resamp.interp</a>), a good starting point
60 is to use the filters <b>gauss,box</b> with the radii <em>1.5 * input
61 resolution</em>, <em>3 * input resolution</em>.
62
63 <p>
64 When resampling a map to a lower resolution (alternative to
65 aggregation, e.g. <a href="r.resamp.stats.html">r.resamp.stats</a>), a
66 good starting point is to use the filters <b>gauss,box</b> with the
67 radii <em>0.25 * output resolution</em>, <em>1 * output
68 resolution</em>.
69
70 <p>
71 These are recommendations for initial settings. The selection of
72 filters and radii might need adjustment according to the actual
73 purpose.
74
75 <h2>NOTES</h2>
76
77 Resampling modules (<em>r.resample, r.resamp.stats, r.resamp.interp,
78 r.resamp.rst, r.resamp.filter</em>) resample the map to match the
79 current region settings.
80
81 <p>
82 When using a kernel which can have negative values (sinc, Lanczos),
83 the <em>-n</em> flag should be used. Otherwise, extreme values can
84 arise due to the total weight being close (or even equal) to zero.
85
86 <p>
87 Kernels with infinite extent (Gauss, normal, sinc, Hann, Hamming,
88 Blackman) must be used in conjunction with a finite windowing function
89 (box, Bartlett, Hermite, Lanczos).
90
91 <p>
92 The way that Lanczos filters are defined, the number of samples is
93 supposed to be proportional to the order ("a" parameter), so lanczos3
94 should use 3 times as many samples (at the same sampling frequency, i.e.
95 cover 3 times as large a time interval) as lanczos1 in order to get a
96 similar frequency response (higher-order filters will fall off faster, but
97 the frequency at which the fall-off starts should be the same). See
98 <a href="https://en.wikipedia.org/wiki/File:Lanczos-kernel.svg">Wikipedia: Lanczos-kernel.svg</a>
99 for an illustration. If both graphs were drawn on the same axes, they
100 would have roughly the same shape, but the a=3 window would have a longer
101 tail. By scaling the axes to the same width, the a=3 window has a narrower
102 central lobe.
103
104 <p>
105 For longitude-latitude coordinate reference systems,
106 the interpolation algorithm is based on
107 degree fractions, not on the absolute distances between cell centers. Any
108 attempt to implement the latter would violate the integrity of the
109 interpolation method.
110
111 <h3>PERFORMANCE</h3>
112 <p>By specifying the number of parallel processes with <b>nprocs</b> option,
113 <em>r.resamp.filter</em> can run faster, see benchmarks below.
114
115 <div align="center" style="margin: 10px">
116 <img src="r_resamp_filter_benchmark_size.png" alt="benchmark for number of cells" border="0">
117 <br>
118 <i>Figure: Benchmark shows execution time for different
119 number of cells. See benchmark script in the source code.</i>
120 </div>
121 <p>To reduce the memory requirements to minimum, set option <b>memory</b> to zero.
122 To take advantage of the parallelization, GRASS
123 needs to compiled with OpenMP enabled.
124
125
126 <h2>SEE ALSO</h2>
127
128 <em>
129 <a href="g.region.html">g.region</a>,
130 <a href="r.mfilter.html">r.mfilter</a>,
131 <a href="r.resample.html">r.resample</a>,
132 <a href="r.resamp.interp.html">r.resamp.interp</a>,
133 <a href="r.resamp.rst.html">r.resamp.rst</a>,
134 <a href="r.resamp.stats.html">r.resamp.stats</a>
135 </em>
136
137 <p>
138 Overview: <a href="https://grasswiki.osgeo.org/wiki/Interpolation">Interpolation and Resampling</a> in GRASS
139
140 <h2>AUTHOR</h2>
141
142 Glynn Clements