NAME
v.to.pg - Export areas and lines from an existing vector
map to Postgres/PostGIS table. (GRASS-RDBMS Interface Display Program)
SYNOPSIS
v.to.pg
v.to.pg help
v.to.pg [-tfvp] [key=name] [tab=name]
map=name type=name
[where=name] [color=name] [rmap=name]
ALTERNATE
v.to.pg -s help
v.to.pg [-sfvp] sql=filename map=name
type=name [color=name] [rmap=name]
DESCRIPTION
v.to.pg exports vectors from an existing vector map based on the
unique values in a database column (or optionally all vectors without referencing
to any existing table, see -t option). Each row returned by a user constructed
database query will be associated with a vector feature which may be drawn
on the graphics display in X-windows. The user can control the
color of the vector draw by specifying a color on the command line.
As result, a new Postgres table table_bnd or table_arc
(or table_mpoly and table_mstring for PostGIS) is created
to hold areas as internal type "polygon" and lines as "open path", where
table is the tab parameter. Besides these elements in fields
called boundary or segment, the table would also have the
category field (named after key parameter), case number this category
occurred in map (as field called 'num'), and an extra boolean field 'ex'
for 'true' if the polygon is external and 'f' if it is a hole for table_bnd
only.
For PostGIS, the difference is that types of the imported entities are
POLYGON (i.e., with "holes" all in one POLYGON) and LINESTRING, respectively.
The fields are called grass_poly and grass_line. There is
no need to define whether a polygon is internal ("hole") or external, in
this case, therefore there is no field 'ex'. Optionally, the user can specify
a raster map as rmap (usually DEM) to extract z-coordinate for vectors
to be exported.
COMMAND LINE OPTIONS
Flag:
-
-t
-
Export all map vectors without reference to existing table ('where' clause
ignored).
-
-f
-
Fill polygons selected on the query criteria.
-
-v
-
Verbose mode with statistics on the completion of the insertions.
-
-p
-
Create and populate PostGIS GEOMETRY format table instead of normal Postgres
geometry types.
Parameters:
-
key=databasecolumnname
-
Column in table "tab" of the currently selected database containing values
corresponding to the vector maps category values. Table is designated on
the command line by tab=tablename and vector is given on the command line
by map=mapname.
-
tab=databasetablename
-
Table in the currently selected database containing a column which has
values corresponding to vector category values in the map designated by
map=map.
-
where=SQLwhereclause
-
SQL "where" clause which specifies the query criteria to be used in subsetting
the database. The field names specified in the where option must indicate
the column(s) to be used, the operators to be used in the evaluation and
the values which the data in the column will be evaluated against.
If the database column used as the selection criteria is a character field
then the associated value must be placed in quotes. To determine the data
types associated with columns in the currently selected database use the
g.column.pg
command with the -v flag.
Queries which are more complex are best implemented using the -s
flag and a prepared SQL file.
-
map=map
-
Name of an existing vector map with category values which correspond to
values in a specified column in the currently selected database.
-
rmap=rastermap
-
Name of an existing raster map where pixel values correspond to
the Z-coordinate in PostGIS vector geometry formats.
-
color=name
-
Color to draw vectors in
-
Colors: red, orange, yellow, green, blue, indigo, violet, magenta, brown,
gray, white, black
-
type=area,line
-
Type of the coverage to export.
ALTERNATE COMMAND LINE USAGE
The alternate command line usage is provided to simplify the process of
retrieving information from more than one table in the query criteria.
The alternate command line structure is selected using the the [-s]
flag on the command line. When using this flag the user must include the
name of a text file on the command line as well. This file must include
a complete, well formed SQL SELECT statement specifying the query criteria
to retrieve values which correspond to category values in a GRASS data
layer.
Flag:
-
-s
-
SQL select statements are input from a prepared file
-
-f
-
Fill polygons selected on the query criteria
-
-v
-
Verbose mode with statistics on the completion of the insertions.
-
-p
-
Create and populate PostGIS GEOMETRY format table instead of normal Postgres
geometry types.
-
Parameters:
-
sql=filename
-
SQL statements specifying well formed selection criteria.
-
map=name
-
Name of an existing vector map
-
rmap=rastermap
-
Name of an existing raster map where pixel values correspond to
the Z-coordinate in PostGIS vector geometry formats.
-
color=name
-
Color to draw vectors in
-
Colors: red, orange, yellow, green, blue, indigo, violet, magenta, brown,
gray, white, black
-
type=area,line
-
Type of the coverage to export.
EXAMPLE:
1. v.to.pg -f key=rec_id map=kuruma_id tab=info_kuruma type=area
where='type_id >32 and type_id < 38' color=red
Result: only polygons with type in 33-37 range would be inserted
in table info_kuruma_bnd and displayed in red color.
2. v.to.pg -v -s -f -p sql=oak.sql map=kuruma_id type=area
oak.sql is:
select rec_id from info_kuruma where type_id > 32 and type_id <38;
Result: this command would do the same as in the first example,
some information printed on screen. However, the result table would be
in PostGIS format.
BUGS
none
NOTE
This program requires the Postgres database software.
The 'total' mode of import (i.e., bypassing reference DB table
and categories count in map) results in that the field 'num' in output
table would only count vectors from beginning to end.
SEE ALSO
g.column.pg, g.select.pg,
g.stats.pg,
g.table.pg,
d.rast.pg,
d.site.pg,
d.what.r.pg,
d.what.s.pg,
d.what.v.pg,
v.reclass.pg
AUTHOR
Alex Shevlakov (sixote@yahoo.com)