v.distance(1)

1v.distance(1)                 Grass User's Manual                v.distance(1)
2
3
4

NAME

6       v.distance   -  Find the nearest element in vector 'to' for elements in
7       vector 'from'. Various information about this relation may be  uploaded
8       to the attribute table of input vector 'from' or printed to stdout
9

KEYWORDS

11       vector
12

SYNOPSIS

14       v.distance
15       v.distance help
16       v.distance  [-pa]  from=name  to=name   [from_type=string[,string,...]]
17       [to_type=string[,string,...]]   [from_layer=integer]    [to_layer=inte‐
18       ger]    [output=name]    [dmax=float]   upload=string[,string,...] col‐
19       umn=string[,string,...]  [to_column=string]   [table=string]   [--over‐
20       write]
21
22   Flags:
23       -p  Print  output to stdout, don't update attribute table. First column
24           is always category of 'from' feature called from_cat
25
26       -a  Calculate distances to all features within the threshold. The  out‐
27           put is written to stdout but may be uploaded to a new table created
28           by this module. From categories are may be multiple
29
30       --overwrite
31
32   Parameters:
33       from=name
34           Name of existing vector file
35
36       to=name
37           Name of existing vector file
38
39       from_type=string[,string,...]
40           From type Options: point,centroid Default: point
41
42       to_type=string[,string,...]
43           To   type   Options:   point,line,boundary,centroid,area   Default:
44           point,line,area
45
46       from_layer=integer
47           From layer Default: 1
48
49       to_layer=integer
50           To layer Default: 1
51
52       output=name
53           New vector map containing lines connecting nearest elements
54
55       dmax=float
56           Maximum distance or -1 for no limit Default: -1
57
58       upload=string[,string,...]
59           Values describing the relation between two nearest features:
60                cat  -  category  of the nearest feature   dist - minimum dis‐
61           tance to nearest feature    to_x -  x  coordinate  of  the  nearest
62           point  on 'to' feature     to_y - y coordinate of the nearest point
63           on 'to' feature    to_along - distance  to  the  nearest  point  on
64           'from'  feature  along  linear  feature  to_angle - angle of linear
65           feature in nearest point, counterclockwise from positive x axis, in
66           radians, which is between -PI and PI inclusive  to_attr - attribute
67           of   nearest   feature   given   by   to_column   option   Options:
68           cat,dist,to_x,to_y,to_along,to_angle,to_attr
69
70       column=string[,string,...]
71           Column  name(s)  where  values specified by 'upload' option will be
72           uploaded
73
74       to_column=string
75           Column name of nearest feature (used with upload=to_attr)
76
77       table=string
78           The name of the table created for output when -a flag is used
79

DESCRIPTION

81       v.distance finds features from one vector (from=)  feature  to  another
82       vector (to=) nearest feature.  Various information about relation (dis‐
83       tance, ...) may be uploaded to attribute table attached to first vector
84       map  or  printed  to  'stdout'.   A new vector map may be created where
85       lines connecting nearest points on features are written.
86

EXAMPLES

88       1) Find nearest lines in vector map ln for points from vector  map  pnt
89       within  the given threshold and write related line categories to column
90       linecat in attribute table attached to vector map pnt:
91
92       v.distance from=pnt to=ln upload=cat column=linecat
93
94
95       2) For each point from vector map pnt find nearest  area  from  map  ar
96       within  the  given  threshold  and write the related area categories to
97       column areacat in attribute table attached to vector map pnt. In case a
98       point falls into a polygon area, the distance is zero:
99
100       v.distance from=pnt to=ar upload=cat column=areacat
101
102
103       3) Create a new vector map which contains lines connecting nearest fea‐
104       tures of maps pnt and map ln. The resulting vector map can be used  for
105       example to connect points to a network as needed for network analysis:
106
107       v.distance -p from=pnt to=ln out=connections upload=dist column=dist
108
109
110       4)  Query  information  from selected point(s). v.distance takes points
111       from vector as input instead of stdin. First new vector map with  query
112       points, has to be created, then the map can be analysed:
113
114       Create query map (if not present):
115
116       echo "123456|654321|1" | v.in.ascii output=pnt
117
118       Find nearest features:
119
120       v.distance from=pnt to=map_to_query upload=cat col=somecol -p
121
122
123       5)  Point-in-polygon:  Find area from vector map ar for each point from
124       vector map pnt in which the individual point falls into and  write  the
125       related area categories to column areacat into attribute table attached
126       to vector map pnt:
127
128       v.distance from=pnt to=ar dmax=0 upload=cat column=areacat
129
130
131       6) Univariate statistics on results: Create  a  vector  map  containing
132       connecting lines and investigate mean distance to targets.
133       An  alternative solution is to use the v.distance upload=dist option to
134       upload distances into the bugs vector directly, then  run  v.univar  on
135       that. Also note you can  upload two columns at a time.
136       e.g. v.distance upload=cat,dist column=nearest_id,dist_to_nr
137
138       # create working copy
139       g.copy vect=bugsites,bugs
140       # add new attribute column to hold nearest archsite category number
141       v.db.addcol map=bugs column="nrst_arch INTEGER"
142       v.distance from=bugs to=archsites to_type=point upload=to_attr \
143         to_column=cat column=nrst_arch out=vdistance_vectors_raw
144       #  we need to give the lines category numbers, create a table, and cre‐
145       ate
146       #  a column in that table to hold the distance data.
147       v.category vdistance_vectors_raw out=vdistance_vectors type=line op=add
148       g.remove v=vdistance_vectors_raw
149       v.db.addtable map=vdistance_vectors column="length DOUBLE"
150       v.to.db map=vdistance_vectors option=length column=length
151       # calculcate statistics. Use v.univar.sh for extended statistics.
152       v.univar vdistance_vectors column=length
153
154

NOTES

156       If a nearest feature does not have a category,  column  is  updated  to
157       null.   This  is  true also for areas, which means for example, that if
158       point is in island (area WITHOUT category), v.distance does not  search
159       for  nearest  area  WITH  category, island is identified as nearest and
160       category updated to null.
161
162       The upload column(s) must already exist. Create one with v.db.addcol.
163

AUTHOR

168       Janne Soimasuo 1994, Finland
169       University of Joensuu, Faculty of Forestry, Finland
170
171       5.0 cmd line coordinates support:  Markus  Neteler,  ITC-irst,  Trento,
172       Italy
173
174       5.1 update Radim Blazek, ITC-irst, Trento, Italy
175
176       Last changed: $Date: 2006/03/30 11:40:14 $
177
178       Full index
179
180
181
182GRASS 6.2.2                                                      v.distance(1)