NAME
v.in.sdts - Imports SDTS vector data, conforming to the Topological
Vector Profile, into GRASS, creating GRASS vector map(s) and associated
attribute files ready to be installed in a relational database.
(GRASS Vector Data Import/Processing Program)
SYNOPSIS
v.in.sdts
v.in.sdts help
v.in.sdts [-il] catd=name [output=name] [dbpath=name] [domain=name] [map=name]
[theme=name] [manifold=name]
DESCRIPTION
v.in.sdts creates one or more GRASS vector maps in the current mapset
from a Spatial Data Transfer Standard dataset conforming to the Topological
Vector Profile (TVP). The program generates GRASS dig, dig_att,
and dig_cats files. Also, if requested, files of attributes in database-ready form
are created, along with scripts to create an approprate SQL-compliant
relational database,
and load the attribute files into the new database. Special database-ready
files of tables linking the attributes to the GRASS vector map layer or
layers are also generated.
The source SDTS dataset must be in the user's current directory. The files
that make up the dataset are listed in the dataset's Catalog/Directory file
(CATD); this file is specified by the user with the catd parameter.
v.in.sdts creates maps in your current mapset, and will only import map data if there is correspondence between the current mapset's coordinate system
and that of the transfer set; in addition, for UTM (and State Plane), Zone
designations must match. These specifications can be displayed be running
v.in.sdts in "Information only" mode. "Information only" mode is
automatically
put in effect when there is a mis-match between source and target coordinate
systems.
An SDTS dataset may consist of one or several distinct map layers (or
"2-D manifolds", in SDTS terminology), coinciding with one or more
partitions of the earth's surface. If a dataset contains more than one
map layer, the grouping of object data into individual map layers, and of
groups of map layers, is specified in the Catalog/Spatial Domain (CATS) file,
in terms of "domain", "map", "theme", and/or "manifold" ("aggregate object").
If available, this information is displayed to the user in "Information
Only" mode. The user can then either
(1) import all the map layers in a
transfer at once, or
(2) select a subset of the transfer consisting of one
or more maps by specifying a domain name, map name, etc.
COMMAND LINE OPTIONS
Flags:
- -i
- "Information-only" mode. Information about the dataset and any individual
map layers in the dataset are displayed. No map layers or attribute files
are generated. Information displayed includes basic identifying data
(TITLE of transfer dataset, map date, dataset creation date, scale,
coordinate system, etc.). For individual maps, any names found in the
CATS file specifying map, theme, domain, manifold, are given. Bounding
coordinates for each map layer are also printed.
The program will also run in "information only" mode if (1) no output name
is specified, or (2) the coordinate system, or, in the case of UTM and State
Plane, Zone, of the dataset to be imported does not match the current mapset.
- -l
- Import object link table(s) only; do not create attribute tables. If this flag is set, and if dbpath is set, only the vector map
(dig, dig_att, and dig_cats) and the file containing the
database-ready
table linking the vector map with the attribute tables will be created;
the attribute files themselves will not be created. This option is useful
if the user wants to selectively import data layers from an SDTS dataset
with multiple maps. One map could be imported with its object link table and
the full set of attributes; subsequent layers imported with the "-l"
option would avoid recopying the full set of attributes.
Parameters:
- catd=name
- Full name of SDTS file containing the Catalog/Directory (CATD) module
for the source dataset. The file name format is specified by SDTS and the
TVP as xxxxCATD.DDF, where xxxx are 4 digits or upper-case letters
or any combination therof. The CATD file must be located along with the
rest of the SDTS dataset in the current directory. The CATD file
contains a listing of all the dataset files, and is thus the necessary
starting point for the transfer process.
Note that the same four-character prefix of the CATD file is used
for all files in the SDTS dataset. This prefix is also used by
v.in.sdts for the naming of the output attribute files (see
The GRASS-SDTS User Guide for details.)
- output=name
- name for output vector map layer. If the SDTS dataset contains
multiple maps, and if no particular one is specified, causing
all the maps to be imported, maps will be distinguished by name
plus numeric suffix. If not specified the module runs
in "information mode" (-i flag) and no output is written.
- dbpath=name
- full path to location for placement of database-ready attribute files
preparatory to their installation in a relational database. Path
must exist and be writable by the user. Setting the dbath parameter
causes database-ready files to be created; otherwise they are not created.
- domain=name
-
- map=name
-
- theme=name
-
- manifold=name
- if one or more domain, map, theme, or manifold ("aggregate object")
names are given in the SDTS dataset Catalog/Spatial Domain (CATS)
file, map layers so designated can be selected with the appropriate
parameter. "Information only" mode lists any such names found in
the CATS file.
SPATIAL OBJECTS IN SDTS AND GRASS
SDTS and the Topological Vector Profile define two basic types of spatial
objects: simple spatial objects, i.e., lines, polygons, nodes, etc.; and
composite objects, which are made up of one or more other simple and/or
composite spatial objects. SDTS composite objects, which GRASS cannot
handle directly, are imported as records in RDBMS-ready tables. Details on
the mapping of simple and composite spatial objects between SDTS and GRASS
may be found in the GRASS-SDTS User Guide.
SDTS ATTRIBUTE IMPORT
Only a brief explanation of SDTS attributes and v.in.sdts's handling of
them is given here. See the GRASS/SDTS User Guide for details.
SDTS is capable of substantial attribute complexity. SDTS distinguishes
between two basic kinds of attributes: primary attributes are related
directly to spatial objects (simple or composite), while secondary
attributes are related to primary or to other secondary attributes.
In SDTS, attributes are stored in relational tables, and spatial objects
may be linked to multiple attributes in one or more different
attribute tables. The schema of an SDTS dataset--the number and kind of
attribute fields and attribute tables, and the relationships among attributes
and objects--is not predefined by the Standard or the Profile, but is
determined by the producer of the dataset.
For most kinds of data likely to be available through SDTS, optimal access
requires use of GRASS with a relational database management system. In
support of this, v.in.sdts imports SDTS attribute tables in a form ready
for use with your RDBMS. It also produces SQL-compatible scripts to set up
the relational database and install the data.
dig_att and dig_cats files: The program does generate dig_att and
dig_cats files, and for relatively
simple SDTS datasets, i.e., those with one-to-one object-attribute
relationships with all object attributes in a single attribute table,
an associated relational database is not necessary. In addition, for more
complex datasets, the dig_att and dig_cats files are constructed in such a
way as to facilitate post-import incorporation of selected data from the
attribute files for use without recourse to a relational database.
Specifically, the contents of the generated dig_att and dig_cats
files are as follows:
dig_att
Contains an entry for each attributed non-composite object (line,
polygon, point). each entry will be assigned a unique category integer
value. These integers, or feature-IDs (FID), also uniquely identify
the same spatial objects, in the relational database object link table.
dig_cats
For datasets with one-to-one object-attribute relationships and a single
object-related attribute module, only one database-ready "object-attribute"
file is created, and the dig_cats records are given the same content,
as the generated database-ready file. Record structure is as follows:
FID | obj_code | attr_code | attr. field 1 |...| attr. field n |
(obj_code and attr_code are codes, derived from record IDs in the
SDTS dataset, which function as keys in the import relational database. See
The GRASS-SDTS User Guide for details.)
For other datasets, the dig_cats file is identical in content
to the generated GRASS-database object link table, and records would have the
structure:
FID | obj_code or FID | obj_code | attr_code
SDTS IMPORT AND USE OF A RELATIONAL DATABASE
Full discussion of this topic may be found in the GRASS-SDTS User Guide.
FILE NAMES
vector map name: if the SDTS dataset contains a single map layer, or if a
a single map layer from a multiple-map dataset, the name specified in
output is used as is. Otherwise, the name is extended with integers to
specify the individual layers.
relational database file names: see the GRASS-SDTS User Guide.
SEE ALSO
m.sdts.read,
v.in.sdts,
v.out.sdts,
v.sdts.dp.cp,
v.sdts.meta.cp,
v.sdts.meta
AUTHORS
David Stigberg, U.S.Army Construction Engineering
Research Laboratory
Tin Qian, University of Illinois
Last changed: $Date: 2002/06/17 09:41:45 $