v.geometry

Prints geometry metrics of vector features.

Command linePython (grass.tools)Python (grass.script)

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

Example:

v.geometry map=name metric=area format=plain

grass.tools.Tools.v_geometry(map, metric, type="point,line,boundary,centroid", layer="1", units=None, nprocs=0, separator=None, format="plain", verbose=None, quiet=None, superquiet=None)

Example:

tools = Tools()
tools.v_geometry(map="name", metric="area", format="json")

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

grass.script.parse_command("v.geometry", map, metric, type="point,line,boundary,centroid", layer="1", units=None, nprocs=0, separator=None, format="plain", verbose=None, quiet=None, superquiet=None)

Example:

gs.parse_command("v.geometry", map="name", metric="area", format="json")

Parameters

Command linePython (grass.tools)Python (grass.script)

map=name [required]
    Name of vector map
    Or data source for direct OGR access
metric=string [,string,...] [required]
    Geometry metric(s) to compute
    Allowed values: 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
    Allowed values: 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)
    Allowed values: 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
    Allowed values: plain, csv, json
    Default: plain
    plain: Plain text with pipe separator by default
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
--help
    Print usage summary
--verbose
    Verbose module output
--quiet
    Quiet module output
--qq
    Very quiet module output
--ui
    Force launching GUI dialog

map : str, required
    Name of vector map
    Or data source for direct OGR access
    Used as: input, vector, name
metric : str | list[str], required
    Geometry metric(s) to compute
    Allowed values: 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 : str | list[str], optional
    Input feature type
    Allowed values: point, line, boundary, centroid
    Default: point,line,boundary,centroid
layer : str, optional
    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.
    Used as: input, layer
    Default: 1
units : str | list[str], optional
    Units (one per metric, positional; unspecified metrics use defaults)
    Allowed values: miles, feet, meters, kilometers, acres, hectares, radians, degrees
nprocs : int, optional
    Number of threads for parallel computing
    0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
    Default: 0
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
format : str, required
    Output format
    Used as: name
    Allowed values: plain, csv, json
    plain: Plain text with pipe separator by default
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
    Default: plain
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

Returns:

result : grass.tools.support.ToolResult | None
If the tool produces text as standard output, a ToolResult object will be returned. Otherwise, None will be returned.

Raises:

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

map : str, required
    Name of vector map
    Or data source for direct OGR access
    Used as: input, vector, name
metric : str | list[str], required
    Geometry metric(s) to compute
    Allowed values: 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 : str | list[str], optional
    Input feature type
    Allowed values: point, line, boundary, centroid
    Default: point,line,boundary,centroid
layer : str, optional
    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.
    Used as: input, layer
    Default: 1
units : str | list[str], optional
    Units (one per metric, positional; unspecified metrics use defaults)
    Allowed values: miles, feet, meters, kilometers, acres, hectares, radians, degrees
nprocs : int, optional
    Number of threads for parallel computing
    0: use OpenMP default; >0: use nprocs; <0: use MAX-nprocs
    Default: 0
separator : str, optional
    Field separator
    Special characters: pipe, comma, space, tab, newline
    Used as: input, separator, character
format : str, required
    Output format
    Used as: name
    Allowed values: plain, csv, json
    plain: Plain text with pipe separator by default
    csv: CSV (Comma Separated Values)
    json: JSON (JavaScript Object Notation)
    Default: plain
verbose : bool, optional
    Verbose module output
    Default: None
quiet : bool, optional
    Quiet module output
    Default: None
superquiet : bool, optional
    Very quiet module output
    Default: None

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:

Python (grass.script)Python (grass.tools)

import grass.script as gs

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

from grass.tools import Tools

data = Tools().v_geometry(map="geology", metric="compactness", format="json")
for record in data["records"]:
    print(record["category"], record["compactness"])

Sample JSON output for metric=length:

{
    "units": {
        "length": "meters"
    },
    "totals": {
        "length": 10426.657857419743
    },
    "records": [
        {
            "category": 1,
            "length": 4554.943058982206
        },
        {
            "category": 2,
            "length": 5871.714798437538
        }
    ]
}

SEE ALSO

r.object.geometry, v.category, v.db.join, v.report, v.to.db, v.univar

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 3e84f7c