v.distance(1grass)

📦
version 8.5.0 · 10 versions
, in alpine 3.24, ubuntu stonking

💖 v.distance — GRASS User's Manual 💖

okay bestie, sit down, hydrate, because this is the one that finds your nearest everything. this is v.distance(1grass) and she is that girl.

🌸 NAME 🌸

v.distance — finds the nearest element in vector map 'to' for elements in vector map 'from'. literally the matchmaker of vector maps. 🫶

✨ KEYWORDS ✨

vector, distance, database, attribute table

🎀 SYNOPSIS 🎀

v.distance
v.distance --help
v.distance [-pas] from=name  [from_layer=string]
[from_type=string[,string,...]]  to=name  [to_layer=string]
[to_type=string[,string,...]]   [output=name]   [dmax=float]
[dmin=float]  upload=string[,string,...]  [column=name[,name,...]]
[to_column=name]   [table=name]   [separator=character]  format=name
[--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

🦋 Flags 🦋

  • -p — prints the output to stdout and does not update the attribute table. the first column is always the category of the 'from' feature, and it's called from_cat. no cap.
  • -a — calculates distances to all features that fall within the threshold. you can write that output to stdout with the -p flag, or upload it into a brand new table created by the table option. also, you can stack multiple upload options. multiple. obsessed.
  • -s — prints the output as a square matrix (this is only possible for one single upload variable, so pick your fave 💅)
  • --overwrite — lets output files overwrite existing files
  • --help — prints the usage summary
  • --verbose — verbose module output
  • --quiet — quiet module output
  • --ui — forces the GUI dialog to launch

🌈 Parameters 🌈

  • from=name [required] — name of the existing vector map (from). or, plot twist, it can be a data source for direct OGR access.
  • from_layer=string — layer number or name (from). vector features can have category values in different layers, and this number decides which layer gets used. when you're doing direct OGR access, this is the layer name instead. default: 1
  • from_type=string[,string,...] — feature type (from), aka the input feature type. options: point, line, boundary, centroid, area. default: point,line,area
  • to=name [required] — name of the existing vector map (to). or a data source for direct OGR access.
  • to_layer=string — layer number or name (to). same story as before: vector features can have category values in different layers, this number picks which layer to use, and with direct OGR access it's the layer name. default: 1
  • to_type=string[,string,...] — feature type (to), the input feature type. options: point, line, boundary, centroid, area. default: point,line,area
  • output=name — name for the output vector map holding the lines that connect the nearest elements
  • dmax=float — maximum distance, or -1 for no limit. units are map units, but meters for ll. default: -1
  • dmin=float — minimum distance, or -1 for no limit. map units, meters for ll. default: -1
  • upload=string[,string,...] [required] — values describing the relation between two nearest features. options: cat, dist, to_x, to_y, to_along, to_angle, to_attr
    • cat: category of the nearest feature
    • dist: minimum distance to nearest feature
    • to_x: x coordinate of the nearest point on the 'to' feature
    • to_y: y coordinate of the nearest point on the 'to' feature
    • to_along: distance to the nearest point on the 'to' feature along that linear feature
    • to_angle: angle along the nearest linear feature in the 'to' map, measured CCW from the +x axis, in radians, between -Pi and Pi inclusive
    • to_attr: attribute of nearest feature given by the to_column option
  • column=name[,name,...] — column name(s) where the values specified by the upload option get uploaded
  • to_column=name — column name of the nearest feature (used with upload=to_attr)
  • table=name — name for a new attribute table
  • separator=character — field separator for printing output to stdout. special characters: pipe, comma, space, tab, newline. default: pipe
  • format=name [required] — output format. options: plain, json. default: plain
    • plain: plain text output
    • json: JSON (JavaScript Object Notation)

💜 DESCRIPTION 💜

so what does she actually do. v.distance finds the nearest element in vector map (to) for elements in vector map (from). various deets about how those vectors relate — distance, category, etc. — can be uploaded to the attribute table attached to that first vector map, or printed straight to stdout. and she can make a whole new vector map where the lines connecting nearest points on features get written. use dmin and/or dmax to limit the search radius (and in lat-long projects you give those in meters, because they're calculated as geodesic distances on a sphere). 🧚

for lines to lines — say line A to line B — v.distance calculates the shortest distance of each vertex in A with each segment (not vertex) in B. then the module calculates the shortest distance of each vertex in B to each segment in A. and the overall shortest distance is the shortest of A-points-to-B-segments and B-points-to-A-segments. on top of that, v.distance checks for intersections. if there is an intersection, the first intersection found gets used and the distance gets set to zero. 💀

for lines to areas, the distance is set to zero if a line is (partially) inside an area. the first point of the line that's inside the area is used as the common point. and the distance is also set to zero if the line intersects with the outer ring or any of the inner rings (isles) — in that case the first intersection is used as the common point.

for areas to areas, the module first checks for overlap, or whether one area is (partially) inside the other. heads up: this is computationally quite intensive. 😭 if the outer rings of the two areas don't overlap, the distance gets calculated the same way as lines to lines above, treating the outer rings as two lines. again, the first point that falls into an area is used as the common point, or the first intersection point.

for anything that isn't points to lines, there can be several common locations with zero distance, and that common location would then be the result of an overlay made of several points, lines, or areas. in these cases v.distance selects a single point, and does not create an overlay like v.overlay does. in this implementation, any shared point is as good as any other. calculating an intersection is costlier than checking if a vertex is inside a polygon — so for example, if a vertex of the boundary of the 'to' area is inside the 'from' area, that's a common location. and for speed reasons, the distance is then set to zero and no further tests are done. periodt. ⭐

🔥 NOTES 🔥

  • if a nearest feature doesn't have a category, the attribute column gets updated to NULL.
  • the upload column(s) must already exist. make one with v.db.addcolumn. (no skipping this step bestie, she will not make it for you 🙈)
  • in lat-long projects, v.distance gives distances (dist, from_along, and to_along) not in degrees but in meters, calculated as geodesic distances on a sphere.
  • if one or both of the input vector maps are 3D, the user gets notified accordingly. 👑
  • the -p flag prints the results to standard output. by default the output is in the form of a linear matrix. if only one variable is uploaded and you want a square matrix, you can set the -s flag.

✨ EXAMPLES ✨

bestie these are the recipes, the actual vibes in practice, let's go 💅

🔍 Find nearest lines

Find nearest lines in vector map "ln" for points from vector map "pnt" within the given threshold and write related line categories to column "linecat" in an attribute table attached to vector map "pnt":

v.distance from=pnt to=ln upload=cat column=linecat

🎯 Find nearest area

For each point from vector map "pnt", find the nearest area from map "ar" within the given threshold and write the related area categories to column "areacat" in an attribute table attached to vector map "pnt" (in the case that a point falls into an area, the distance is zero):

v.distance from=pnt to=ar upload=cat column=areacat

🦋 Create a new vector map

Create a new vector map which contains lines connecting nearest features of maps "pnt" and map "ln". The resulting vector map can be used for example to connect points to a network as needed for network analysis:

v.distance from=pnt to=ln out=connections upload=dist column=dist

🌸 Create a new vector map with from and to categories in the attribute table

Create a new vector map that contains lines connecting nearest features of maps "pnt" and map "ln", and a new attribute table that contains distances, from and to categories from the input maps:

v.distance from=pnt to=ln out=connections upload=cat,dist column=to_cat,dist table=connections

🫶 Query information

Query information from selected point(s). v.distance takes points from a vector map as input instead of stdin. A new vector map with query points has to be created before the map can be analysed.

Create query map (if not present):

echo "123456|654321|1" | v.in.ascii output=pnt

Find nearest features:

v.distance -p from=pnt to=map_to_query upload=cat

💜 Point-in-polygon

The option dmax=0 is here important because otherwise for points not falling into any area, the category of the nearest area is recorded. For each point from vector map "pnt", find the area from vector map "ar" in which the individual point falls, and write the related area categories to column "areacat" into the attribute table attached to vector map "pnt":

v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
no cap, that dmax=0 is doing SO much heavy lifting here. forget it and your not-in-any-area points get matched to the nearest area anyway 😭

📊 Univariate statistics on results

Create a vector map containing connecting lines and investigate mean distance to targets. An alternative solution is to use the v.distance upload=dist option to upload distances into the bugs vector directly, then run v.univar on that. Also note you can upload two columns at a time, e.g. v.distance upload=cat,dist column=nearest_id,dist_to_nr.

# create working copy
g.copy vect=bugsites,bugs
# add new attribute column to hold nearest archsite category number
v.db.addcolumn map=bugs column="nrst_arch INTEGER"
v.distance from=bugs to=archsites to_type=point upload=to_attr \
  to_column=cat column=nrst_arch out=vdistance_vectors_raw
# we need to give the lines category numbers, create a table, and create
#  a column in that table to hold the distance data.
v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
g.remove -f type=vector name=vdistance_vectors_raw
v.db.addtable map=vdistance_vectors column="length DOUBLE"
v.to.db map=vdistance_vectors option=length column=length
# calculate statistics
v.univar vdistance_vectors column=length

Example for a Latitude-longitude project (EPSG 4326):

# points along the equator
echo "0|-61|1" | v.in.ascii output=pnt1 input=-
echo "0|-58|1" | v.in.ascii output=pnt2 input=-
# here, distances are in degree units
v.distance -p --q from=pnt1 to=pnt2 upload=dist
from_cat|distance
1|3

North Carolina sample data 🎀

As linear matrix:

v.distance -pa from=hospitals to=hospitals upload=dist,to_attr to_column=NAME separator=tab
from_cat    to_cat  dist    to_attr
1   1   0   Cherry Hospital
1   2   7489.1043632983983  Wayne Memorial Hospital
1   3   339112.17046729225  Watauga Medical Center
1   4   70900.392145909267  Central Prison Hospital
1   5   70406.227393921712  Dorothea Dix Hospital

As square matrix (only possible with single upload option):

v.distance -pas from=hospitals to=hospitals upload=dist separator=tab
from_cat to_cat       dist
              1          2          3          4          5 ...
1             0    7489.10  339112.17   70900.39   70406.23 ...
2       7489.10          0  345749.12   76025.46   75538.87 ...
3     339112.17  345749.12          0  274153.19  274558.98 ...
4      70900.39   76025.46  274153.19          0     501.11 ...
5      70406.23   75538.87  274558.98     501.11          0 ...
...
v.distance -p from=busroute_a to=busstopsall upload=dist,to_attr to_column=routes format=json
[
    {
        "from_cat": 1,
        "to_cat": 112,
        "distances": [
            {
                "value": 0.1428123184481199,
                "name": "dist"
            },
            {
                "value": "8,A",
                "name": "to_attr"
            }
        ]
    },
    {
        "from_cat": 2,
        "to_cat": 44,
        "distances": [
            {
                "value": 0.10232660032693719,
                "name": "dist"
            },
            {
                "value": "9,A",
                "name": "to_attr"
            }
        ]
    }
]

👀 SEE ALSO 👀

you'll wanna hang out with these too, they're the friend group fr fr:

  • r.distance
  • v.db.addcolumn
  • v.what.vect

💖 AUTHORS 💖

the absolute icons who built this, in order of legend status:

  • Janne Soimasuo 1994, University of Joensuu, Faculty of Forestry, Finland
  • Cmd line coordinates support: Markus Neteler, ITC-irst, Trento, Italy
  • Updated for 5.1: Radim Blazek, ITC-irst, Trento, Italy
  • Matrix-like output by Martin Landa, FBK-irst, Trento, Italy
  • Improved processing speed: Markus Metz
  • Distance from any feature to any feature: Markus Metz
  • New table without the -p flag: Huidae Cho Make linear matrix the default for all outputs: Moritz Lennert

🔥 SOURCE CODE 🔥

Available at: v.distance source code (history)

Latest change: Saturday Oct 11 04:38:40 2025 in commit: 3dd71f5fab83b72a2db2da959fe075c5b3b52200

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

okay that's the whole page bestie, you made it 🫶 this was GRASS 8.5.0 and the page is v.distance(1grass), docs © 2003-2026 GRASS Development Team (GRASS 8.5.0 Reference Manual) — and that last little glow-up landed Saturday Oct 11 04:38:40 2025 in commit 3dd71f5fab83b72a2db2da959fe075c5b3b52200. go measure something. slay 💅✨

📦 where this page comes from