.TH r.mfilter
.SH NAME
\fIr.mfilter\fR - Raster file matrix filter.
.br
.I (GRASS Raster Program)
.SH SYNOPSIS
\fBr.mfilter\fR
.br
\fBr.mfilter help\fR
.br
\fBr.mfilter \fR[\fB-qpz\fR] \fBinput\*=\fIname \fBoutput\*=\fIname \fBfilter\*=\fIname \fR[\fBrepeat\*=\fIvalue\fR] \
[\fBtitle\*=\fI"phrase"\fR]
.SH DESCRIPTION
\fIr.mfilter\fR filters the raster \fIinput\fR to produce the
raster \fIoutput\fR according to the matrix \fIfilter\fR designed
by the user (see \fIFILTERS\fR below).
The filter is applied \fIrepeat\fR times (default \fIvalue\fR is 1).
The \fIoutput\fR raster map layer can be given a \fItitle\fR if desired.
(This title should be put in quotes if it contains more than one word.)
.SH OPTIONS
The program can be run either non-interactively or interactively.
To run \fIr.mfilter\fR non-interactively, the user should specify desired
flag settings and parameter values on the command line, using the form:
.LP
.RS
\fBr.mfilter \fR[\fB-qpz\fR] \fBinput\*=\fIname \fBoutput\*=\fIname \fBfilter\*=\fIname \fR[\fBrepeat\*=\fIvalue\fR] \
[\fBtitle\*=\fI"phrase"\fR]
.RE
.LP
If the user specifies \fIinput\fR, \fIoutput\fR, and \fIfilter\fR file names
on the command line, other parameters whose values are unspecified on the
command line will be set to their default values (see below).

Alternately, the user can simply type \fBr.mfilter\fR on the command line,
without program arguments.  In this case, the user will be prompted for
flag settings and parameter values using the standard GRASS parser interface
described in the manual entry for \fIparser\fR.
.LP
\fBFlags:\fR
.IP \fB-q\fR 18
\fIr.mfilter\fR will normally print messages to indicate what is is doing as it
proceeds.  If the user specifies the -q flag, the program will run quietly.
.\" .IP \fB-p\fR 18
.\" Preserves the edge.
.\" If unspecified by the user, the edge will not be preserved.
.IP \fB-z\fR 18
The filter is applied only to zero category values in the input raster
map layer.  The non-zero category values are not changed.
Note that if there is more than one filter step,
this rule is applied to the intermediate raster
map layer -- only zero category values which result from the first filter will
be changed.  In most cases this will NOT be the desired result.
Hence -z should be used only with single step filters.
.LP
\fBParameters:\fR
.IP \fBinput\*=\fIname\fR 18
The name of an existing raster file containing data values to be filtered.
.IP \fBoutput\*=\fIname\fR 18
The name of the new raster file to contain filtered program output.
.IP \fBfilter\*=\fIname\fR 18
The name of an existing, user-created UNIX ASCII file whose contents is a
matrix defining the way in which the \fIinput\fR file will be filtered.
The format of this file is described below, under FILTERS.
.IP \fBrepeat\*=\fIvalue\fR 18
The number of times the \fIfilter\fR is to be applied to the \fIinput\fR data.
.br
Options:  integer values
.br
Default:  1
.IP \fBtitle\*="\fIphrase\fR" 18
A title to be assigned to the filtered raster \fIoutput\fR map.
If the title exceeds one word, it should be quoted.
.br
Default:  (none)


.SH FILTERS
The \fIfilter\fR file is a normal UNIX ASCII file designed by the user.
It has the following format:

.TS
tab(:);
ll.
TITLE:title
MATRIX:n
:.
.T&
ls.
n lines of n integers
.T&
ll.
:.
DIVISOR:d
.\" START:UL/LL/UR/LR
TYPE:S/P
.TE

.IP TITLE 10
A one-line title for the filter.
If a title was not specified on the command line, it can be specified here.
This title would be used to construct a title for the resulting raster map
layer.  It should be a one-line description of the filter.
.IP MATRIX
The matrix (n x n) follows on the next n lines.  \fIn\fR must be
an odd integer greater than or equal to 3.
The matrix itself consists of n rows of n integers.
The integers must be separated from each other by at least 1 blank.
.IP DIVISOR
The filter divisor is \fId\fR.  If not specified, the default is 1.
If the divisor is zero (0), then the divisor is dependent on the
category values in the neighborhood
(see HOW THE FILTER WORKS below).
.\" .IP START
.\" This specifies the starting corner for the filter.
.\" This also specifies the movement of the filter.
.\" If not specified, the default is UL.
.\" .RS
.\" .IP UL
.\" Upper left (to lower right)
.\" .IP UR
.\" Upper right (to lower left)
.\" .IP LL
.\" Lower left (to upper right)
.\" .IP LR
.\" Lower right (to upper left)
.\" .RE
.IP TYPE
The filter type.  \fIS\fR means sequential, while \fIP\fR mean parallel.
If not specified, the default is S.

Sequential filtering happens in place.  As the filter is applied to the
raster map layer, the category values that were changed in neighboring
cells affect the resulting category value of the current
cell being filtered.

Parallel filtering happens in such a way that the original raster
map layer category values are used to produce the new category value.

.LP
More than one filter may be specified in the filter file.
The additional filter(s) are described just like the first.
For example, the following describes two filters:

.SH EXAMPLE FILTER FILE

.TS
tab(:);
ll.
TITLE:3x3 average, non-zero data only, followed by 5x5 average
MATRIX:3
.T&
ls.
1 1 1
1 1 1
1 1 1
.T&
ll.
DIVISOR:0
.\" START:UL
TYPE:P

MATRIX:5
.T&
ls.
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
1 1 1 1 1
.T&
ll.
DIVISOR:25
.\" START:UL
TYPE:P
.TE
.SH HOW THE FILTER WORKS
The filter process produces a new category value for each cell
in the input raster map layer by multiplying the category values of the
cells in the n x n neighborhood around the center cell
by the corresponding matrix value and adding them together.
If a divisor is specified, the sum is divided by this divisor,
rounding to the nearest integer.
(If a zero divisor was specified, then
the divisor is computed for each cell as the sum of the MATRIX
values where the corresponding input cell is non-zero.)

If more than one filter step is specified, either because the
repeat value was greater than one or because the filter file
contained more than one matrix, these steps are performed
sequentially. This means that first one filter is applied to
the entire input raster map layer to produce an intermediate result;
then the next filter is applied to the intermediate result to
produce another intermediate result;  and so on, until the
final filter is applied.  Then the output cell is written.
.SH NOTES
If the resolution of the geographic region does not agree with the
resolution of the raster map layer, unintended resampling of the original
data may occur.  The user should be sure that the geographic region
is set properly.
.SH SEE ALSO
.I g.region,
.I r.clump,
.I r.neighbors,
and
.I parser
.SH AUTHOR
Michael Shapiro, U.S. Army Construction Engineering Laboratory