v.in.sdts

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.

AUTHORS

David Stigberg, U.S.Army Construction Engineering Research Laboratory
Tin Qian, University of Illinois

Last changed: $Date$