r.mfilter(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

👑 r.mfilter — Performs raster map matrix filter 💖

okay bestie, welcome to the GRASS GIS User's Manual, section 1, where we're talking about r.mfilter — the little module that runs your raster through a matrix filter and serves LOOKS. 💅

🌈 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 💜

So r.mfilter takes your raster input and filters it into a whole new raster output, using a matrix filter that you designed yourself (the deets are down in FILTERS, keep scrolling bestie).

Figure: Illustration for a custom 3x3 filter

The filter gets applied repeat times (default is 1, no drama). And if you want, your output raster map layer can be given a TITLE — just put that TITLE in quotes if it's more than one word, or the shell will absolutely eat it. 🙈

With the -z flag, the filter is applied only to null values in the input raster map layer. The non-null category values are not changed, periodt. But lowkey important: if there's more than one filter step, this rule gets applied to the intermediate raster map layer — meaning only the null category values that result from the first filter will get changed. In most cases this will NOT be the desired result. So -z should only be used with single step filters, fr fr.

The filter parameter is the name of an existing, user-created UNIX ASCII file whose contents are a matrix defining the way the input file gets filtered. The format of that file is described below, under FILTERS. 👇

The repeat parameter is literally just the number of times the filter is applied to the input data.

🧚 FILTERS 🧚

The filter file is a normal UNIX ASCII file that you designed. It has this 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 wasn't specified on the command line, it can be specified here instead. 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, keep it cute and concise.

🌟 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, and 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. And if the divisor is zero (0), then the divisor is dependent on the category values in the neighborhood — see HOW THE FILTER WORKS below for the whole story.

🎀 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. (And 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 — icon behavior ngl.)

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. Slay pipeline. ✨

⚡ 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. So bestie, please 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: Saturday Jan 17 05:40:50 2026

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

© 2003-2025 GRASS Development Team, GRASS GIS 8.4.2 Reference Manual

and that's the whole page, no cap 💅 shoutout to GRASS 8.4.2 for holding it down, and shoutout to that Saturday Jan 17 05:40:50 2026 timestamp for being the moment someone actually read all this. r.mfilter(1), out. 🌈✨

📦 where this page comes from