NAME
v.in.shape - Read an ArcView Shapefile
(GRASS Vector Program)
SYNOPSIS
v.in.shape
v.in.shape[-loud]
input=name
[output=name]
[verbose=debug level]
[logfile=name]
[snapdist=snap distance]
[scale=orig. scale]
[attribute=category number]
[label=category label]
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
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 current version is more robust than the module available up to Spring 2002.
The emphasis is now to concentrate on maintaining an effective shape file import filter.
To assist this, features that are really extensions of the basic aim have been removed.
Selection of features with particular attributes can still be extracted to a new file
with v.extract. There is also less need for posterior error correction now, as
the current module filters out some potentially problematic shapes at the point of
import, and so, will always insert incoming data into the final map. If a map fails to
build because of topological errors, the problem can be tracked down using v.digit
and fixed. Formerly, the module attempted many kinds of fixes, however
there were many complaints about imported maps being modified or corrupted by the process,
so we now leave the fixing of such errors to the user.
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
still needs some improvement).
OPTIONS
Flags:
- -l
- Force an area (polygon theme) import to be imported as lines as is. This
option can be used to create an outline of the original boundaries even if the map
is bad. This option is ignored for other types of import.
- -o
- Allow over-write of existing vector map.
- -u
- If the record number is used as the attribute, several 'parts' of the same
'shape' will have the same value when these are split on import to GRASS which
does not currently support compound objects. This may be what you want, but it might
not. To assign a unique and sequential record number, as attribute, to each area
choose this option. So, this option is ignored if the attribute is set.
Note: This can cause a subtle difference even if applied to coverages
without compound objects, as it always applies a sequential ID value to each successively
imported object. Without the option, it is the record number in the original that is
used, which can skip values if there are NULL shapes, because GRASS ignores the latter.
This may be important if you plan to use the attribute as a row ID in an external database
or dbmi.
- -d
- List fields in DBF file
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 (minimal report of fatal errors and essential warnings) and 3
(very verbose log - reports most data transfer operations and some intermediate steps).
The default is 1.
- logfile=filename
- Name of file[path] where log info will be written. By default, log info is directed to
stderr, which is also used (with a warning) if the log filepath is invalid or
not writable.
- 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. This is still not quite right, but
errors caused by it are astronomically unlikely, and are easily fixed manually,
which must be set off against the import process increasing in duration by a
factor of several if the snapping procedure was perfectly correct. Really
effective snapping must await the development of spatial query functions.
Therefore it will not be changed at this stage.
- 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. The value affects some behaviour of
v.digit including proper building, so may have to be played with.
Of course it can be reset by v.digit following import.
- 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.
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 is now imported, but in
the GRASS 5.0.x vector model, these vector 'points' have limited utility.The
module s.in.shape imports
site data in a form that may be found more useful.
The filtration process creates a large temp file to store the imported data
and a significant amount of metadata about the imported points. This can be
large
in large files. It is deleted if the import proceeds in a normal fashion, but will
be left 'dangling' on abnormal termination. This however is a quite general problem in the
current GRASS environment model. If disk space is available, this module will now import
an unlimited size of map, though it is currently slow on large maps, as there are many
disk read/write operations. This is compounded by the lengthy build process, which however
affects all vector map builds.
Area and perimeter fields in input data may no longer
be quite correct if the lines have been adjusted to correct topology problems.
But if the user has not modified the file, the values should be correct. If in
doubt, GRASS's own modules may be used to generate dimensional data, for example
v.report
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 "-d"
flag to get the list of fields from the "map.dbf" file.
SEE ALSO
m.in.e00,
g.mapsets,
g.region,
v.digit,
v.proj,
s.in.shape,
v.support,
v.to.rast,
v.out.shape
v.extract
v.report
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.
Spring 2002: Rewrite of most of the code.
Last changed: $Date$