xenial (1) v.in.ogr.1grass.gz

Provided by: grass-doc_7.0.3-1build1_all bug

NAME

       v.in.ogr  - Imports vector data into a GRASS vector map using OGR library.

KEYWORDS

       vector, import, OGR

SYNOPSIS

       v.in.ogr
       v.in.ogr --help
       v.in.ogr       [-flc2tojrewi]       input=string        [layer=string[,string,...]]         [output=name]
       [spatial=xmin,ymin,xmax,ymax[,xmin,ymin,xmax,ymax,...]]        [where=sql_query]         [min_area=float]
       [type=string[,string,...]]         [snap=float]         [location=name]         [columns=name[,name,...]]
       [encoding=string]   [key=string]    [geometry=name]    [--overwrite]   [--help]   [--verbose]   [--quiet]
       [--ui]

   Flags:
       -f
           List supported OGR formats and exit

       -l
           List available OGR layers in data source and exit

       -c
           Do not clean polygons (not recommended)

       -2
           Force 2D output even if input is 3D
           Useful if input is 3D but all z coordinates are identical

       -t
           Do not create attribute table

       -o
           Override dataset projection (use location’s projection)

       -j
           Perform projection check only and exit

       -r
           Limit import to the current region

       -e
           Extend region extents based on new dataset
           Also updates the default region if in the PERMANENT mapset

       -w
           Change column names to lowercase characters

       -i
           Create the location specified by the "location" parameter and exit. Do not import the vector data.

       --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=string [required]
           OGR datasource name
           Examples:
           ESRI Shapefile: directory containing shapefiles
           MapInfo File: directory containing mapinfo files

       layer=string[,string,...]
           OGR layer name. If not given, all available layers are imported
           Examples:
           ESRI Shapefile: shapefile name
           MapInfo File: mapinfo file name

       output=name
           Name for output vector map

       spatial=xmin,ymin,xmax,ymax[,xmin,ymin,xmax,ymax,...]
           Import subregion only
           Format: xmin,ymin,xmax,ymax - usually W,S,E,N

       where=sql_query
           WHERE conditions of SQL statement without ’where’ keyword
           Example: income < 1000 and inhab >= 10000

       min_area=float
           Minimum size of area to be imported (square meters)
           Smaller areas and islands are ignored. Should be greater than snap^2
           Default: 0.0001

       type=string[,string,...]
           Optionally change default input type
           Options: point, line, boundary, centroid
           Default:
           point: import area centroids as points
           line: import area boundaries as lines
           boundary: import lines as area boundaries
           centroid: import points as centroids

       snap=float
           Snapping threshold for boundaries (map units)
           ’-1’ for no snap
           Default: -1

       location=name
           Name for new location to create

       columns=name[,name,...]
           List of column names to be used instead of original names, first is used for category column

       encoding=string
           Encoding value for attribute data
           Overrides encoding interpretation, useful when importing ESRI Shapefile

       key=string
           Name of column used for categories
           If not given, categories are generated as unique values and stored in ’cat’ column

       geometry=name
           Name of geometry column
           If not given, all geometry columns from the input are used

DESCRIPTION

       v.in.ogr imports vector data using OGR library to GRASS vector map. OGR (Simple Features Library) is part
       of the GDAL library, so you need to install GDAL to use v.in.ogr.

       If the layer parameter is not given, all available OGR layers are imported as separate GRASS layers  into
       one  GRASS  vector  map.  If several OGR layer names are given, all these layers are imported as separate
       GRASS layers into one GRASS vector map.

       The optional spatial parameter defines spatial query extents.  This parameter allows the user to restrict
       the  region  to  a  spatial  subset while importing the data. All vector features completely or partially
       falling into this rectangle subregion are imported.  The -r current region flag is  identical,  but  uses
       the current region settings as the spatial bounds (see g.region).

   Topology cleaning
       Topology  cleaning  on areas is automatically performed, but may fail in special cases. In these cases, a
       snap threshold value is estimated from the imported vector data and printed out at the  end.  The  vector
       data can then be imported again with the suggested snap threshold value which is incremented by powers of
       10 until either an estimated upper limit for the threshold value is reached or the topology  cleaning  on
       areas  was  successful.  In some cases, manual cleaning might be required or areas are truly overlapping,
       e.g. buffers created with non-topological software.

       The min_area threshold value is being specified  as  area  size  in  map  units  with  the  exception  of
       latitude-longitude locations in which it is being specified solely in square meters.

       The  snap  threshold  value  is used to snap boundary vertices to each other if the distance in map units
       between two vertices is not larger than the threshold. Snapping is by default disabled with -1. See  also
       the v.clean manual.

   Supported OGR Vector Formats
       OGR  library  supports various vector data formats including ESRI Shapefile, Mapinfo File, UK .NTF, SDTS,
       TIGER, IHO S-57 (ENC), DGN,  GML,  AVCBin,  REC,  Memory,  OGDI,  and  PostgreSQL  depend  on  the  local
       installation, for details see OGR web site.

       List of locally supported formats can be printed by -f flag.

   Overlapping polygons
       When  importing  overlapping  polygons,  the  overlapping  parts  will  become  new  areas  with multiple
       categories, one unique category for each original polygon. An original polygon will thus be converted  to
       multiple  areas  with the same shared category. These multiple areas will therefore also link to the same
       entry in the attribute table. A single category value may thus refer to  multiple  non-overlapping  areas
       which  together represent the original polygon overlapping with another polygon. The original polygon can
       be recovered by using v.extract with the desired category value or where statement and  the  -d  flag  to
       dissolve common boundaries.

