v.net.distance(1)

NAME
v.net.distance - 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 various information about this relation are uploaded to the attribute table.

KEYWORDS
vector, network, shortest path

SYNOPSIS
v.net.distance
v.net.distance --help
v.net.distance [-g] 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 locations

--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 data source for direct OGR access

output=name [required]
    Name for output vector map

arc_layer=string
    Arc layer
    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

arc_type=string[,string,...]
    Arc type
    Input feature type
    Options: line, boundary
    Default: line,boundary

node_layer=string
    Node layer
    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: 2

from_layer=string
    From 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

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 inhab >= 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 inhab >= 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.

NOTES
These two sets are given by the respective layer, where and cats parameters. The type of to features is specified by to_type parameter. All from features are points. A table is linked to output map containing various information about the relation. More specifically, the table has three columns: cat, tcat and dist storing category of each from feature, category of the nearest to feature and the distance between them respectively. Furthemore, output map contains the shorest path between each cat, tcat pair. Each path consist of several lines. If a line is on the shorest path from a point then the category of this point is assigned to the line. Note that 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. And so the shortest paths can be easily obtained by querying lines with corresponding category number.
The costs of arcs in forward and backward direction are specified by arc_column and arc_backward_column columns respectively. If arc_backward_column is not given, the same cost is used in both directions.

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, as the closest node will be the node itself and the result will be zero-length paths. In order to find 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
Find shortest path and distance from every school to the nearest hospital and show all paths.

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 tlayer=3

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

Last changed: $Date: 2014-12-24 15:44:33 +0100 (st, 24 12 2014) $

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

© 2003-2015 GRASS Development Team, GRASS GIS 7.0.1 Reference Manual