[GRASS-SVN] r66126 - grass/trunk/raster/r.resamp.filter

[svn_grass at osgeo.org]

Author: neteler
Date: 2015-09-06 06:05:47 -0700 (Sun, 06 Sep 2015)
New Revision: 66126

Modified:
   grass/trunk/raster/r.resamp.filter/r.resamp.filter.html
Log:
r.resamp.filter manual: expanded based on Glynn's comments in https://trac.osgeo.org/grass/ticket/1401#comment:8

Modified: grass/trunk/raster/r.resamp.filter/r.resamp.filter.html
===================================================================
--- grass/trunk/raster/r.resamp.filter/r.resamp.filter.html	2015-09-06 12:30:22 UTC (rev 66125)
+++ grass/trunk/raster/r.resamp.filter/r.resamp.filter.html	2015-09-06 13:05:47 UTC (rev 66126)
@@ -1,43 +1,91 @@
 <h2>DESCRIPTION</h2>
 
-<p><em>r.resamp.filter</em> resamples an input raster, filtering the
-input with an analytic kernel.
+<em>r.resamp.filter</em> resamples an input raster, filtering the
+input with an analytic kernel. Each output cell is typically calculated
+based upon a small subset of the input cells, not the entire input.
+<em>r.resamp.filter</em> performs convolution (i.e. a weighted sum is
+calculated for every raster cell).
 
-<p>All of the kernels specified by the filter= option are multiplied
-together. Typical usage will use either a single kernel or an infinite
-kernel along with a finite window.
+<p>
+The module maps the input range to the width of the window function, so
+wider windows will be "sharper" (have a higher cut-off frequency), e.g.
+lanczos3 will be sharper than lanczos2.
 
+<p>
+r.resamp.filter implements FIR (finite impulse response) filtering. All
+of the functions are low-pass filters, as they are symmetric. See
+<a href="http://en.wikipedia.org/wiki/Window_function">Wikipedia: Window function</a>
+for examples of common window functions and their frequency responses.
 
+<p>
+A piecewise-continuous function defined by sampled data can be considered
+a mixture (sum) of the underlying signal and quantisation noise. The
+intent of a low pass filter is to discard the quantisation noise while
+retaining the signal.
+
+The cut-off frequency is normally chosen according to the sampling
+frequency, as the quantisation noise is dominated by the sampling
+frequency and its harmonics. In general, the cut-off frequency is
+inversely proportional to the width of the central "lobe" of the window
+function.
+
+<p>
+When using <em>r.resamp.filter</em> with a specific radius, a specific
+cut-off frequency regardless of the method is chosen. So while lanczos3
+uses 3 times as large a window as lanczos1, the cut-off frequency remains
+the same. Effectively, the radius is "normalised".
+
+<p>
+All of the kernels specified by the <b>filter</b> parameter are
+multiplied together. Typical usage will use either a single kernel or an
+infinite kernel along with a finite window.
+
+
 <h2>NOTES</h2>
 
-<p>Resampling modules (<em>r.resample, r.resamp.stats, r.resamp.interp,
+Resampling modules (<em>r.resample, r.resamp.stats, r.resamp.interp,
 r.resamp.rst, r.resamp.filter</em>) resample the map to match the
 current region settings.
 
- 
-<p>When using a kernel which can have negative values (sinc, Lanczos),
+<p>
+When using a kernel which can have negative values (sinc, Lanczos),
 the <em>-n</em> flag should be used. Otherwise, extreme values can
 arise due to the total weight being close (or even equal) to zero.
 
- 
-<p>Kernels with infinite extent (Gauss, normal, sinc, Hann, Hamming,
+<p>
+Kernels with infinite extent (Gauss, normal, sinc, Hann, Hamming,
 Blackman) must be used in conjunction with a finite windowing function
-(box, Bartlett, Hermite, Lanczos)
+(box, Bartlett, Hermite, Lanczos).
 
+<p>
+The way that Lanczos filters are defined, the number of samples is
+supposed to be proportional to the order ("a" parameter), so lanczos3
+should use 3 times as many samples (at the same sampling frequency, i.e.
+cover 3 times as large a time interval) as lanczos1 in order to get a
+similar frequency response (higher-order filters will fall off faster, but
+the frequency at which the fall-off starts should be the same). See 
+<a href="http://en.wikipedia.org/wiki/File:Lanczos-kernel.svg">Wikipedia: Lanczos-kernel.svg</a>
+for an illustration. If both graphs were drawn on the same axes, they
+would have roughly the same shape, but the a=3 window would have a longer
+tail. By scaling the axes to the same width, the a=3 window has a narrower
+central lobe.
 
-<p>For longitude-latitude locations, the interpolation algorithm is based on
+<p>
+For longitude-latitude locations, the interpolation algorithm is based on
 degree fractions, not on the absolute distances between cell centers.  Any
 attempt to implement the latter would violate the integrity of the
 interpolation method.
 
 
-
 <h2>SEE ALSO</h2>
 
-<em><a href="g.region.html">g.region</a></em>,
-<em><a href="r.resample.html">r.resample</a></em>,
-<em><a href="r.resamp.rst.html">r.resamp.rst</a></em>
-<em><a href="r.resamp.stats.html">r.resamp.stats</a></em>
+<em>
+<a href="g.region.html">g.region</a>,
+<a href="r.resample.html">r.resample</a>,
+<a href="r.resamp.interp.html">r.resamp.interp</a>,
+<a href="r.resamp.rst.html">r.resamp.rst</a>,
+<a href="r.resamp.stats.html">r.resamp.stats</a>
+</em>
 
 <h2>AUTHOR</h2>