---
name: r.clump
description: Recategorizes data in a raster map by grouping cells that form physically discrete areas into unique categories.
keywords: [ raster, statistics, reclass, clumps ]
---

# r.clump

Recategorizes data in a raster map by grouping cells that form physically discrete areas into unique categories.

=== "Command line"

    **r.clump**
    [**-dg**]
    **input**=*name* [,*name*,...]
    [**output**=*name*]
    [**title**=*string*]
    [**threshold**=*float*]
    [**minsize**=*integer*]
    [**--overwrite**]
    [**--verbose**]
    [**--quiet**]
    [**--qq**]
    [**--ui**]

    Example:

    ```sh
    r.clump input=name output=name
    ```

=== "Python (grass.tools)"

    *grass.tools.Tools.r_clump*(**input**,
        **output**=*None*,
        **title**=*None*,
        **threshold**=*0*,
        **minsize**=*1*,
        **flags**=*None*,
        **overwrite**=*None*,
        **verbose**=*None*,
        **quiet**=*None*,
        **superquiet**=*None*)

    Example:

    ```python
    tools = Tools()
    tools.r_clump(input="name", output="name")
    ```

    This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

=== "Python (grass.script)"

    *grass.script.run_command*("***r.clump***",
        **input**,
        **output**=*None*,
        **title**=*None*,
        **threshold**=*0*,
        **minsize**=*1*,
        **flags**=*None*,
        **overwrite**=*None*,
        **verbose**=*None*,
        **quiet**=*None*,
        **superquiet**=*None*)

    Example:

    ```python
    gs.run_command("r.clump", input="name", output="name")
    ```

## Parameters

=== "Command line"

    **input**=*name* [,*name*,...] **[required]**  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of input raster map(s)  
    **output**=*name*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output raster map  
    **title**=*string*  
    &nbsp;&nbsp;&nbsp;&nbsp;Title for output raster map  
    **threshold**=*float*  
    &nbsp;&nbsp;&nbsp;&nbsp;Threshold to identify similar cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Valid range: 0 = identical to &lt; 1 = maximal difference  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **minsize**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Minimum clump size in cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Clumps smaller than minsize will be merged to form larger clumps  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *1*  
    **-d**  
    &nbsp;&nbsp;&nbsp;&nbsp;Clump also diagonal cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Clumps are also traced along diagonal neighboring cells  
    **-g**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print only the number of clumps in shell script style  
  
    **--overwrite**  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    **--help**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print usage summary  
    **--verbose**  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    **--quiet**  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    **--qq**  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    **--ui**  
    &nbsp;&nbsp;&nbsp;&nbsp;Force launching GUI dialog

=== "Python (grass.tools)"

    **input** : str | list[str], *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of input raster map(s)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **output** : str | type(np.ndarray) | type(np.array) | type(gs.array.array), *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output raster map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, raster, *name*  
    **title** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Title for output raster map  
    **threshold** : float, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Threshold to identify similar cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Valid range: 0 = identical to &lt; 1 = maximal difference  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **minsize** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Minimum clump size in cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Clumps smaller than minsize will be merged to form larger clumps  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *1*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *d*, *g*  
    &nbsp;&nbsp;&nbsp;&nbsp;**d**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Clump also diagonal cells  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Clumps are also traced along diagonal neighboring cells  
    &nbsp;&nbsp;&nbsp;&nbsp;**g**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print only the number of clumps in shell script style  
  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  

    Returns:

    **result** : grass.tools.support.ToolResult | np.ndarray | tuple[np.ndarray] | None  
    If the tool produces text as standard output, a *ToolResult* object will be returned. Otherwise, `None` will be returned. If an array type (e.g., *np.ndarray*) is used for one of the raster outputs, the result will be an array and will have the shape corresponding to the computational region. If an array type is used for more than one raster output, the result will be a tuple of arrays.

    Raises:

    *grass.tools.ToolError*: When the tool ended with an error.

=== "Python (grass.script)"

    **input** : str | list[str], *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of input raster map(s)  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, raster, *name*  
    **output** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output raster map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, raster, *name*  
    **title** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Title for output raster map  
    **threshold** : float, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Threshold to identify similar cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Valid range: 0 = identical to &lt; 1 = maximal difference  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **minsize** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Minimum clump size in cells  
    &nbsp;&nbsp;&nbsp;&nbsp;Clumps smaller than minsize will be merged to form larger clumps  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *1*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *d*, *g*  
    &nbsp;&nbsp;&nbsp;&nbsp;**d**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Clump also diagonal cells  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Clumps are also traced along diagonal neighboring cells  
    &nbsp;&nbsp;&nbsp;&nbsp;**g**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Print only the number of clumps in shell script style  
  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*

