1v.in.ogr(1) GRASS GIS User's Manual v.in.ogr(1)
2
6 v.in.ogr - Imports vector data into a GRASS vector map using OGR
7 library.
8
10 vector, import, OGR, topology, geometry, snapping, create location
11
13 v.in.ogr
14 v.in.ogr --help
15 v.in.ogr [-flc2tojrewi] input=string [gdal_config=string]
16 [gdal_doo=string] [layer=string[,string,...]] [output=name] [spa‐
17 tial=xmin,ymin,xmax,ymax[,xmin,ymin,xmax,ymax,...]] [where=sql_query]
18 [min_area=float] [type=string[,string,...]] [snap=float] [loca‐
19 tion=name] [columns=name[,name,...]] [encoding=string]
20 [key=string] [geometry=name] [--overwrite] [--help] [--verbose]
21 [--quiet] [--ui]
22 Flags:
24 -f
25 List supported OGR formats and exit
26 -l
28 List available OGR layers in data source and exit
29 -c
31 Do not clean polygons (not recommended)
32 -2
34 Force 2D output even if input is 3D
35 Useful if input is 3D but all z coordinates are identical
36 -t
38 Do not create attribute table
39 -o
41 Override projection check (use current location’s projection)
42 Assume that the dataset has the same projection as the current
43 location
44 -j
46 Perform projection check only and exit
47 -r
49 Limit import to the current region
50 -e
52 Extend region extents based on new dataset
53 Also updates the default region if in the PERMANENT mapset
54 -w
56 Change column names to lowercase characters
57 -i
59 Create the location specified by the "location" parameter and exit.
60 Do not import the vector data.
61 --overwrite
63 Allow output files to overwrite existing files
64 --help
66 Print usage summary
67 --verbose
69 Verbose module output
70 --quiet
72 Quiet module output
73 --ui
75 Force launching GUI dialog
76 Parameters:
78 input=string [required]
79 Name of OGR datasource to be imported
80 Examples:
81 Â Â Â Â Â Â Â Â ESRI Shapefile: directory containing shapefiles
82 Â Â Â Â Â Â Â Â MapInfo File: directory containing mapinfo files
83 gdal_config=string
85 GDAL configuration options
86 Comma-separated list of key=value pairs
87 gdal_doo=string
89 GDAL dataset open options
90 Comma-separated list of key=value pairs
91 layer=string[,string,...]
93 OGR layer name. If not given, all available layers are imported
94 Examples:
95 Â Â Â Â Â Â Â Â ESRI Shapefile: shapefile name
96 Â Â Â Â Â Â Â Â MapInfo File: mapinfo file name
97 output=name
99 Name for output vector map
100 spatial=xmin,ymin,xmax,ymax[,xmin,ymin,xmax,ymax,...]
102 Import subregion only
103 Format: xmin,ymin,xmax,ymax - usually W,S,E,N
104 where=sql_query
106 WHERE conditions of SQL statement without ’where’ keyword
107 Example: income < 1000 and population >= 10000
108 min_area=float
110 Minimum size of area to be imported (square meters)
111 Smaller areas and islands are ignored. Should be greater than
112 snap^2
113 Default: 0.0001
114 type=string[,string,...]
116 Optionally change default input type
117 Options: point, line, boundary, centroid
118 Default:
119 point: import area centroids as points
120 line: import area boundaries as lines
121 boundary: import lines as area boundaries
122 centroid: import points as centroids
123 snap=float
125 Snapping threshold for boundaries (map units)
126 ’-1’ for no snap
127 Default: -1
128 location=name
130 Name for new location to create
131 columns=name[,name,...]
133 List of column names to be used instead of original names, first is
134 used for category column
135 encoding=string
137 Encoding value for attribute data
138 Overrides encoding interpretation, useful when importing ESRI
139 Shapefile
140 key=string
142 Name of column used for categories
143 If not given, categories are generated as unique values and stored
144 in ’cat’ column
145 geometry=name
147 Name of geometry column
148 If not given, all geometry columns from the input are used
149
151 v.in.ogr imports vector data from files and database connections sup‐
152 ported by the OGR library) into the current location and mapset.
153 If the layer parameter is not given, all available OGR layers are
155 imported as separate GRASS layers into one GRASS vector map. If several
156 OGR layer names are given, all these layers are imported as separate
157 GRASS layers into one GRASS vector map.
158 The optional spatial parameter defines spatial query extents. This
160 parameter allows the user to restrict the region to a spatial subset
161 while importing the data. All vector features completely or partially
162 falling into this rectangle subregion are imported. The -r current
163 region flag is identical, but uses the current region settings as the
164 spatial bounds (see g.region).
165 Supported Vector Formats
167 v.in.ogr uses the OGR library which supports various vector data for‐
168 mats including ESRI Shapefile, Mapinfo File, UK .NTF, SDTS, TIGER, IHO
169 S-57 (ENC), DGN, GML, GPX, AVCBin, REC, Memory, OGDI, and PostgreSQL,
170 depending on the local OGR installation. For details see the OGR web
171 site. The -f prints a list of the vector formats supported by the sys‐
172 tem’s OGR (Simple Features Library). The OGR (Simple Features Library)
173 is part of the GDAL library, hence GDAL needs to be installed to use
174 v.in.ogr.
175 The list of actually supported formats can be printed by -f flag.
177 Topology cleaning
179 Topology cleaning on areas is automatically performed, but may fail in
180 special cases. In these cases, a snap threshold value is estimated from
181 the imported vector data and printed out at the end. The vector data
182 can then be imported again with the suggested snap threshold value
183 which is incremented by powers of 10 until either an estimated upper
184 limit for the threshold value is reached or the topology cleaning on
185 areas was successful. In some cases, manual cleaning might be required
186 or areas are truly overlapping, e.g. buffers created with non-topologi‐
187 cal software.
188 The min_area threshold value is being specified as area size in map
190 units with the exception of latitude-longitude locations in which it is
191 being specified solely in square meters.
192 The snap threshold value is used to snap boundary vertices to each
194 other if the distance in map units between two vertices is not larger
195 than the threshold. Snapping is by default disabled with -1. See also
196 the v.clean manual.
197 Overlapping polygons
199 When importing overlapping polygons, the overlapping parts will become
200 new areas with multiple categories, one unique category for each origi‐
201 nal polygon. An original polygon will thus be converted to multiple
202 areas with the same shared category. These multiple areas will there‐
203 fore also link to the same entry in the attribute table. A single cate‐
204 gory value may thus refer to multiple non-overlapping areas which
205 together represent the original polygon overlapping with another poly‐
206 gon. The original polygon can be recovered by using v.extract with the
207 desired category value or where statement and the -d flag to dissolve
208 common boundaries.
209
211 v.in.ogr attempts to preserve projection information when importing
212 datasets if the source format includes projection information, and if
213 the OGR driver supports it. If the projection of the source dataset
214 does not match the projection of the current location v.in.ogr will
215 report an error message ("Projection of dataset does not appear to
216 match current location").
217 If the user wishes to ignore the difference between the apparent coor‐
219 dinate system of the source data and the current location, they may
220 pass the -o flag to override the projection check.
221 If the user wishes to import the data with the full projection defini‐
223 tion, it is possible to have v.in.ogr automatically create a new loca‐
224 tion based on the projection and extents of the file being read. This
225 is accomplished by passing the name to be used for the new location via
226 the location parameter. Upon completion of the command, a new location
227 will have been created (with only a PERMANENT mapset), and the vector
228 map will have been imported with the indicated output name into the
229 PERMANENT mapset.
230 An interesting wrapper command around v.in.ogr is v.import which repro‐
232 jects (if needed) the vector dataset during import to the projection of
233 the current location.
234
236 Table column names: supported characters
237 The characters which are eligible for table column names are limited by
238 the SQL standard. Supported are:
239 [A-Za-z][A-Za-z0-9_]*
240 This means that SQL neither supports ’.’ (dots) nor ’-’ (minus) nor ’#’
241 in table column names. Also a table name must start with a character,
242 not a number.
243 v.in.ogr converts ’.’, ’-’ and ’#’ to ’_’ (underscore) during import.
245 The -w flag changes capital column names to lowercase characters as a
246 convenience for SQL usage (lowercase column names avoid the need to
247 quote them if the attribute table is stored in a SQL DBMS such as Post‐
248 greSQL). The columns parameter is used to define new column names dur‐
249 ing import.
250 The DBF database specification limits column names to 10 characters.
252 If the default DB is set to DBF and the input data contains longer col‐
253 umn/field names, they will be truncated. If this results in multiple
254 columns with the same name then v.in.ogr will produce an error. In
255 this case you will either have to modify the input data or use
256 v.in.ogr’s columns parameter to rename columns to something unique.
257 (hint: copy and modify the list given with the error message). Alter‐
258 natively, change the local DB with db.connect.
259 File encoding
261 When importing ESRI Shapefiles the OGR library tries to read the
262 LDID/codepage setting from the .dbf file and use it to translate string
263 fields to UTF-8. LDID "87 / 0x57" is treated as ISO8859_1 which may not
264 be appropriate for many languages. Unfortunately it is not clear what
265 other values may be appropriate (see example below). To change encoding
266 the user can set up SHAPE_ENCODING environmental variable or simply to
267 define encoding value using encoding parameter. Note that recoding sup‐
268 port is new for GDAL/OGR 1.9.0.
269 Value for encoding also affects text recoding when importing DXF files.
271 For other formats has encoding value no effect.
272 Defining the key column
274 Option key specifies the column name used for feature categories. This
275 column must be integer. If not specified, categories numbers are gener‐
276 ated starting with 1 and stored in the column named "cat".
277 Supports of multiple geometry columns
279 Starting with GDAL 1.11 the library supports multiple geometry columns
280 in OGR. By default v.in.ogr reads all geometry columns from given
281 layer. The user can choose desired geometry column by geometry option,
282 see example below.
283 Latitude-longitude data: Vector postprocessing after import
285 For vector data like a grid, horizontal lines need to be broken at
286 their intersections with vertical lines (v.clean ... tool=break).
287
289 The command imports various vector formats:
290 SHAPE files
292 v.in.ogr input=/home/user/shape_data/test_shape.shp output=grass_map
293 Alternate method:
294 v.in.ogr input=/home/user/shape_data layer=test_shape output=grass_map
295 Define encoding value for attribute data (in this example we expect
296 attribute data in Windows-1250 encoding; ie. in Central/Eastern Euro‐
297 pean languages that use Latin script, Microsoft Windows encoding).
298 v.in.ogr input=/home/user/shape_data/test_shape.shp output=grass_map encoding=cp1250
299 MapInfo files
301 v.in.ogr input=./ layer=mapinfo_test output=grass_map
302 Arc Coverage
304 We import the Arcs and Label points, the module takes care to build
305 areas.
306 v.in.ogr input=gemeinden layer=LAB,ARC type=centroid,boundary output=mymap
307 E00 file
309 See also v.in.e00.
310 First we have to convert the E00 file to an Arc Coverage with ’avcim‐
312 port’ (AVCE00 tools, use e00conv first in case that avcimport fails):
313 avcimport e00file coverage
314 v.in.ogr input=coverage layer=LAB,ARC type=centroid,boundary output=mymap
315 SDTS files
317 You have to select the CATD file.
318 v.in.ogr input=CITXCATD.DDF output=cities
319 TIGER files
321 v.in.ogr input=input/2000/56015/ layer=CompleteChain,PIP output=t56015_all \
322 type=boundary,centroid snap=-1
323 PostGIS tables
325 Import polygons as areas:
326 v.in.ogr input="PG:host=localhost dbname=postgis user=postgres" layer=polymap \
327 output=polygons type=boundary,centroid
328 If the table containing the polygons are in a specific schema, you can
329 use:
330 v.in.ogr input="PG:host=localhost dbname=postgis user=postgres" \
331 layer=myschema.polymap \
332 output=polygons type=boundary,centroid
333 Generally, v.in.ogr just follows the format-specific syntax defined by
334 the OGR library.
335 OpenStreetMap (OSM)
337 OSM data are available in .osm (XML based) and .pbf (optimized binary)
338 formats. The .pbf format is recommended because file sizes are smaller.
339 The OSM driver will categorize features into 5 layers :
340 · points: "node" features that have significant tags attached.
342 · lines: "way" features that are recognized as non-area.
344 · multilinestrings: "relation" features that form a multi‐
346 linestring(type = ’multilinestring’ or type = ’route’).
347 · multipolygons: "relation" features that form a multipolygon
349 (type = ’multipolygon’ or type = ’boundary’), and "way" fea‐
350 tures that are recognized as area.
351 · other_relations: "relation" features that do not belong to any
353 of the above layers.
354 It is recommended to import one layer at a time, and to select features
355 with the where option, e.g. to import roads, use
356 v.in.ogr where="highway <> ’’"
357 i.e. the OSM tag highway must be set.
358 When importing administrative boundaries from OSM, it is important to
360 not only select administrative boundaries, but also the admin level to
361 be imported (valid range is 1 - 11), e.g. with
362 v.in.ogr where="boundary = ’administrative’ and admin_level = ’1’"
363 The OSM topological model differs from the GRASS topological model. OSM
365 topologically correct connections of lines can be on all vertices of a
366 line. During import, lines are automatically split at those vertices
367 where an OSM connection to another line exists.
368 Import of OSM data requires a configuration file, defined with the
370 OSM_CONFIG_FILE configuration option. In the data folder of the GDAL
371 distribution, you can find a osmconf.ini file that can be customized to
372 fit your needs. See OSM map features for keys and their values. You
373 should set "other_tags=no" to avoid problems with import or querying
374 the imported vector. Once a OSM_CONFIG_FILE has been created, OSM data
375 can be imported with e.g.
376 export OSM_CONFIG_FILE=/path/to/osmconf.ini
377 v.in.ogr input=name.pbf layer=lines output=osm_data
378 Oracle Spatial
380 Note that you have to set the environment-variables ORACLE_BASE, ORA‐
381 CLE_SID, ORACLE_HOME and TNS_ADMIN accordingly.
382 v.in.ogr input=OCI:username/password@database_instance output=grasslayer layer=roads_oci
383 Multiple geometry columns
385 This example shows how to work with data which contain multiple geome‐
386 try per feature. The number of geometry columns per feature can be
387 checked by v.external together with -t flag.
388 v.external -t input=20141130_ST_UKSH.xml.gz
389 ...
390 Okresy,point,1,DefinicniBod
391 Okresy,multipolygon,1,OriginalniHranice
392 Okresy,multipolygon,1,GeneralizovaneHranice
393 ...
394 In our example layer "Okresy" has three geometry columns: "Definicni‐
395 Bod", "OriginalniHranice" and "GeneralizovanaHranice". By default
396 v.in.ogr reads data from all three geometry columns. The user can spec‐
397 ify desired geometry column by geometry option, in this case the module
398 will read geometry only from the specified geometry column. In the
399 example below, the output vector map will contain only geometry saved
400 in "OriginalniHranice" geometry column.
401 v.in.ogr input=20141130_ST_UKSH.xml.gz layer=Okresy geometry=OriginalniHranice
402
404 If a message like
405 WARNING: Area size 1.3e-06, area not imported
406 appears, the min_area may be adjusted to a smaller value so that all
407 areas are imported. Otherwise tiny areas are filtered out during import
408 (useful to polish digitization errors or non-topological data).
409 If a message like
411 Try to import again, snapping with at least 1e-008: ’snap=1e-008’
412 appears, then the map to be imported contains topological errors. The
413 message suggests a value for the snap parameter to be tried. For more
414 details, see above in Topology Cleaning.
415
417 SQL syntax errors
418 Depending on the currently selected SQL driver, error messages such as
419 follows may arise:
420 DBMI-SQLite driver error:
421 Error in sqlite3_prepare():
422 near "ORDER": syntax error
423 Or:
424 DBMI-DBF driver error:
425 SQL parser error:
426 syntax error, unexpected DESC, expecting NAME processing ’DESC
427 This indicates that a column name in the input dataset corresponds to a
428 reserved SQL word (here: ’ORDER’ and ’DESC’ respectively). A different
429 column name has to be used in this case. The columns parameter can be
430 used to assign different column names on the fly in order to avoid
431 using reserved SQL words. For a list of SQL reserved words for SQLite
432 (the default driver), see here.
433 Projection errors
435 Projection of dataset does not appear to match the current location.
436 Here you need to create or use a location whose projection matches that
437 of the vector data you wish to import. Try using location parameter to
438 create a new location based upon the projection information in the
439 file. If desired, you can then re-project it to another location with
440 v.proj.
441
443 · OGR vector library
444 · OGR vector library C API documentation
446
448 db.connect, v.clean, v.extract, v.build.polylines, v.edit, v.external,
449 v.import, v.in.db, v.in.e00, v.out.ogr
450 GRASS GIS Wiki page: Import of Global datasets
452
454 Original author: Radim Blazek, ITC-irst, Trento, Italy
455 Location and spatial extent support by Markus Neteler and Paul Kelly
456 Various improvements by Markus Metz
457 Multiple geometry columns support by Martin Landa, OSGeoREL, Czech
458 Technical University in Prague, Czech Republic
459
461 Available at: v.in.ogr source code (history)
462 Main index | Vector index | Topics index | Keywords index | Graphical
464 index | Full index
465 © 2003-2020 GRASS Development Team, GRASS GIS 7.8.5 Reference Manual
467GRASS 7.8.5 v.in.ogr(1)