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 li‐
7 brary.
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 lo‐
43 cation
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 im‐
155 ported 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 pa‐
160 rameter 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 re‐
163 gion 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 format
171 overview. The -f prints a list of the vector formats supported by the
172 system’s OGR (Simple Features Library). The OGR (Simple Features Li‐
173 brary) is part of the GDAL library, hence GDAL needs to be installed to
174 use 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 ar‐
202 eas with the same shared category. These multiple areas will therefore
203 also link to the same entry in the attribute table. A single category
204 value may thus refer to multiple non-overlapping areas which together
205 represent the original polygon overlapping with another polygon. The
206 original polygon can be recovered by using v.extract with the desired
207 category value or where statement and the -d flag to dissolve common
208 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 re‐
215 port an error message ("Projection of dataset does not appear to match
216 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.
268 Value for encoding also affects text recoding when importing DXF files.
270 For other formats has encoding value no effect.
271 Defining the key column
273 Option key specifies the column name used for feature categories. This
274 column must be integer. If not specified, categories numbers are gener‐
275 ated starting with 1 and stored in the column named "cat".
276 Supports of multiple geometry columns
278 Starting with GDAL 1.11 the library supports multiple geometry columns
279 in OGR. By default v.in.ogr reads all geometry columns from given
280 layer. The user can choose desired geometry column by geometry option,
281 see example below.
282 Latitude-longitude data: Vector postprocessing after import
284 For vector data like a grid, horizontal lines need to be broken at
285 their intersections with vertical lines (v.clean ... tool=break).
286
288 The command imports various vector formats:
289 SHAPE files
291 v.in.ogr input=/home/user/shape_data/test_shape.shp output=grass_map
292 Alternate method:
293 v.in.ogr input=/home/user/shape_data layer=test_shape output=grass_map
294 Define encoding value for attribute data (in this example we expect at‐
295 tribute data in Windows-1250 encoding; ie. in Central/Eastern European
296 languages that use Latin script, Microsoft Windows encoding).
297 v.in.ogr input=/home/user/shape_data/test_shape.shp output=grass_map encoding=cp1250
298 MapInfo files
300 v.in.ogr input=./ layer=mapinfo_test output=grass_map
301 Arc Coverage
303 We import the Arcs and Label points, the module takes care to build ar‐
304 eas.
305 v.in.ogr input=gemeinden layer=LAB,ARC type=centroid,boundary output=mymap
306 E00 file
308 See also v.in.e00.
309 First we have to convert the E00 file to an Arc Coverage with ’avcim‐
311 port’ (AVCE00 tools, use e00conv first in case that avcimport fails):
312 avcimport e00file coverage
313 v.in.ogr input=coverage layer=LAB,ARC type=centroid,boundary output=mymap
314 SDTS files
316 You have to select the CATD file.
317 v.in.ogr input=CITXCATD.DDF output=cities
318 TIGER files
320 v.in.ogr input=input/2000/56015/ layer=CompleteChain,PIP output=t56015_all \
321 type=boundary,centroid snap=-1
322 PostGIS tables
324 Import polygons as areas:
325 v.in.ogr input="PG:host=localhost dbname=postgis user=postgres" layer=polymap \
326 output=polygons type=boundary,centroid
327 If the table containing the polygons are in a specific schema, you can
328 use:
329 v.in.ogr input="PG:host=localhost dbname=postgis user=postgres" \
330 layer=myschema.polymap \
331 output=polygons type=boundary,centroid
332 Generally, v.in.ogr just follows the format-specific syntax defined by
333 the OGR library.
334 OpenStreetMap (OSM)
336 OSM data are available in .osm (XML based) and .pbf (optimized binary)
337 formats. The .pbf format is recommended because file sizes are smaller.
338 The OSM driver will categorize features into 5 layers :
339 • points: "node" features that have significant tags attached.
341 • lines: "way" features that are recognized as non-area.
343 • multilinestrings: "relation" features that form a multi‐
345 linestring(type = ’multilinestring’ or type = ’route’).
346 • multipolygons: "relation" features that form a multipolygon
348 (type = ’multipolygon’ or type = ’boundary’), and "way" fea‐
349 tures that are recognized as area.
350 • other_relations: "relation" features that do not belong to any
352 of the above layers.
353 It is recommended to import one layer at a time, and to select features
354 with the where option, e.g. to import roads, use
355 v.in.ogr where="highway <> ’’"
356 i.e. the OSM tag highway must be set.
357 When importing administrative boundaries from OSM, it is important to
359 not only select administrative boundaries, but also the admin level to
360 be imported (valid range is 1 - 11), e.g. with
361 v.in.ogr where="boundary = ’administrative’ and admin_level = ’1’"
362 The OSM topological model differs from the GRASS topological model. OSM
364 topologically correct connections of lines can be on all vertices of a
365 line. During import, lines are automatically split at those vertices
366 where an OSM connection to another line exists.
367 Import of OSM data requires a configuration file, defined with the
369 OSM_CONFIG_FILE configuration option. In the data folder of the GDAL
370 distribution, you can find a osmconf.ini file that can be customized to
371 fit your needs. See OSM map features for keys and their values. You
372 should set "other_tags=no" to avoid problems with import or querying
373 the imported vector. Once a OSM_CONFIG_FILE has been created, OSM data
374 can be imported with e.g.
375 export OSM_CONFIG_FILE=/path/to/osmconf.ini
376 v.in.ogr input=name.pbf layer=lines output=osm_data
377 Oracle Spatial
379 Note that you have to set the environment-variables ORACLE_BASE, ORA‐
380 CLE_SID, ORACLE_HOME and TNS_ADMIN accordingly.
381 v.in.ogr input=OCI:username/password@database_instance output=grasslayer layer=roads_oci
382 Multiple geometry columns
384 This example shows how to work with data which contain multiple geome‐
385 try per feature. The number of geometry columns per feature can be
386 checked by v.external together with -t flag.
387 v.external -t input=20141130_ST_UKSH.xml.gz
388 ...
389 Okresy,point,1,DefinicniBod
390 Okresy,multipolygon,1,OriginalniHranice
391 Okresy,multipolygon,1,GeneralizovaneHranice
392 ...
393 In our example layer "Okresy" has three geometry columns: "Definicni‐
394 Bod", "OriginalniHranice" and "GeneralizovanaHranice". By default
395 v.in.ogr reads data from all three geometry columns. The user can spec‐
396 ify desired geometry column by geometry option, in this case the module
397 will read geometry only from the specified geometry column. In the ex‐
398 ample below, the output vector map will contain only geometry saved in
399 "OriginalniHranice" geometry column.
400 v.in.ogr input=20141130_ST_UKSH.xml.gz layer=Okresy geometry=OriginalniHranice
401
403 If a message like
404 WARNING: Area size 1.3e-06, area not imported
405 appears, the min_area may be adjusted to a smaller value so that all
406 areas are imported. Otherwise tiny areas are filtered out during import
407 (useful to polish digitization errors or non-topological data).
408 If a message like
410 Try to import again, snapping with at least 1e-008: ’snap=1e-008’
411 appears, then the map to be imported contains topological errors. The
412 message suggests a value for the snap parameter to be tried. For more
413 details, see above in Topology Cleaning.
414
416 SQL syntax errors
417 Depending on the currently selected SQL driver, error messages such as
418 follows may arise:
419 DBMI-SQLite driver error:
420 Error in sqlite3_prepare():
421 near "ORDER": syntax error
422 Or:
423 DBMI-DBF driver error:
424 SQL parser error:
425 syntax error, unexpected DESC, expecting NAME processing ’DESC
426 This indicates that a column name in the input dataset corresponds to a
427 reserved SQL word (here: ’ORDER’ and ’DESC’ respectively). A different
428 column name has to be used in this case. The columns parameter can be
429 used to assign different column names on the fly in order to avoid us‐
430 ing reserved SQL words. For a list of SQL reserved words for SQLite
431 (the default driver), see here.
432 Projection errors
434 Projection of dataset does not appear to match the current location.
435 Here you need to create or use a location whose projection matches that
436 of the vector data you wish to import. Try using location parameter to
437 create a new location based upon the projection information in the
438 file. If desired, you can then re-project it to another location with
439 v.proj.
440
442 • OGR vector library
443 • OGR vector library C API documentation
445
447 db.connect, v.clean, v.extract, v.build.polylines, v.edit, v.external,
448 v.import, v.in.db, v.in.e00, v.out.ogr
449 GRASS GIS Wiki page: Import of Global datasets
451
453 Original author: Radim Blazek, ITC-irst, Trento, Italy
454 Location and spatial extent support by Markus Neteler and Paul Kelly
455 Various improvements by Markus Metz
456 Multiple geometry columns support by Martin Landa, OSGeoREL, Czech
457 Technical University in Prague, Czech Republic
458
460 Available at: v.in.ogr source code (history)
461 Accessed: Mon Jun 20 16:47:22 2022
463 Main index | Vector index | Topics index | Keywords index | Graphical
465 index | Full index
466 © 2003-2022 GRASS Development Team, GRASS GIS 8.2.0 Reference Manual
468GRASS 8.2.0 v.in.ogr(1)