## DESCRIPTION

*r.clump* finds all areas of contiguous cell category values (connected
components) in the input raster map. NULL values in the input are
ignored. It assigns a unique category value to each such area ("clump")
in the resulting output raster map.

Category distinctions in the input raster map are preserved. This means
that if distinct category values are adjacent, they will NOT be clumped
together. The user can run *[r.reclass](r.reclass.md)* prior to
*r.clump* to recategorize cells and reassign cell category values.

*r.clump* can also perform "fuzzy" clumping where neighboring cells that
are not identical but similar to each other are clumped together. Here,
the spectral distance between two cells is scaled to the range \[0, 1\]
and compared to the *threshold* value. Cells are clumped together if
their spectral distance is ≤ *threshold*. The result is very sensitive
to this *threshold* value, a recommended start value is 0.01, then
increasing or decreasing this value according to the desired output.
Once a suitable threshold has been determined, noise can be reduced by
merging small clumps with the *minsize* option.

*r.clump* can also use multiple raster maps of any kind (CELL, FCELL,
DCELL) as input. In this case, the spectral distance between cells is
used to determine the similarity of two cells. This means that input
maps must be metric: the difference cell 1 - cell 2 must make sense.
Categorical maps, e.g. land cover, can not be used in this case.
Examples for valid input maps are satellite imagery, vegetation indices,
elevation, climatic parameters etc.

## NOTES

By default, the resulting clumps are connected only by their four direct
neighbors (left, right, top, bottom). The *-d* flag activates also
diagonal clump tracing.

*r.clump* works properly with raster map that contains only "fat" areas
(more than a single cell in width). Linear elements (lines that are a
single cell wide) may or may not be clumped together depending on the
direction of the line - horizontal and vertical lines of cells are
considered to be contiguous, but diagonal lines of cells are not
considered to be contiguous and are broken up into separate clumps
unless the *-d* flag is used.

A random color table and other support files are generated for the
output raster map.

## EXAMPLES

### Clumping of a raster map

Perform clumping on "lakes" map (North Carolina sample dataset) and
report area sizes for each lake individually rather by waterbody type:

```sh
g.region raster=lakes -p

# report sizes by waterbody type
r.report lakes units=h

# clump per raster polygon
r.clump lakes out=lakes_individual

# report sizes by individual waterbody
r.report lakes_individual units=h
```

![r.clump lake clumping example](r_clump_lakes.png)  
*Figure: Clumping of rasterized lakes: original lakes map (left) and
clumped lakes map (right)*

### Fuzzy clumping on Landsat bands

Perform fuzzy clumping on Landsat 7 2002 imagery (North Carolina sample
dataset)

```sh
g.region raster=lsat7_2002_10 -p
r.clump in=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 \
        out=lsat7_2002_clump threshold=0.045

# reduce noise
r.clump in=lsat7_2002_10,lsat7_2002_20,lsat7_2002_30,lsat7_2002_40,lsat7_2002_50,lsat7_2002_70 \
        out=lsat7_2002_clump_min10 threshold=0.045 minsize=10
```

![r.clump example Landsat fuzzy clumping](r_clump_lsat.png)  
*Figure: Fuzzy clumping on Landsat bands: original RGB composite (left),
fuzzy clumped map (middle), and fuzzy clumped with minsize map (right)*

## SEE ALSO

*[r.buffer](r.buffer.md), [r.distance](r.distance.md),
[r.grow](r.grow.md), [r.mapcalc](r.mapcalc.md),
[r.mfilter](r.mfilter.md), [r.neighbors](r.neighbors.md),
[r.to.vect](r.to.vect.md), [r.reclass](r.reclass.md),
[r.statistics](r.statistics.md), [r.support](r.support.md)*

## AUTHORS

Michael Shapiro, U.S. Army Construction Engineering Research
Laboratory  
Markus Metz (diagonal clump tracing, fuzzy clumping)

## SOURCE CODE

Available at: [r.clump source code](https://github.com/OSGeo/grass/tree/main/raster/r.clump)
([history](https://github.com/OSGeo/grass/commits/main/raster/r.clump))  
Latest change: Saturday Oct 25 22:50:58 2025 in commit [ee87f21](https://github.com/OSGeo/grass/commit/ee87f21833475fd40805f58d1702f7d64478a27b)
