v.in.shape

NAME

v.in.shape - Read an ArcView Shapefile
(GRASS Vector Program)

SYNOPSIS

v.in.shape

v.in.shape[.pg] [-lbros] input=name [output=name] [mapset=name] [verbose=debug level] [logfile=name] [snapdist=snap distance] [sliver=min. angle] [scale=orig. scale] [attribute=category number] [label=category label] [select=field to use] [maxshapes=maximum number]

DESCRIPTION

The v.in.shape program is designed to import ArcView Shapefiles. v.in.shape will be run non-interactively if the user specifies program arguments on the command line. Alternately, the user can simply type:

v.in.shape or v.in.shape.pg

on the command line without program arguments. In this case, the user will be prompted for parameter values using the standard GRASS user interface described in the manual entry for parser.

FEATURES

By default Grass files created have the name extracted from the basename of the shapefile. This can be over-ridden by supplying a value to the output option, which must be a legal name.
The import filter attempts to correct some common errors that are frequently met with in shapefiles:
The snap distance, which always has a small default value if not supplied, creates a microgrid of cells in the import map region. Only one vertex is ever assigned to a particular cell. If a later vertex is added that is in the same cell, it is considered co-incident with the first. When a link is added between two vertices, it is recorded and the same link is not added twice. The snap distance is also used to define the co-incidence of other spatial entities, for example edges of bounding boxes. This snap distance has no relation to the snap distance defined for the dig_plus map. (This needs some improvement).
The sliver tolerance defines a minimum angle between two lines, where the lines would be considered distinct. Lines closer than this are considered colinear, and under some circumstances, the import attempts to filter out extra, overlapping lines. This often helps where the boundaries of two adjacent polygons are not alligned properly in some way.
Duplicate rings are removed.

OPTIONS

Flags:

-l: List the fields contained in the DBF file associated with the input shapefile, then exit.
-b: Display bounds of map (north, south, east, west coordinates), then exit.
-r: Create a reject lines file. During import some lines are not imported for a variety of reasons.
-o: Allow over-write of existing vector map.
-s: Select shapes to extract based on a field
-p: Dump the fields of the shapefile from DBF to a postgres table.
*NOTE: This option is only available with v.in.shape.pg

Parameters:

input=filename: Name of input shape file. Provide a full path name or the name of a file in the current directory. Any of the full pathname, basename, or prefix only will suffice.
output=filename: Name of vector map to be created (default: prefix of shape file). By default prefix of shape file name is used.
verbose=integer: Number between 0 (no trace of what's happening) and 9 (very verbose log). Name of file where log info will be written. By default log info are directed to stderr.
snapdist=fp-number: A grid resolution can be defined within which adjacent vertices will snap.
Note:The vertices do not snap to the grid. All the vertices inside a grid cell snap to one of their number (usually the first). This value defaults to 1.0e-10 ground units. In fact, it will never allow a value that is less.
sliver=fp-number: A minimum angle can be defined for one link to subtend others at a given node. If the angle between two lines is less than this, they will be treated as colinear. This can be useful as the module now has features which attempt to correct some common topological errors that occur in the immediate vicinity of nodes. If you can be confident that true angles between adjacent arcs radiating from the same node cannot be less than a certain value, you can specify that value here, and some errors may be automatically corrected. This defaults to .0001 degrees. In fact it will never allow a value that is less.
scale=integer: This sets an original scale that will be specified in the header of the vector map file produced. It can be edited later with v.digit. The value defaults to 1:2400
attribute=name: Name of the input field to use as the category number in dig_att. Defaults to using the record ID number as a category value if no value is assigned or a non-numeric field is given. If the field is floating-point the value is rounded to the nearest integer.
label=name: Name of the input field to use as the category label in dig_cats. Only writes out results if a meaningful category field is given, otherwise no action is taken. If the same attribute is re-assigned a new category, the value is over-written.
select=field:value: Name of dbf-file field to use for selection. The format of the filter is select=: as above, but the -s flag is required also.
Example:
v.in.shape -s input=map select=FOLIE:118 label=ALIASFOLIE imports only shape vectors with value "118" in dbf-table field "FOLIE".
This feature may be used for selective data import.

maxshapes=value

Useful mainly for debug purposes, or to check that a map is good, imports only the first `value' shapes. The shapes counted include those filtered out by the `select' option, therefore this is the maximum number imported.

BUGS AND CAVEAT

There is no support for projection since the projection information is not stored in SHAPE files.

Multipatch data is not yet supported. Point data (sites) also is not handled by this module. New module s.in.shape imports site data.

Resource hog. The filtration process uses a lot of memory in large files. The size of files that can be imported sufficiently depends on the resources of the local system, but performance degrades rapidly when you go into swap. On a system with 128MB physical RAM, files of up to 4000 polygons are typically imported easily.

Area and perimeter fields in input data may no longer be quite correct if the lines have been adjusted to correct topology problems.

EXAMPLE

Example:
v.in.shape in=map.shp out=map attribute=OBJART label=ALIASFOLIE scale=25000
This command imports the shape file "map" into GRASS at scale of 1:25000 (since the scale is not stored in the shape file). "attribute" is the field name containing the record ID (if not set, internal numbering will be done). "label" is the field containing the associated text labels. Use the "-l" flag to get the list of fields from the "map.dbf" file.

AUTHORS

Frank Warmerdam (warmerda@home.com)
Based on Shapelib (http://gdal.velocet.ca/projects/shapelib/).

Markus Neteler
added category support

David Gray
preprocessing to provide correct handling of polygon edges, labels and correction of some topological errors. Also some new options q.v.

Last changed: $Date$