r.mfilter(1)		      Grass User's Manual		  r.mfilter(1)



NNAAMMEE
       rr..mmffiilltteerr - Raster file matrix filter.
       _(_G_R_A_S_S _R_a_s_t_e_r _P_r_o_g_r_a_m_)

SSYYNNOOPPSSIISS
       rr..mmffiilltteerr
       rr..mmffiilltteerr hheellpp
       rr..mmffiilltteerr  [--qqppzz]  iinnppuutt==_n_a_m_e  oouuttppuutt==_n_a_m_e  ffiilltteerr==_n_a_m_e	[rreeppeeaatt==_v_a_l_u_e]
       [TTIITTLLEE==_"_p_h_r_a_s_e_"]

DDEESSCCRRIIPPTTIIOONN
       _r_._m_f_i_l_t_e_r filters the raster _i_n_p_u_t to produce the raster _o_u_t_p_u_t accord-
       ing to the matrix _f_i_l_t_e_r designed by the user (see _F_I_L_T_E_R_S below).  The
       filter is applied _r_e_p_e_a_t times (default _v_a_l_u_e is 1).  The _o_u_t_p_u_t raster
       map  layer  can be given a _T_I_T_L_E if desired.  (This TITLE should be put
       in quotes if it contains more than one word.)

OOPPTTIIOONNSS
       The program can be run either non-interactively or  interactively.   To
       run  _r_._m_f_i_l_t_e_r  non-interactively, the user should specify desired flag
       settings and parameter values on the command line, using the form:


       rr..mmffiilltteerr  [--qqppzz]  iinnppuutt==_n_a_m_e  oouuttppuutt==_n_a_m_e  ffiilltteerr==_n_a_m_e	[rreeppeeaatt==_v_a_l_u_e]
       [TTIITTLLEE==_"_p_h_r_a_s_e_"]



       If  the user specifies _i_n_p_u_t, _o_u_t_p_u_t, and _f_i_l_t_e_r file names on the com-
       mand 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 rr..mmffiilltteerr 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 _p_a_r_s_e_r.



   FFllaaggss::
       --qq     _r_._m_f_i_l_t_e_r 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.

       --zz     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 cate-
	      gory 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.




   PPaarraammeetteerrss::
       iinnppuutt==_n_a_m_e
	      The name of an existing raster file containing data values to be
	      filtered.

       oouuttppuutt==_n_a_m_e
	      The name of the new raster file to contain filtered program out-
	      put.

       ffiilltteerr==_n_a_m_e
	      The name of an existing, user-created UNIX ASCII file whose con-
	      tents  is a matrix defining the way in which the _i_n_p_u_t file will
	      be filtered.  The format of this file is described below,  under
	      FILTERS.

       rreeppeeaatt==_v_a_l_u_e
	      The  number  of  times  the _f_i_l_t_e_r is to be applied to the _i_n_p_u_t
	      data.
	      Options:	integer values
	      Default:	1

       TTIITTLLEE== A TITLE to be assigned to the filtered raster  _o_u_t_p_u_t  map.   If
	      the TITLE exceeds one word, it should be quoted.
	      Default:	(none)






FFIILLTTEERRSS
       The  _f_i_l_t_e_r  file is a normal UNIX ASCII file designed by the user.  It
       has the following format:

	    TITLE      TITLE
	    MATRIX     n
			 .
	    n lines of n integers
			 .
	    DIVISOR    d
	    TYPE	S/P


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

       MATRIX The  matrix  (n  x n) follows on the next n lines.  _n must be an
	      odd integer greater than or equal to 3.  The matrix itself  con-
	      sists  of  n rows of n integers.	The integers must be separated
	      from each other by at least 1 blank.

       DIVISOR
	      The filter divisor is _d.	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).

       TYPE   The filter type.	_S means sequential, while _P 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.




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




EEXXAAMMPPLLEE FFIILLTTEERR FFIILLEE
	     TITLE     3x3 average, non-zero data only, followed by 5x5  aver-
       age
	    MATRIX    3
	    1 1 1
	    1 1 1
	    1 1 1
	    DIVISOR   0
	    TYPE      P

	    MATRIX    5
	    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
	    DIVISOR   25
	    TYPE      P


HHOOWW TTHHEE FFIILLTTEERR WWOORRKKSS
       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  writ-
       ten.

NNOOTTEESS
       If the resolution of the geographic region does not agree with the res-
       olution 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.

SSEEEE AALLSSOO
       _g_._r_e_g_i_o_n

       _r_._c_l_u_m_p

       _r_._n_e_i_g_h_b_o_r_s

       _p_a_r_s_e_r

AAUUTTHHOORR
       Michael Shapiro, U.S.Army Construction Engineering Research Laboratory

       _L_a_s_t _c_h_a_n_g_e_d_: _$_D_a_t_e_: _2_0_0_2_/_0_1_/_2_5 _0_5_:_4_5_:_3_4 _$



GRASS 5.0							  r.mfilter(1)
