1v.to.db(1)                  GRASS GIS User's Manual                 v.to.db(1)
2
3
4

NAME

6       v.to.db  - Populates attribute values from vector features.
7

KEYWORDS

9       vector,  attribute  table, database, area, azimuth, bounding box, cate‐
10       gory, compactness, coordinates, fractal, geometry,  length,  perimeter,
11       sides, sinuous, slope
12

SYNOPSIS

14       v.to.db
15       v.to.db --help
16       v.to.db  [-psc]  map=name   [layer=string]   [type=string[,string,...]]
17       option=string          columns=name[,name,...]           [units=string]
18       [query_layer=string]      [query_column=name]     [separator=character]
19       [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]
20
21   Flags:
22       -p
23           Print only
24
25       -s
26           Only print SQL statements
27
28       -c
29           Print also totals for option length, area, or count
30
31       --overwrite
32           Allow output files to overwrite existing files
33
34       --help
35           Print usage summary
36
37       --verbose
38           Verbose module output
39
40       --quiet
41           Quiet module output
42
43       --ui
44           Force launching GUI dialog
45
46   Parameters:
47       map=name [required]
48           Name of vector map
49           Or data source for direct OGR access
50
51       layer=string
52           Layer number or name (write to)
53           Vector features can have category values in different layers.  This
54           number  determines  which  layer  to use. When used with direct OGR
55           access this is the layer name.
56           Default: 1
57
58       type=string[,string,...]
59           Feature type
60           For coor valid point/centroid, for length valid line/boundary
61           Options: point, line, boundary, centroid
62           Default: point,line,boundary,centroid
63
64       option=string [required]
65           Value to upload
66           Options: cat, area, compact, fd, perimeter,  length,  count,  coor,
67           start, end, sides, query, slope, sinuous, azimuth, bbox
68           cat: insert new row for each category if doesn’t exist yet
69           area: area size
70           compact: compactness of an area, calculated as
71           compactness = perimeter / (2 * sqrt(PI * area))
72           fd: fractal dimension of boundary defining a polygon, calculated as
73           fd = 2 * (log(perimeter) / log(area))
74           perimeter: perimeter length of an area
75           length: line length
76           count: number of features for each category
77           coor: point coordinates, X,Y or X,Y,Z
78           start: line/boundary starting point coordinates, X,Y or X,Y,Z
79           end: line/boundary end point coordinates, X,Y or X,Y,Z
80           sides: categories of areas on the left and right side of the bound‐
81           ary, ’query_layer’ is used for area category
82           query: result of a database query for all  records  of  the  geome‐
83           try(or geometries) from table specified by ’query_layer’ option
84           slope: slope steepness of vector line or boundary
85           sinuous:  line  sinuousity,  calculated  as  line length / distance
86           between end points
87           azimuth: line azimuth, calculated as angle between North  direction
88           and endnode direction at startnode
89           bbox: bounding box of area, N,S,E,W
90
91       columns=name[,name,...] [required]
92           Name of attribute column(s) to populate
93           Name of attribute column(s)
94
95       units=string
96           Units
97           Options: miles, feet, meters, kilometers, acres, hectares, radians,
98           degrees
99
100       query_layer=string
101           Query layer number or name (read from)
102           Vector features can have category values in different layers.  This
103           number  determines  which  layer  to use. When used with direct OGR
104           access this is the layer name.
105           Default: 1
106
107       query_column=name
108           Name of attribute column used for ’query’ option
109           E.g. ’cat’, ’count(*)’, ’sum(val)’
110
111       separator=character
112           Field separator for print mode
113           Special characters: pipe, comma, space, tab, newline
114           Default: pipe
115

DESCRIPTION

117       v.to.db loads vector map features or metrics into a database table,  or
118       prints  them  (or  the  SQL queries used to obtain them) in a form of a
119       human-readable report. For uploaded/printed  category  values  ’-1’  is
120       used  for  ’no  category’ and ’null’/’-’ if category cannot be found or
121       multiple categories were found. For line  azimuths  ’-1’  is  used  for
122       closed lines (start equals end).
123

NOTES

