GRASS logo

NAME

r.neighborhoodmatrix - Calculates a neighborhood matrix for a raster map with regions

KEYWORDS

raster, neighboorhood, regions

SYNOPSIS

r.neighborhoodmatrix
r.neighborhoodmatrix --help
r.neighborhoodmatrix [-dl] input=name output=name [separator=character] [processes=integer] [--overwrite] [--help] [--verbose] [--quiet] [--ui]

Flags:

-d
Also take into account diagonal neighbors
-l
Also output length of common border (in pixels)
--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]
Raster for which to calculate the neighboorhood matrix
output=name [required]
Name for output file (- for standard output)
Default: -
separator=character
Field separator
Special characters: pipe, comma, space, tab, newline
Default: pipe
processes=integer
Number of processes to run in parallel (for multiple rasters)
Default: 1

Table of contents

DESCRIPTION

r.neighborhoodmatrix identifies all adjacency relations between objects (aka segments or clumps) 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.

In order to speed up calculations, the user can set the parameter processes to the number of desired processes to run in parallel. As the module parallelizes per direction, the maximum number of processes is 4 without and 8 with the -d flag.

NOTES

The module (without the -d flag) should give the same result as the equivalent call to v.neighborhoodmatrix with the -b flag. Currently it actually seems faster for some maps to transform the raster to vector and then run the latter. More tests are needed, though, to confirm this.

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

TODO

EXAMPLE

Send the neighborhood matrix of the counties in the boundary_county map of the North Carolina dataset to standard output:
r.neighborhoodmatrix in=boundary_county_500m sep=comma
Idem, but also calculating neighborhood length, sending the output to a file and using 4 parallel processes:
r.neighborhoodmatrix -l n=boundary_county_500m sep=comma \
	output=county_neighbors.csv processes=4
Transforming the raster to vector (without attribute table or topology) and using v.neighborhoodmatrix:
r.to.vect -tbv in=boundary_county_500m out=boundary_county_500m type=area
v.neighborhoodmatrix in=boundary_county_500m sep=comma

SEE ALSO

v.neighborhoodmatrix

AUTHOR

Moritz Lennert

Last changed: $Date: 2017-11-20 12:49:09 +0100 (Mon, 20 Nov 2017) $

SOURCE CODE

Available at: r.neighborhoodmatrix source code (history)


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

© 2003-2017 GRASS Development Team, GRASS GIS 7.2.3svn Reference Manual