.TH v.out.ascii 1grass "" "GRASS 6.4.2" "Grass User's Manual"
.SH NAME
\fI\fBv.out.ascii\fR\fR  - Converts a GRASS binary vector map to a GRASS ASCII vector map.
.SH KEYWORDS
vector, export
.SH SYNOPSIS
\fBv.out.ascii\fR
.br
\fBv.out.ascii help\fR
.br
\fBv.out.ascii\fR [-\fBor\fR] \fBinput\fR=\fIname\fR  [\fBoutput\fR=\fIname\fR]   [\fBformat\fR=\fIstring\fR]   [\fBfs\fR=\fIcharacter\fR]   [\fBdp\fR=\fIinteger\fR]   [\fBlayer\fR=\fIinteger\fR]   [\fBcolumns\fR=\fIname\fR[,\fIname\fR,...]]   [\fBwhere\fR=\fIsql_query\fR]   [--\fBverbose\fR]  [--\fBquiet\fR] 
.SS Flags:
.IP "\fB-o\fR" 4m
.br
Create old (version 4) ASCII file
.IP "\fB-r\fR" 4m
.br
Only export points falling within current 3D region (points mode)
.IP "\fB--verbose\fR" 4m
.br
Verbose module output
.IP "\fB--quiet\fR" 4m
.br
Quiet module output
.PP
.SS Parameters:
.IP "\fBinput\fR=\fIname\fR" 4m
.br
Name of input vector map
.IP "\fBoutput\fR=\fIname\fR" 4m
.br
Path to resulting ASCII file or ASCII vector name if '-o' is defined
.IP "\fBformat\fR=\fIstring\fR" 4m
.br
Output format
.br
Options: \fIpoint,standard\fR
.br
Default: \fIpoint\fR
.IP "\fBfs\fR=\fIcharacter\fR" 4m
.br
Field separator (points mode)
.br
Default: \fI|\fR
.IP "\fBdp\fR=\fIinteger\fR" 4m
.br
Number of significant digits (floating point only)
.br
Options: \fI0-32\fR
.br
Default: \fI8\fR
.IP "\fBlayer\fR=\fIinteger\fR" 4m
.br
Layer number
.br
A single vector map can be connected to multiple database tables. This number determines which table to use.
.br
Default: \fI1\fR
.IP "\fBcolumns\fR=\fIname[,\fIname\fR,...]\fR" 4m
.br
Name of attribute column(s) to be exported (point mode)
.IP "\fBwhere\fR=\fIsql_query\fR" 4m
.br
WHERE conditions of SQL statement without 'where' keyword
.br
Example: income = 10000
.PP
.SH DESCRIPTION
\fIv.out.ascii\fR converts a GRASS vector map in binary format to a
GRASS vector map in ASCII format. Using
flag \fB-o\fR \fIv.out.ascii\fR output will be in old (version 4)
ASCII format.
.PP
If the \fBoutput\fR parameter is not given then the coordinates of any 
\fIpoint\fR data within the vector map is sent to stdout.
.SH NOTES
The \fIv.in.ascii\fR module performs
the function of \fIv.out.ascii\fR in reverse; i.e. it converts
vector maps in ASCII format to their binary format.  These two
companion module are useful both for importing and exporting vector
maps between GRASS and other software, and for transferring data
between machines.
.PP
If the \fBformat\fR parameter is set to \fBstandard\fR, a GRASS
ASCII vector map will be exported, which may contain a mix of
primitives including points, lines, boundaries, centroids, areas,
faces, and kernels. The beginning of the output ascii file will
contain a header listing any metadata for the input vector map, if
such metadata exists. An example of the \fBstandard\fR format is
given below.
.PP
The header is similar as the head file of vector binary format but
contains bounding box also. Key words are:
\fC
.DS
.br
ORGANIZATION
.br
DIGIT DATE
.br
DIGIT NAME
.br
MAP NAME
.br
MAP DATE
.br
MAP SCALE
.br
OTHER INFO
.br
ZONE
.br
WEST EDGE
.br
EAST EDGE
.br
SOUTH EDGE
.br
NORTH EDGE
.br
MAP THRESH
.br
.DE
\fR
.PP
The body begins with the row:
\fC
.DS
.br
VERTI:
.br
.DE
\fR
followed by records of primitives:
\fC
.DS
.br
TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
.br
 X Y [Z]
