Provided by: grass-doc_8.3.0-1_all bug

NAME

       r.mfilter  - Performs raster map matrix filter.

KEYWORDS

       raster, algebra, statistics, filter, parallel

SYNOPSIS

       r.mfilter
       r.mfilter --help
       r.mfilter  [-z]  input=name  output=name  filter=name   [repeat=integer]    [title=string]
       [nprocs=integer]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

   Flags:
       -z
           Apply filter only to null data values

       --overwrite
           Allow output files to overwrite existing files

       --help
           Print usage summary

       --verbose
           Verbose module output

       --quiet
           Quiet module output

       --ui
           Force launching GUI dialog

   Parameters:
       input=name [required]
           Name of input raster map

       output=name [required]
           Name for output raster map

       filter=name [required]
           Path to filter file

       repeat=integer
           Number of times to repeat the filter
           Default: 1

       title=string
           Output raster map title

       nprocs=integer
           Number of threads for parallel computing
           Default: 1

DESCRIPTION

       r.mfilter filters the raster input to produce the raster output according  to  the  matrix
       filter designed by the user (see FILTERS below).

       Figure: Illustration for a custom 3x3 filter

       The  filter is applied repeat times (default value is 1).  The output raster map layer can
       be given a TITLE if desired.  (This TITLE should be put in quotes if it contains more than
       one word.)

       With -z flag the filter is applied only to null values in the input raster map layer.  The
       non-null 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 null 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.

       The  filter  parameter defines the name of an existing, user-created UNIX ASCII file whose
       contents is a matrix defining the way in which the input file will be filtered. The format
       of this file is described below, under FILTERS.

       The  repeat parameter defines the number of times the filter is to be applied to the input
       data.

   FILTERS
       The filter file is a normal UNIX ASCII file designed by the user.  It  has  the  following
       format:
            TITLE      TITLE
            MATRIX     n
                         .
            n lines of n values
                         .
            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 consists of n rows of n values.  The values 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:

   EXAMPLE FILTER FILE
             TITLE     3x3 average, non-null 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

   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.  (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-null.)

       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.

   PERFORMANCE
       By specifying the number of parallel processes  with  nprocs  option,  r.mfilter  can  run
       significantly faster, see benchmarks below.
       Figure:  Benchmark  on the left shows execution time for different number of cells for 9x9
       matrix, benchmark on the right shows execution time for 16  billion  cells  for  different
       matrix sizes. (Intel Core i9-10940X CPU @ 3.30GHz x 28)

       Note  that parallelization is implemented only for the parallel filter, not the sequential
       one.  To take advantage of the parallelization, GRASS GIS needs to  compiled  with  OpenMP
       enabled.

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.

SEE ALSO

        g.region, r.clump, r.neighbors, r.resamp.filter,
       Raster Parallelization with OpenMP

AUTHORS

       Glynn   Clements.   Based  upon  r.mfilter,  by  Michael  Shapiro,  U.S.Army  Construction
       Engineering Research Laboratory.
       Aaron Saw Min Sern (OpenMP support).

SOURCE CODE

       Available at: r.mfilter source code (history)

       Accessed: Tuesday Jun 27 11:12:55 2023

       Main index | Raster index | Topics index | Keywords index | Graphical index | Full index

       © 2003-2023 GRASS Development Team, GRASS GIS 8.3.0 Reference Manual