v.net.distance(1grass)

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

💖 v.net.distance 💖

okay bestie, welcome to v.net.distance — that's the GRASS manual page, and she is a whole vibe. short queen, big job: she finds the shortest paths through a network from every point in one set to the nearest feature in another set, and then dumps a bunch of juicy info about that relationship into an attribute table. no cap. 🦋

🌈 KEYWORDS 🌈

vector, network, shortest path

✨ SYNOPSIS ✨

v.net.distance
v.net.distance --help
v.net.distance [-gl] input=name output=name  [arc_layer=string]
[arc_type=string[,string,...]]   [node_layer=string]
[from_layer=string]   [from_cats=range]   [from_where=sql_query]
[to_layer=string]   [to_type=string[,string,...]]   [to_cats=range]
[to_where=sql_query]   [arc_column=name]   [arc_backward_column=name]
[node_column=name]   [--overwrite]  [--help]  [--verbose]  [--quiet]
[--ui]

🎀 Flags

  • -g — use a geodesic calculation for longitude-latitude projects 💫
  • -l — write every output path as one single line, instead of as the original input segments. the way that this makes each path its own glow-up line ✨
  • --overwrite — let output files overwrite existing files, yes ma'am, permission granted 💅
  • --help — print the usage summary, for when you're lost (iykyk)
  • --verbose — verbose module output, she's chatty and we love that
  • --quiet — quiet module output, she's giving mysterious
  • --ui — force launching the GUI dialog, clicky-clicky era 🖱️

🌸 Parameters

  • input=name [required] — name of input vector map. or a data source for direct OGR access, fancy 💜
  • output=name [required] — name for the output vector map
  • arc_layer=string — arc layer. vector features can have category values in different layers, and this number decides which layer to use. when you're doing direct OGR access, this is the layer name instead. Default: 1
  • arc_type=string[,string,...] — arc type, aka the input feature type. Options: line, boundary. Default: line,boundary
  • node_layer=string — node layer. same layer deal as before: the number picks the layer, and with direct OGR access it's the layer name. Default: 2
  • from_layer=string — from layer number or name. vector features can have category values in different layers, and this number says which one. with direct OGR access, it's the layer name. Default: 1
  • from_cats=range — from category values. Example: 1,3,7-9,13
  • from_where=sql_query — from WHERE conditions of an SQL statement, without the where keyword. Example: income < 1000 and population >= 10000
  • to_layer=string — layer number or name. to layer number or name. Default: 1
  • to_type=string[,string,...] — to feature type. Options: point, line, boundary. Default: point
  • to_cats=range — to category values. Example: 1,3,7-9,13
  • to_where=sql_query — to WHERE conditions of an SQL statement, without the where keyword. Example: income < 1000 and population >= 10000
  • arc_column=name — arc forward/both direction(s) cost column (number) 💸
  • arc_backward_column=name — arc backward direction cost column (number) 💸
  • node_column=name — node cost column (number) 💸

👑 DESCRIPTION 👑

v.net.distance finds the nearest element in set to for every point in set from. she's a matchmaker, fr fr. 🫶

💅 NOTES 💅

These two sets are given by their respective layer, where and cats parameters. The type of the to features is decided by the to_type parameter. All from features are points, periodt.

A table gets linked to the output map holding all the tea about the relation. More specifically, the table has three columns: cat, tcat and dist, storing the category of each from feature, the category of the nearest to feature, and the distance between them, respectively. iconic trio honestly ✨

And furthermore? The output map contains the shortest path between each cat, tcat pair. Each path is made of several lines. If a line is on the shortest path from a point, then the category of that point gets assigned to the line. Heads up though: every line may hold more than one category value, because a single line can be on the shortest path for more than one from feature. Which is actually super convenient — you can grab the shortest paths by simply querying lines with the corresponding category number. Or, if you want unique paths, use the -l flag and each path becomes its own separate single line in the output. main character energy 🌟

The costs of arcs in the forward and backward direction are set by the arc_column and arc_backward_column columns respectively. If arc_backward_column isn't given, the same cost gets used in both directions. equal treatment, slay. 💖