Location Creation

       v.in.ogr  attempts  to  preserve  projection  information  when  importing  datasets if the source format
       includes projection information, and if the OGR driver supports it.  If  the  projection  of  the  source
       dataset  does  not  match  the  projection  of the current location v.in.ogr will report an error message
       ("Projection of dataset does not appear to match current location").

       If the user wishes to ignore the difference between the apparent coordinate system of the source data and
       the current location, they may pass the -o flag to override the projection check.

       If  the  user  wishes  to  import  the  data  with the full projection definition, it is possible to have
       v.in.ogr automatically create a new location based on the projection and extents of the file being  read.
       This  is  accomplished  by  passing  the name to be used for the new location via the location parameter.
       Upon completion of the command, a new location will have been created (with only a PERMANENT mapset), and
       the vector map will have been imported with the indicated output name into the PERMANENT mapset.

NOTES

       The characters used for table column names are limited. Supported are:
       [A-Za-z][A-Za-z0-9_]*
       This  means  that  SQL  neither supports ’.’ (dots) nor ’-’ (minus) nor ’#’ in table column names. Also a
       table name must start with a character, not a number.

       v.in.ogr converts ’.’, ’-’ and ’#’ to ’_’ (underscore) during import. The -w flag changes capital  column
       names  to  lowercase  characters as a convenience for SQL usage (lowercase column names avoid the need to
       quote them if the attribute table is stored in a SQL DBMS such as PostgreSQL). The  cnames  parameter  is
       used to define new column names during import.

       The DBF database specification limits column names to 10 characters.  If the default DB is set to DBF and
       the input data contains longer column/field names, they will be truncated. If this  results  in  multiple
       columns  with  the  same  name then v.in.ogr will produce an error.  In this case you will either have to
       modify the input data or use v.in.ogr’s cnames parameter to rename columns to  something  unique.  (hint:
       copy  and  modify  the  list  given  with  the  error  message).  Alternatively, change the local DB with
       db.connect.

       When importing Esri Shapefiles the OGR library tries to read the LDID/codepage setting from the .dbf file
       and use it to translate string fields to UTF-8. LDID "87 / 0x57" is treated as ISO8859_1 which may not be
       appropriate for many languages. Unfortunately it is not clear what other values may be  appropriate  (see
       example below). To change encoding the user can set up SHAPE_ENCODING environmental variable or simply to
       define encoding value using encoding parameter. Note that recoding support is new for GDAL/OGR 1.9.0.

       Value for encoding also affects text recoding when importing DXF files. For other  formats  has  encoding
       value no effect.

       Option  key  specifies  column  name  used  for  feature  categories. This column must be integer. If not
       specified, categories numbers are generated starting with 1 and stored in the column named "cat".

       Starting with GDAL 1.11 the library supports multiple geometry columns in OGR. By default v.in.ogr  reads
       all  geometry  columns  from given layer. The user can choose desired geometry column by geometry option,
       see example below.

