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 according 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 inter-
       actively.  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 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  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 spec-
	      ifies 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 cate-
	      gory 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 cat-
	      egory  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 output.

       ffiilltteerr==_n_a_m_e
	      The name of an existing,	user-created  UNIX  ASCII
	      file whose contents 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 speci-
	      fied 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 consists 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  additional	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 average
	    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 cat-
       egory 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  inte-
       ger.   (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  fil-
       ter  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.

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

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)
