GRASS ASCII vector format explained in seperate manual page

manual page of v.in.ascii, v.out.ascii and v.edit update accordingly


git-svn-id: https://svn.osgeo.org/grass/grass/trunk@48436 15284696-431f-4ddb-bdfa-cd5b030d7da7

lib/vector/vectorascii.html

@@ -0,0 +1,141 @@
+<!-- meta page description: GRASS ASCII vector format specification -->
+<!-- meta page index: vector -->
+
+A vector map in GRASS native vector format may contain a mix of
+<i>primitives</i> including points, lines, boundaries, centroids, areas,
+faces, and kernels. The GRASS ASCII vector format may contain also 
+a <i>header</i> with various metadata (see example below).
+
+<p>
+The header is similar as the head file of vector binary format but
+contains bounding box also. Key words are:
+
+<div class="code"><pre>
+ORGANIZATION
+DIGIT DATE
+DIGIT NAME
+MAP NAME
+MAP DATE
+MAP SCALE
+OTHER INFO
+ZONE
+WEST EDGE
+EAST EDGE
+SOUTH EDGE
+NORTH EDGE
+MAP THRESH
+</pre></div>
+
+<p>
+The body begins with the row:
+
+<div class="code"><pre>
+VERTI:
+</pre></div>
+
+followed by records of primitives:
+
+<div class="code"><pre>
+TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
+ X Y [Z]
+....
+ X Y [Z]
+[ LAYER CATEGORY]
+....
+[ LAYER CATEGORY]
+</pre></div>
+
+Everything above in <tt>[&nbsp;]</tt> is optional. 
+
+<p>
+The primitive codes are as follows:
+<ul>
+  <li>'P': point</li>
+  <li>'L': line</li>
+  <li>'B': boundary</li>
+  <li>'C': centroid</li>
+  <li>'F': face (3D boundary)</li>
+  <li>'K': kernel (3D centroid)</li>
+  <li>'A': area (boundary) - better use 'B'; kept only for backward compatibility</li>
+</ul>
+
+The coordinates are listed following the initial line containing the
+primitive code, the total number of coordinates 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).
+
+<p>
+The order of coordinates is
+<div class="code"><pre>
+X Y [Z]
+</pre></div>
+
+In pre-GRASS 6 versions of the ASCII format, the order of coordinates
+was different:
+<div class="code"><pre>
+Y X
+</pre></div>
+
+<p>
+Latitude/Longitude data may be given in a number of ways.
+Decimal degrees must be positive or negative instead of using a hemisphere
+letter. Mixed coordinates must use a hemisphere letter. Whole minutes and
+seconds must always contain two digits (example: use <tt>167:03:04.567</tt>;
+and not <tt>167:3:4.567</tt>). 
+<br><br>
+Acceptable formats:<br>
+<i>key: D=Degrees; M=Minutes; S=Seconds; h=Hemisphere (N,S,E,W)</i>
+<ul>
+  <li><tt>(+/-)DDD.DDDDD</tt>
+  <li><tt>DDDh</tt>
+  <li><tt>DDD:MMh</tt>
+  <li><tt>DDD:MM.MMMMMh</tt>
+  <li><tt>DDD:MM:SSh</tt>
+  <li><tt>DDD:MM:SS.SSSSSh</tt>
+</ul>
+
+<h2>EXAMPLES</h2>
+
+<div class="code"><pre>
+ORGANIZATION: GRASS Development Team
+DIGIT DATE:   1/9/2005
+DIGIT NAME:   -
+MAP NAME:     test
+MAP DATE:     2005
+MAP SCALE:    10000
+OTHER INFO:   Test polygons
+ZONE:  0
+MAP THRESH:   0.500000
+VERTI:
+B  6
+ 5958812.48844435 3400828.84221011
+ 5958957.29887089 3400877.11235229
+ 5959021.65906046 3400930.7458436
+ 5959048.47580612 3400973.65263665
+ 5959069.92920264 3401032.64947709
+ 5958812.48844435 3400828.84221011
+C  1 1
+ 5958952.42189184 3400918.23126419
+ 1 20
+B  4
+ 5959010.9323622 3401338.36037757
+ 5959096.7459483 3401370.54047235
+ 5959091.38259917 3401450.99070932
+ 5959010.9323622 3401338.36037757
+C  1 1
+ 5959063.08352122 3401386.98533277
+ 1 21
+</pre></div>
+
+In this case the vector map contains 2 boundaries (first boundary with
+6 vertices, second with 4 vertices) without category and 2 centroids
+with category number 20 and 21 (layer 1).
+
+<h2>SEE ALSO</h2>
+
+<em>
+  <a href="v.in.ascii.html">v.in.ascii</a>,
+  <a href="v.out.ascii.html">v.out.ascii</a>,
+  <a href="v.edit.html">v.edit</a>
+</em>