EXAMPLES

       The command imports various vector formats:

   SHAPE files
       v.in.ogr input=/home/user/shape_data/test_shape.shp output=grass_map
       Alternate method:
       v.in.ogr input=/home/user/shape_data layer=test_shape output=grass_map
       Define encoding value for attribute data (in this  example  we  expect  attribute  data  in  Windows-1250
       encoding; ie. in Central/Eastern European languages that use Latin script, Microsoft Windows encoding).
       v.in.ogr input=/home/user/shape_data/test_shape.shp output=grass_map encoding=cp1250

   MapInfo files
       v.in.ogr input=./ layer=mapinfo_test output=grass_map

   Arc Coverage
       We import the Arcs and Label points, the module takes care to build areas.
       v.in.ogr input=gemeinden layer=LAB,ARC type=centroid,boundary output=mymap

   E00 file
       See also v.in.e00.

       First  we  have  to  convert  the E00 file to an Arc Coverage with ’avcimport’ (AVCE00 tools, use e00conv
       first in case that avcimport fails):
       avcimport e00file coverage
       v.in.ogr input=coverage layer=LAB,ARC type=centroid,boundary output=mymap

   SDTS files
       You have to select the CATD file.
       v.in.ogr input=CITXCATD.DDF output=cities

   TIGER files
       v.in.ogr input=input/2000/56015/ layer=CompleteChain,PIP output=t56015_all \
       type=boundary,centroid snap=-1

   PostGIS tables
       Area example:
       v.in.ogr input="PG:host=localhost dbname=postgis user=postgres" layer=polymap \
       output=polygons type=boundary,centroid

   Oracle Spatial maps
       Note that you have to set the environment-variables ORACLE_BASE, ORACLE_SID,  ORACLE_HOME  and  TNS_ADMIN
       accordingly.
       v.in.ogr dsn=OCI:username/password@database_instance output=grasslayer layer=roads_oci

   Multiple geometry columns
       This  example  shows  how  to  work  with data which contain multiple geometry per feature. The number of
       geometry columns per feature can be checked by v.external together with -t flag.
       v.external -t input=20141130_ST_UKSH.xml.gz
       ...
       Okresy,point,1,DefinicniBod
       Okresy,multipolygon,1,OriginalniHranice
       Okresy,multipolygon,1,GeneralizovaneHranice
       ...
       In our example layer  "Okresy"  has  three  geometry  columns:  "DefinicniBod",  "OriginalniHranice"  and
       "GeneralizovanaHranice".  By  default  v.in.ogr  reads data from all three geometry columns. The user can
       specify desired geometry column by geometry option, in this case the module will read geometry only  from
       the  specified  geometry  column.  In the example below, the output vector map will contain only geometry
       saved in "OriginalniHranice" geometry column.
       v.in.ogr input=20141130_ST_UKSH.xml.gz layer=Okresy geometry=OriginalniHranice

WARNINGS

       If a message like "WARNING: Area size 1.3e-06, area not imported." appears, the min_area may be  adjusted
       to  a  smaller  value so that all areas are imported. Otherwise tiny areas are filtered out during import
       (useful to polish digitization errors or non-topological data).

       If a message like "Try to import again, snapping with at least 1e-008: ’snap=1e-008’" appears,  then  the
       map to be imported contains topological errors. The message suggests a value for the snap parameter to be
       tried. For more details, see above in Topology Cleaning.

ERROR MESSAGES

       DBMI-DBF driver error: SQL parser error: syntax error, unexpected DESC, expecting NAME processing ’DESC’
           indicates that a column name corresponds to a reserved SQL word (here: ’DESC’).  A  different  column
           name should be used. The cnames parameter can be used to assign different column names on the fly.

       Projection of dataset does not appear to match the current location.
           You  need  to  create  a  location  whose  projection  matches the data you wish to import. Try using
           location parameter to create a new location based upon the projection information  in  the  file.  If
           desired, you can then re-project it to another location with v.proj.

REFERENCES

           •   OGR vector library

           •   OGR vector library C API documentation

SEE ALSO

         db.connect,  v.clean,  v.extract,  v.build.polylines,  v.edit, v.external, v.import, v.in.db, v.in.e00,
       v.out.ogr

       GRASS GIS Wiki page: Import of Global datasets

AUTHORS

       Original author: Radim Blazek, ITC-irst, Trento, Italy
       Location and spatial extent support by Markus Neteler and Paul Kelly
       Various improvements by Markus Metz
       Multiple geometry columns support by Martin Landa, OSGeoREL, Czech Technical University in Prague,  Czech
       Republic

       Last changed: $Date: 2016-01-13 10:20:46 +0100 (Wed, 13 Jan 2016) $

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

       © 2003-2016 GRASS Development Team, GRASS GIS 7.0.3 Reference Manual