| 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 |