vector/v.edit/v.edit.html

@@ -180,18 +180,23 @@ cat roads.txt | v.edit tool=create map=vectmap input=-
 
 <h3>Add new features to existing vector map</h3>
 
-Add point to the vector map (without header):
+Add a new point to the vector map (without header):
 
 <div class="code"><pre>
 echo "P 1 1
  640794 214874
- 1 1" | v.edit -n tool=add map=vectmap
+ 1 1" | v.edit -n tool=add map=vectmap input=-
 </pre></div>
 
+The input must be in <a href="vectorascii.html">GRASS ASCII vector
+format</a>.
+
+<p>
+
 Add new features read from standard input:
 
 <div class="code"><pre>
-v.out.ascii in=railroads format=standard | v.edit tool=add map=vectmap
+v.out.ascii in=railroads format=standard | v.edit tool=add map=vectmap input=-
 </pre></div>
 
 <h3>Delete selected features from vector map layer</h3>

vector/v.in.ascii/v.in.ascii.html

@@ -1,7 +1,8 @@
 <h2>DESCRIPTION</h2>
 
-<em>v.in.ascii</em> converts a vector map in ASCII format to a vector map in 
-binary format. The module may import two formats:
+<em>v.in.ascii</em> converts a vector map
+in <a href="vectorascii.html">GRASS ASCII vector format</a> to a
+vector map in binary format. The module may import two formats:
 <ul>
 <li><b>standard</b> contains all data types, each coordinate on one row</li>
 <li><b>point</b> (default) reads only points, each point defined on
@@ -12,12 +13,11 @@ binary format. The module may import two formats:
 </ul>
 
 <p>
-The <a href="v.out.ascii.html">v.out.ascii</a> GRASS module performs
-the function of <em>v.in.ascii</em> in reverse; i.e., it converts
-vector maps in binary format to ASCII format. These two companion
-programs are useful both for importing and exporting vector maps
-between GRASS and other software, and for transferring data between
-machines.
+<em><a href="v.out.ascii.html">v.out.ascii</a></em> performs the
+function of <em>v.in.ascii</em> in reverse; i.e., it converts vector
+maps in binary format to GRASS ASCII vector format. These two companion programs
+are useful both for importing and exporting vector maps between GRASS
+and other software, and for transferring data between machines.
 
 <h2>NOTES</h2>
  
@@ -37,133 +37,45 @@ may be explicitly declared along with the geometry columns using the
 <b>columns</b> parameter.
 
 <p>
-Latitude/Longitude data may be given in a number of ways.
-Decimal degrees must be positive or negative instead of using a hemisphere
-letter. Mixed coordinates must use a hemisphere letter. Whole minutes and
-seconds must always contain two digits (example: use <tt>167:03:04.567</tt>;
-and not <tt>167:3:4.567</tt>). 
-<br><br>
-Acceptable formats:<br>
-<i>key: D=Degrees; M=Minutes; S=Seconds; h=Hemisphere (N,S,E,W)</i>
-<ul>
-  <li><tt>(+/-)DDD.DDDDD</tt>
-  <li><tt>DDDh</tt>
-  <li><tt>DDD:MMh</tt>
-  <li><tt>DDD:MM.MMMMMh</tt>
-  <li><tt>DDD:MM:SSh</tt>
-  <li><tt>DDD:MM:SS.SSSSSh</tt>
-</ul>
-
-<p>
 Use the <b>-z</b> flag to convert ASCII data into a 3D vector map.
 
 <p>