125       Measures of lengths and areas are always reported in meters, unless the
126       unit parameter is set.  The units miles, feet,  meters  and  kilometers
127       are square for option=area.
128
129       Feet  and acre units are always reported in their common versions (i.e.
130       the International Foot, exactly 5280 feet in a  mile),  even  when  the
131       location’s standard map unit is the US Survey foot.
132
133       When  calculating  perimeters in Latitude-Longitude locations, the geo‐
134       desic distance between the vertices is used.
135
136       When using option=coor on a vector area map, only coordinates  of  cen‐
137       troids with unique category will be reported.
138
139       When  using option=bbox on a vector area map with more than one feature
140       per category value, the results corresponds to the bounding box of  all
141       features of same category taken together.
142
143       Line  azimuth  is  calculated  as angle from the North direction to the
144       line endnode direction at the line statnode. By default  it’s  reported
145       in  decimal  degrees  (0-360, CW) but it also may be repored in radians
146       with unit=radians. Azimuth value -1 is used to report closed line  with
147       it’s  startnode  and  endnode  being in same place. Azimuth values make
148       sense only if every vector line has only one entry in database  (unique
149       CAT value).
150
151       If  the  module is apparently slow and the map attributes are stored in
152       an external DBMS such as PostgreSQL, it is highly recommended to create
153       an index on the key (category) column.
154
155       Uploading  the  vector  map  attributes  to a database requires a table
156       attached to a given input  vector  layer.  The  print  only  (-p)  mode
157       doesn’t  require  a  table. Use db.execute or v.db.addtable to create a
158       table if needed.
159
160       Updating the table has to be done column-wise. The column will be  cre‐
161       ated  in  the  table if it doesn’t already exist, except when using the
162       print only (-p) mode. If the column exists,  the  --overwrite  flag  is
163       required to overwrite it.
164

EXAMPLES

166   Updating attribute tables
167       Upload category numbers to attribute table (used for new map):
168       v.to.db map=soils type=centroid option=cat
169
170       Upload  polygon areas to corresponding centroid record in the attribute
171       table:
172       v.to.db map=soils type=centroid option=area columns=area_size unit=h
173
174       Upload line lengths (in meters) of each vector line to attribute  table
175       (use v.category in case of missing categories):
176       v.to.db map=roads option=length type=line columns=linelength units=me
177
178       Upload x and y coordinates from vector geometry to attribute table:
179       v.to.db map=pointsmap option=coor columns=x,y
180
181       Upload x, y and z coordinates from vector geometry to attribute table:
182       v.to.db map=pointsmap option=coor columns=x,y,z
183
184       Transfer  attributes from a character column (with numeric contents) to
185       a new integer column:
186       v.db.addcolumn usa_income_employment2002 col="FIPS_NUM integer"
187       v.to.db usa_income_employment2002 option=query columns=FIPS_NUM query_column=STATE_FIPS
188
189       Upload category numbers of left and right area, to an  attribute  table
190       of boundaries common for the areas:
191       # add categories for boundaries of the input vector map, in layer 2:
192       v.category soils out=mysoils layer=2 type=boundary option=add
193       # add a table with columns named "left" and "right" to layer 2 of the input
194       # vector map:
195       v.db.addtable mysoils layer=2 columns="left integer,right integer"
196       # upload categories of left and right areas:
197       v.to.db mysoils option=sides columns=left,right layer=2
198       # display the result:
199       v.db.select mysoils layer=2
200
201       Compute  DL,  the Fractal Dimension (Mandelbrot, 1982), of the boundary
202       defining a polygon based on the formula:
203       D = 2 * (log perimeter) / (log area):
204       g.copy vect=soils,mysoils
205       v.db.addcolumn mysoils col="d double precision"
206       v.to.db mysoils option=fd column="d"
207       g.region vector=mysoils res=50
208       v.to.rast input=mysoils output=soils_fd type=area use=attr attribute_column=d
209       r.colors map=soils_fd color=gyr
210       d.mon wx0
211       d.rast.leg soils_fd
212       d.vect mysoils type=boundary
213
214   Printing reports
215       Report x,y,z coordinates of points in the input vector map:
216       v.to.db -p bugsites option=coor type=point
217       Report all area sizes of the input vector map:
218       v.to.db -p soils option=area type=boundary units=h
219
220       Report all area sizes of the input vector map, in hectares,  sorted  by
221       category number (requires GNU sort utility installed):
222       v.to.db -p soils option=area type=boundary units=h | sort -n
223
224       Report all line lengths of the input vector map, in kilometers:
225       v.to.db -p roads option=length type=line units=k
226
227       Report number of features for each category in the input vector map:
228       v.to.db -p roads option=count type=line
229

SEE ALSO

231         d.what.vect,  db.execute,  v.category, v.db.addtable, v.db.addcolumn,
232       v.db.connect, v.distance, v.report, v.univar, v.what
233

REFERENCES

235           ·   Mandelbrot, B. B. (1982). The fractal geometry of  nature.  New
236               York: W. H. Freeman.
237
238           ·   Xu, Y. F. & Sun, D. A. (2005). Geotechnique 55, No. 9, 691-695
239

AUTHOR

241       Radim Blazek, ITC-irst, Trento, Italy
242       Line sinuousity implemented by Wolf Bergenheim
243

SOURCE CODE

245       Available at: v.to.db source code (history)
246
247       Main  index  | Vector index | Topics index | Keywords index | Graphical
248       index | Full index
249
250       © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
251
252
253
254GRASS 7.8.5                                                         v.to.db(1)
Impressum