v.net.distance(1)

📦
version 8.4.2 · 8 versions
, in fedora 44

v.net.distance 💖 (that's the v.net.distance(1) manual page, bestie — GRASS GIS User's Manual energy)

okay so. listen. you want the shortest path through a network between two sets of features? this is the module. it computes shortest distance via the network between the given sets of features, finds the shortest paths from each 'from' point to the nearest 'to' feature, and then uploads various info about that whole relationship into the attribute table. slay.

✨ 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 geodesic calculation for longitude-latitude projects
  • -l — write each output path as one line, not as original input segments.
  • --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] — name of input vector map. or like, a data source for direct OGR access, that works too.
  • output=name [required] — name for output vector map
  • arc_layer=string — arc layer. vector features can have category values in different layers, and this number decides which layer we're using. when you're doing direct OGR access, this is the layer name instead. default: 1
  • arc_type=string[,string,...] — arc type. input feature type. options: line, boundary. default: line,boundary
  • node_layer=string — node layer. same deal as arc layer — vector features can have category values in different layers, this number picks which one, and with direct OGR access it's the layer name. default: 2
  • from_layer=string — from layer number or name. yep, same layer situation again: category values live in different layers, this number chooses which layer, and 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 SQL statement without '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 SQL statement without '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. that's the whole vibe. obsessed.

🦋 NOTES 🦋

so these two sets are given by their respective layer, where and cats parameters. the type of to features is specified by the to_type parameter. and heads up: all from features are points, no exceptions.

a table gets linked to the output map containing various info 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. three columns, three jobs, all done. 💖

furthermore, the output map contains the shortest path between each cat, tcat pair. each path consists of several lines. if a line is on the shortest path from a point, then the category of this point is assigned to the line. and note (this is the important bit): every line may contain more than one category value, since a single line may be on the shortest path for more than one from feature. so the shortest paths can be easily obtained by querying lines with the corresponding category number. alternatively, unique paths can be created with the -l flag, where each path will be a separate single line in the output. cute, right?

the costs of arcs in forward and backward direction are specified by the arc_column and arc_backward_column columns respectively. if arc_backward_column is not given, the same cost is used in both directions. equality, iconic.

⚠️ okay so real talk: v.net.distance will not work if you are trying to find the nearest neighbors within a group of nodes, i.e. where 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. that's not it. if you want nearest neighbors within a group of nodes, you can either loop through each node as to and all other nodes as from, or create a complete distance matrix with v.net.allpairs and select the lowest non-zero distance for each node.

🌈 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 paths. periodt.

streets are grey lines, schools are green circles, hospitals are red crosses, shortest paths are blue lines:

# 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. let's go.

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

accessed: Saturday Jan 17 05:41:26 2026

main index | vector index | topics index | keywords index | graphical index | full index

🎀 and that's the whole page, bestie! this was pulled from GRASS GIS 8.4.2 Reference Manual, © 2003-2025 GRASS Development Team, and the page itself is v.net.distance(1) under GRASS 8.4.2. go map something cute. ✨🌸💖
📦 where this page comes from