-In special cases of data import, such as the import of large LIDAR datasets
-(millions of data points), it may be necessary to disable topology support
-(creating a GRASS vector level 1 vector map) due to memory constraints.
-This is done with the <b>-b</b> flag. As only very few vector modules
-support points data processing at vector level 1, usually topology is
-required (vector level 2). Therefore it is recommened that the user first
-try to import the data without creating a database (the <b>-t</b> flag)
-or within a subregion (the <b>-r</b> flag) before resorting the to
+In special cases of data import, such as the import of large LIDAR
+datasets (millions of data points), it may be necessary to disable
+topology support (vector level 1) due to memory constraints.  This is
+done with the <b>-b</b> flag. As only very few vector modules support
+points data processing at vector level 1, usually topology is required
+(vector level 2). Therefore it is recommened that the user first try
+to import the data without creating a database (the <b>-t</b> flag) or
+within a subregion (the <b>-r</b> flag) before resorting the to
 disabling of topology.
 
 <p>
-A GRASS ASCII vector map (in <b>standard format</b> mode) may contain a mix
-of primitives including points, lines, boundaries, centroids, areas,
-faces, and kernels. The GRASS ASCII vector format
-may contain a header with various metadata (see example below). 
-The header is not required if the <b>-n</b> flag is used.
-
-<p>The header is similar as the head file of vector binary format but
-contains bounding box also. Key words are:
-
-<pre>
-ORGANIZATION
-DIGIT DATE
-DIGIT NAME
-MAP NAME
-MAP DATE
-MAP SCALE
-OTHER INFO
-ZONE
-WEST EDGE
-EAST EDGE
-SOUTH EDGE
-NORTH EDGE
-MAP THRESH
-</pre>
-
-<p>The body begins with the row:
-
-<pre>
-VERTI:
-</pre>
-
-followed by records of primitives:
+If old version is requested, the <b>output</b> files
+from <em><a href="v.out.ascii.html">v.out.ascii</a></em> is placed in
+the <tt>$LOCATION/$MAPSET/dig_ascii/</tt>
+and <tt>$LOCATION/$MAPSET/dig_att</tt> directory.
 
-<pre>
-TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
- X Y [Z]
-....
- X Y [Z]
-[ LAYER CATEGORY]
-....
-[ LAYER CATEGORY]
-</pre>
+<h3>Import of files without category column</h3>
 
-Everything above in <tt>[&nbsp;]</tt> is optional. 
-
-<p>
-The primitive codes are as follows:
-<ul>
-<li>'P': point</li>
-<li>'L': line</li>
-<li>'B': boundary</li>
-<li>'C': centroid</li>
-<li>'F': face (3D boundary)</li>
-<li>'K': kernel (3D centroid)</li>
-<li>'A': area (boundary) - better use 'B'; kept only for backward compatibility</li>
-</ul>
-
-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
-<div class="code"><pre>
-  X Y [Z]
-</pre></div>
-
-In pre-GRASS 6 versions of the ASCII file, the order of coordinates is:
-<div class="code"><pre>
-Y X
-</pre></div>
-
-If old version is requested, the <b>output</b> files from <em>v.out.ascii</em> is placed 
-in the <tt>$LOCATION/$MAPSET/dig_ascii/</tt> and <tt>$LOCATION/$MAPSET/dig_att</tt> directory.
-
-<h3>Import of files without category ID column</h3>
-
-If the input file does not contain a vector ID column,
-there is the possibility to auto-generate these IDs (categories). 
-To automatically add an additional column named 'cat', the 
-<b>cat</b> parameter must be set to the virtual column number 0 
-(<tt>cat=0</tt>). This is the default action if the <b>cat</b> parameter
-is not set.
+If the input file does not contain a category column, there is the
+possibility to auto-generate these IDs (categories). To automatically
+add an additional column named 'cat', the <b>cat</b> parameter must be
+set to the virtual column number 0 (<tt>cat=0</tt>). This is the
+default action if the <b>cat</b> parameter is not set.
 
 <h3>Importing from a spreadsheet</h3>
 
-Data may be imported from many spreadsheet programs by saving the 
-spreadsheet as a comma separated variable (.csv) text file, and then 
-using the <b>fs=','</b> option with <em>v.in.ascii</em> in <b>points</b> mode.
-If the input file contains any header lines, such as column headings, the
-<b>skip</b> parameter should be used. These skipped header lines will be
-written to the map's history file for later reference (read with
-<tt>v.info&nbsp;-h</tt>). The skip option only works in <tt>points</tt> mode.
-<P>
+Data may be imported from many spreadsheet programs by saving the
+spreadsheet as a comma separated variable (.csv) text file, and then
+using the <b>fs=','</b> or <b>fs=comma</b> option
+with <em>v.in.ascii</em> in <b>points</b> mode.  If the input file
+contains any header lines, such as column headings, the
+<b>skip</b> parameter should be used. These skipped header lines will
+be written to the map's history file for later reference (read with
+<tt>v.info&nbsp;-h</tt>). The skip option only works in <b>points</b> mode.
+
+<p>
 Any line starting with the hash character ('<tt>#</tt>') will be treated as
 a comment and skipped completely if located in the main data file. If located
 in the header, as defined by the <b>skip</b> parameter, it will be treated as
