r.neighborhoodmatrix

Calculates geometry parameters for raster objects.

r.neighborhoodmatrix [-dlc] input=name [output=name] [separator=character] [--overwrite] [--verbose] [--quiet] [--qq] [--ui]

Example:

r.neighborhoodmatrix input=name

grass.script.run_command("r.neighborhoodmatrix", input, output=None, separator="pipe", flags=None, overwrite=False, verbose=False, quiet=False, superquiet=False)

Example:

gs.run_command("r.neighborhoodmatrix", input="name")

Parameters

Command linePython (grass.script)

input=name [required]
    Raster for which to calculate the neighboorhood matrix
output=name
    Name for output file
separator=character
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Default: pipe
-d
    Also take into account diagonal neighbors
-l
    Also output length of common border (in pixels)
-c
    Include column names in output (meaning will be inversed soon)
--overwrite
    Allow output files to overwrite existing files
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

input : str, required
    Raster for which to calculate the neighboorhood matrix
    Used as: input, raster, name
output : str, optional
    Name for output file
    Used as: output, file, name
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
    Default: pipe
flags : str, optional
    Allowed values: d, l, c
    d
        Also take into account diagonal neighbors
    l
        Also output length of common border (in pixels)
    c
        Include column names in output (meaning will be inversed soon)
overwrite: bool, optional
    Allow output files to overwrite existing files
    Default: False
verbose: bool, optional
    Verbose module output
    Default: False
quiet: bool, optional
    Quiet module output
    Default: False
superquiet: bool, optional
    Very quiet module output
    Default: False

DESCRIPTION

r.neighborhoodmatrix identifies all adjacency relations between objects (aka segments or clumps identified by identical integer cell values of adjacent pixels) in a raster map and exports these as a 2xn matrix where n is the number of neighborhood relations with each relation listed in both directions (i.e. if a is neighbor of b, the list will contain a,b and b,a). If a path to an output file is specified, the matrix will be written to that file, otherwise it will be sent to standard output.

Neighborhood relations are determined pixel by pixel, and by default only pixels that share a common pixel boundary are considered neighbors. When the -d flag is set pixels sharing a common corner (i.e. diagonal neighbors) are also taken into account.

When the -l flag is set, the module additionally indicates the length of the common border between two neighbors in number of pixels. As this length is not clearly defined for diagonal neighbors, the -l flag cannot be used in combination with the -d flag.

The -c flag currently adds column headers. Please note that this flag's meaning will be inversed when GRASS 8 comes out in order to harmonize its behaviour with that in other modules.

NOTES

As neighborhood length is measured in pixels, this length is not in proportion to length in map units if the location is a lat-long location, or if the resolution is not the same in East-West and in North-South direction (rectangular pixels).

The module respects the region settings, so if the raster map is outside the current computational region, the resulting list of neighbors will be empty.

TODO

Add flag to only output half matrix with each relation only shown once.
Measure neighbordhood length in map units, not only pixels

EXAMPLE

Start by making sure the input map is of type CELL:

r.mapcalc "bc_int = int(boundary_county_500m)"

Send the neighborhood matrix of the counties in the boundary_county map of the North Carolina dataset to standard output:

r.neighborhoodmatrix in=bc_int sep=comma

Idem, but also calculating neighborhood length, sending the output to a file:

r.neighborhoodmatrix -l n=bc_int sep=comma output=county_neighbors.csv

AUTHORS

Original Python-Version: Moritz Lennert
C-Version: Markus Metz

SOURCE CODE

Available at: r.neighborhoodmatrix source code (history)
Latest change: Friday Feb 21 10:10:05 2025 in commit 7d78fe3