.br
....
.br
 X Y [Z]
.br
[ LAYER CATEGORY]
.br
....
.br
[ LAYER CATEGORY]
.br
.DE
\fR
Everything above in [ ] is optional. 
.PP
The primitive codes are as follows:
.RS
.IP
\(cqP': point
.IP
\(cqL': line
.IP
\(cqB': boundary
.IP
\(cqC': centroid
.IP
\(cqF': face (3D boundary)
.IP
\(cqK': kernel (3D centroid)
.IP
\(cqA': area (boundary) - better use 'B'; kept only for backward compatibility
.RE
The coordinates are listed following the initial line containing the
primitive code, the total number of vectors in the series, and (optionally)
the number of categories (1 for a single layer, higher for multiple layers).
Below that 1 or several lines follow to indicate the layer number and
the category number (ID).
.br
The order of coordinates is
\fC
.DS
.br
  X Y [Z]
.br
.DE
\fR
In pre-GRASS 6 versions of the ASCII file, the order of coordinates is:
\fC
.DS
.br
Y X
.br
.DE
\fR
If old version is requested, the \fBoutput\fR files from \fIv.out.ascii\fR is placed 
in the $LOCATION/$MAPSET/dig_ascii/ and $LOCATION/$MAPSET/dig_att directory.
.PP
Only features with a category number will be
exported. Use \fIv.category\fR to add them if needed.
.PP
\fIv.out.ascii\fR does not copy the \fIdig_cats\fR file
associated with the binary vector \fIinput\fR map to the
new \fIoutput\fR file name. The user must copy
the \fIdig_cats\fR file to the new \fIoutput\fR name if this is
desired (e.g. using the UNIX \fIcp\fR command).
.PP
It is possible to output the coordinates of vertices in a non-points vector
feature by first converting the vector feature to a points map with 
\fIv.to.points\fR and then exporting with \fIv.out.ascii\fR in 
\fIpoints\fR mode.
.SH EXAMPLES
.SS Standard mode
.PP
\fC
.DS
.br
v.out.ascii input=quads format=standard
.br
.br
ORGANIZATION: US Army Const. Eng. Rsch. Lab
.br
DIGIT DATE:   May 1987
.br
DIGIT NAME:   grass
.br
MAP NAME:     Quads
.br
MAP DATE:     May 1987
.br
MAP SCALE:    24000
.br
OTHER INFO:
.br
ZONE:         13
.br
MAP THRESH:   18.288000
.br
VERTI:
.br
B  4
.br
 599587.1820962 4914067.53414294
.br
 589639.15126831 4913922.5687301
.br
 589440.96838162 4927803.62500018
.br
 599375.87959179 4927959.83330436
.br
B  2
.br
 599375.87959179 4927959.83330436
.br
 599587.1820962 4914067.53414294
.br
B  4
.br
 599587.1820962 4914067.53414294
.br
 609541.5508239 4914236.0597482
.br
 609316.10665227 4928116.8490555
.br
 599375.87959179 4927959.83330436
.br
C  1 1
.br
 594125.63    4921115.58
.br
 1     1
.br
C  1 1
.br
 604433.84    4921087.1
.br
 1     2
.br
.DE
\fR
.SS Point mode
\fC
.DS
.br
v.out.ascii input=quads format=point
.br
.br
594125.63|4921115.58|1
.br
604433.84|4921087.1|2
.br
.DE
\fR
\fC
.DS
.br
v.out.ascii input=archsites format=point where="cat > 5 and cat <= 8" columns=str1
.br
.br
600375|4925235|6|Prairie Site
.br
606635|4920773|7|Jensen Pass
.br
595755|4925300|8|No Name
.br
.DE
\fR
.SH SEE ALSO
\fI
v.category,
v.in.ascii,
v.to.points
.br
GRASS SQL interface
\fR
.SH AUTHORS
Michael Higgins, 
U.S. Army Construction Engineering 
Research Laboratory
.br
James Westervelt, 
U.S. Army Construction Engineering 
Research Laboratory
.br
Radim Blazek, ITC-Irst, Trento, Italy
.br
Attribute selection added by Martin Landa, CTU in Prague, Czech Republic (2008/12)
.PP
\fILast changed: $Date: 2011-11-08 10:42:51 +0100 (Tue, 08 Nov 2011) $\fR
.PP
Full index
.PP
© 2003-2011 GRASS Development Team