@@ -171,13 +83,14 @@ a header line and written to the history file.
 
 <h3>Import of sexagesimal degree (degree, minutes, seconds, DMS)</h3>
 
-The import of DMS formatted degrees is supported (in this case no
-sign but N/S, E/W characters are used to indicate the hemispheres).
-While the positions are internally translated into decimal degrees
-during the import, the original DMS values are maintained in the
-attribute table. This requires both the latitude and
-the longitude columns to be defined as varchars(), not as numbers.
-A warning will be issued which can be ignored.
+The import of DMS formatted degrees is supported (in this case no sign
+but N/S, E/W characters are used to indicate the hemispheres).  While
+the positions are internally translated into decimal degrees during
+the import, the original DMS values are maintained in the attribute
+table. This requires both the latitude and the longitude columns to be
+defined as <tt>varchar()</tt>, not as numbers.  A warning will be
+issued which can be ignored. See <a href="vectorascii.html">GRASS
+ASCII vector format specification</a> for details.
 
 <h3>Importing only selected columns</h3>
 Although <em>v.in.ascii</em> doesn't have an option to specify which columns
@@ -198,7 +111,6 @@ cut -d&lt;the_field_separator_character&gt; -f&lt;comma-separated_list_of_column
 <h3>Example 1a) - standard format mode</h3>
 Sample ASCII polygon vector map for 'standard' format mode. 
 The two areas will be assigned categories 20 and 21. 
-The example can be tested in the Spearfish sample dataset:
 <p>
 <div class="code"><pre>
 echo "ORGANIZATION: GRASS Development Team
@@ -232,11 +144,11 @@ C  1 1
 </pre></div>
 
 <h3>Example 1b) - standard format mode</h3>
+
 Sample ASCII 3D line vector map for 'standard' format mode with simplified input
 (note the space field separator).
 Note the <b>-z</b> flag indicating 3D vector input, and the <b>-n</b> flag
 indicating no vector header should be expected from the input file.
-The example can be tested in the Spearfish sample dataset:
 
 <div class="code"><pre>
 echo "L 5 1
@@ -268,7 +180,7 @@ Import into GRASS:
 v.in.ascii input=coords.txt output=mymap
 </pre></div>
 As the <b>cat</b> option is set to 0 by default, an extra column 'cat'
-containing the IDs will be auto-generated.
+containing the category numbers will be auto-generated.
 
 <h3>Example 3 - point format mode</h3>
 
@@ -356,6 +268,8 @@ cat $MAPSET/group/$GROUP/POINTS | v.in.ascii out=$GROUP_gcp fs=space skip=3 \
 <h2>REFERENCES</h2>
 
 <a href="sql.html">SQL command notes</a> for creating databases
+<br>
+<a href="vectorascii.html">GRASS ASCII vector format</a> specification
 
 <h2>SEE ALSO</h2>
 

vector/v.out.ascii/v.out.ascii.html

@@ -1,7 +1,7 @@
 <h2>DESCRIPTION</h2>
 
 <em>v.out.ascii</em> converts a GRASS vector map in binary format to a
-GRASS vector map in ASCII format. Using
+GRASS vector map in <a href="vectorascii.html">ASCII format</a>. Using
 flag <b>-o</b> <em>v.out.ascii</em> output will be in old (version 4)
 ASCII format.
 
@@ -19,100 +19,27 @@ maps between GRASS and other software, and for transferring data
 between machines.
 
 <p>
