v.geometry.py - GRASS manual

NAME

v.geometry.py - Prints geometry metrics of vector features.

KEYWORDS

SYNOPSIS

v.geometry.py

v.geometry.py --help

v.geometry.py map=name metric=string[,string,...] [type=string[,string,...]] [layer=string] [units=string[,string,...]] [nprocs=integer] [separator=character] format=name [--help] [--verbose] [--quiet] [--ui]

Flags:

--help: Print usage summary
--verbose: Verbose module output
--quiet: Quiet module output
--ui: Force launching GUI dialog

Parameters:

map=name [required]: Name of vector map; Or data source for direct OGR access
metric=string[,string,...] [required]: Geometry metric(s) to compute; Options: area, perimeter, length, count, compactness, fractal_dimension, slope, sinuosity, azimuth, coordinates, start, end, bbox; area: area size; perimeter: perimeter length of an area; length: line length; count: number of features for each category; compactness: compactness of an area, calculated as perimeter / (2 * sqrt(PI * area)); fractal_dimension: fractal dimension of boundary defining a polygon, calculated as 2 * (log(perimeter) / log(area)); slope: slope steepness of vector line or boundary; sinuosity: line sinuosity, calculated as line length / distance between end points; azimuth: line azimuth, calculated as angle between North direction and endnode direction at startnode; coordinates: point coordinates, X,Y or X,Y,Z; start: line/boundary starting point coordinates, X,Y or X,Y,Z; end: line/boundary end point coordinates, X,Y or X,Y,Z; bbox: bounding box of area, N,S,E,W
type=string[,string,...]: Input feature type; Options: point, line, boundary, centroid; Default: point,line,boundary,centroid
layer=string: Layer number or name; Vector features can have category values in different layers. This number determines which layer to use. When used with direct OGR access this is the layer name.; Default: 1
units=string[,string,...]: Units (one per metric, positional; unspecified metrics use defaults); Options: miles, feet, meters, kilometers, acres, hectares, radians, degrees
nprocs=integer: Number of threads for parallel computing; 0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs; Default: 0
separator=character: Field separator; Special characters: pipe, comma, space, tab, newline
format=name [required]: Output format; Options: plain, csv, json; Default: plain; plain: Plain text with pipe separator by default; csv: CSV (Comma Separated Values); json: JSON (JavaScript Object Notation)

DESCRIPTION
NOTES
EXAMPLES
SEE ALSO
AUTHORS

DESCRIPTION

v.geometry prints geometry metrics of vector features. Output is available as JSON, CSV, or plain text.

One or more metric values can be requested per invocation. When multiple metrics are given, they are computed in parallel and the results are merged by category. Supported metrics are:

area, perimeter, compactness, fractal_dimension, bbox - for areas (and boundaries that form areas)
length, slope, sinuosity, azimuth, start, end - for lines and boundaries
coordinates - for points and centroids
count - number of features per category

Values are aggregated per category.

Measures of lengths and areas are reported in meters by default; use the units option to change this.

NOTES

v.geometry is a read-only front-end to v.to.db and accepts the same set of units. It does not read from or write to the attribute table, so no table needs to be attached to the input map.

For writing metrics back into an attribute table, use v.to.db directly. Features of v.to.db that are not purely geometric, such as cross-layer attribute queries (option=query), are intentionally not exposed here.

Records are keyed by category. When multiple metrics are requested, the values for each category are merged into one record. If a category is shared across features of different types (for example a line and an area with the same cat), their metrics would end up in the same record even though they describe different features. To avoid this, v.geometry rejects combinations of metrics that belong to different feature-type families (area, line, point); the count metric is universal and can be combined with any of them. Run v.geometry separately for each feature type if you need metrics from more than one family.

When count is combined with another metric (for example metric=area,count), the count is aligned to the categories covered by that metric. Categories that only appear in the count result are dropped so every merged record carries both values, and the reported count total reflects only the aligned features.

EXAMPLES

Report area sizes of geology polygons in hectares:

v.geometry map=geology metric=area units=hectares

Compute area, perimeter, and compactness in a single call:

v.geometry map=geology metric=area,perimeter,compactness

Consume metrics from Python:

import grass.script as gs

data = gs.parse_command("v.geometry", map="geology", metric="compactness")
for record in data["records"]:
    print(record["category"], record["compactness"])

AUTHORS

Anna Petrasova, NCSU GeoForAll Laboratory

SOURCE CODE

Available at: v.geometry source code (history)

Latest change: Tuesday Jul 14 09:37:43 2026 in commit: 3e84f7cf1a9f4ea2cca9be853a0028ffecd86ee0