⚠️ okay so this is important bestie: v.net.distance will not work if you're trying to find the nearest neighbors within a group of nodes — like when to and from are the same set of nodes. because the closest node will be the node itself, and the result will be zero-length paths. 😭 if you need nearest neighbors within a group of nodes, you've got two options: loop through each node as to and all other nodes as from, OR build a complete distance matrix with v.net.allpairs and pick the lowest non-zero distance for each node. no zero-length shenanigans allowed.

🍓 EXAMPLES 🍓

💜 Shortest path and distance between school and nearest hospital

Find the shortest path and distance from every school to the nearest hospital, and show all the paths.

Streets are grey lines, schools are green circles, hospitals are red crosses, and the shortest paths are blue lines — it's giving art direction 🎨

# connect schools to streets as layer 2
v.net input=streets_wake points=schools_wake output=streets_net1 \
      operation=connect thresh=400 arc_layer=1 node_layer=2
# connect hospitals to streets as layer 3
v.net input=streets_net1 points=hospitals output=streets_net2 \
      operation=connect thresh=400 arc_layer=1 node_layer=3
# inspect the result
v.category in=streets_net2 op=report
# shortest paths from schools (points in layer 2) to nearest hospitals (points in layer 3)
v.net.distance in=streets_net2 out=schools_to_hospitals flayer=2 to_layer=3
# visualization
g.region vector=streets_wake
d.mon wx0
d.vect streets_wake color=220:220:220
d.vect schools_wake color=green size=10
d.vect map=hospitals icon=basic/cross3 size=15 color=black fcolor=red
d.vect schools_to_hospitals

🦋 Distance between point source of pollution and sample points along streams

Example with streams of the NC sample data set. 🌊

# add coordinates of pollution point source of pollution as vector
pollution.txt:
634731.563206905|216390.501834892
v.in.ascii input=pollution.txt output=pollution
# add table to vector
v.db.addtable map=pollution
# add coordinates of sample points as vector
samples.txt:
634813.332814905|216333.590706166
634893.462007813|216273.763350851
634918.660011082|216254.949609689
v.in.ascii input=samples.txt output=samples
# add table to vector
v.db.addtable map=samples
# connect samples and pollution to streams
v.net -c input=streams points=samples output=streams_samples \
         operation=connect node_layer=3 threshold=10 \
v.net -c input=streams_samples points=pollution
         output=streams_samples_pollution operation=connect \
         node_layer=4 threshold=10
# check vector layers
v.category input=streams_samples_pollution option=report
Layer/table: 1/streams_samples_pollution
type       count        min        max
point          0          0          0
line        8562      40102     101351
boundary       0          0          0
centroid       0          0          0
area           0          0          0
face           0          0          0
kernel         0          0          0
all         8562      40102     101351
Layer: 3
type       count        min        max
point          3          1          3
line           0          0          0
boundary       0          0          0
centroid       0          0          0
area           0          0          0
face           0          0          0
kernel         0          0          0
all            3          1          3
Layer: 4
type       count        min        max
point          1          1          1
line           0          0          0
boundary       0          0          0
centroid       0          0          0
area           0          0          0
face           0          0          0
kernel         0          0          0
all            1          1          1
# calculate distance between sample points and pollution point source
v.net.distance input=streams_samples_pollution \
      output=distance_samples_to_pollution from_layer=3 to_layer=4
# check results
v.report map=distance_samples_to_pollution@vnettest option=length
cat|tcat|dist|length
1|1|100.0|100.0
2|1|200.0|200.0
3|1|231.446|231.446

🌟 SEE ALSO 🌟

v.net.path, v.net.allpairs, v.net.distance, v.net.alloc

🎀 AUTHORS 🎀

  • Daniel Bundala, Google Summer of Code 2009, Student
  • Wolf Bergenheim, Mentor
  • Markus Metz

🔥 SOURCE CODE 🔥

Available at: v.net.distance source code (history)

Latest change: Friday May 09 14:33:40 2025 in commit: b356c7e108fcbeca77474c8e83ebec8f1e7b3e4a

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

and that's the whole page bestie, we ate and left absolutely no crumbs 💅✨ this was GRASS 8.5.0, © 2003-2026 GRASS Development Team, with the latest little glow-up landing Friday May 09 14:33:40 2025. go compute some shortest paths, you've got this 🫶💖🌈

📦 where this page comes from