-If the <b>format</b> parameter is set to <b>standard</b>, 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 <b>standard</b> format is
-given below.
-
-<p>The header is similar as the head file of vector binary format but
-contains bounding box also. Key words are:
-
-<pre>
-ORGANIZATION
-DIGIT DATE
-DIGIT NAME
-MAP NAME
-MAP DATE
-MAP SCALE
-OTHER INFO
-ZONE
-WEST EDGE
-EAST EDGE
-SOUTH EDGE
-NORTH EDGE
-MAP THRESH
-</pre>
-
-<p>The body begins with the row:
-
-<pre>
-VERTI:
-</pre>
-
-followed by records of primitives:
-
-<pre>
-TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
- X Y [Z]
-....
- X Y [Z]
-[ LAYER CATEGORY]
-....
-[ LAYER CATEGORY]
-</pre>
-
-Everything above in <tt>[&nbsp;]</tt> is optional. 
-
-<p>
-The primitive codes are as follows:
-<ul>
-<li>'P': point</li>
-<li>'L': line</li>
-<li>'B': boundary</li>
-<li>'C': centroid</li>
-<li>'F': face (3D boundary)</li>
-<li>'K': kernel (3D centroid)</li>
-<li>'A': area (boundary) - better use 'B'; kept only for backward compatibility</li>
-</ul>
-
-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
-<div class="code"><pre>
-  X Y [Z]
-</pre></div>
-
-In pre-GRASS 6 versions of the ASCII file, the order of coordinates is:
-<div class="code"><pre>
-Y X
-</pre></div>
-
 If old version is requested, the <b>output</b> files from <em>v.out.ascii</em> is placed 
 in the <tt>$LOCATION/$MAPSET/dig_ascii/</tt> and <tt>$LOCATION/$MAPSET/dig_att</tt> directory.
 
 <p>
 Only features with a category number will be
-exported. Use <em>v.category</em> to add them if needed.
+exported. Use <em><a href="v.category.html">v.category</a></em> to add
+them if needed.
 
 <p>
-<em>v.out.ascii</em> does not copy the <em>dig_cats</em> file
-associated with the binary vector <em>input</em> map to the
-new <em>output</em> file name. The user must copy
-the <em>dig_cats</em> file to the new <em>output</em> name if this is
-desired (e.g. using the UNIX <em>cp</em> command).
+<em>v.out.ascii</em> does not copy the <tt>dig_cats</tt> file
+associated with the binary vector <b>input</b> map to the
+new <b>output</b> file name. The user must copy the <tt>dig_cats</tt>
+file to the new <b>output</b> name if this is desired (e.g. using the
+UNIX <em>cp</em> command).
 
 <p>
 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 
-<em>v.to.points</em> and then exporting with <em>v.out.ascii</em> in 
-<em>points</em> mode.
+<em><a href="v.to.points.html">v.to.points</a></em> and then exporting
+with <em>v.out.ascii</em> in
+<b>points</b> mode.
 
 <h2>EXAMPLES</h2>
 
@@ -170,13 +97,31 @@ v.out.ascii input=archsites format=point where="cat > 5 and cat <= 8" columns=st
 595755|4925300|8|No Name
 </pre></div>
 
+<h3>WKT mode</h3>
+
+WKT is abbreviation
+for <a href="http://en.wikipedia.org/wiki/Well-known_text">Well-known
+text</a>.
+
+<div class="code"><pre>
+v.out.ascii input=quads format=wkt
+
+POLYGON((599587.18209620 4914067.53414294, 589639.15126831 4913922.56873010,
+         589440.96838162 4927803.62500018, 599375.87959179 4927959.83330436,
+         599587.18209620 4914067.53414294))
+POLYGON((599587.18209620 4914067.53414294, 599375.87959179 4927959.83330436,
+         609316.10665227 4928116.84905550, 609541.55082390 4914236.05974820,
+         599587.18209620 4914067.53414294))
+</pre></div>
+
 <h2>SEE ALSO</h2>
 
 <em>
 <a href="v.category.html">v.category</a>,
 <a href="v.in.ascii.html">v.in.ascii</a>,
 <a href="v.to.points.html">v.to.points</a><br>
-<a HREF="sql.html">GRASS SQL interface</a>
+<a href="vectorascii.html">GRASS ASCII vector format</a> specification<br>
+<a href="sql.html">GRASS SQL interface</a>
 </em>
 
 <h2>AUTHORS</h2>
@@ -191,7 +136,8 @@ Research Laboratory
 <br>
 Radim Blazek, ITC-Irst, Trento, Italy
 <br>
-Attribute selection added by Martin Landa, CTU in Prague, Czech Republic (2008/12)
+Attribute selection added by Martin Landa, Czech Technical University
+in Prague, Czech Republic (2008/12)
 
 <p>
 <i>Last changed: $Date$</i>