<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN"> <html> <head> <title>GRASS GIS: v.in.ascii</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <link rel="stylesheet" href="grassdocs.css" type="text/css"> </head> <body bgcolor="white"> <img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade> <h2>NAME</h2> <em><b>v.in.ascii</b></em> - Creates a vector map from ASCII points file or ASCII vector file. <h2>KEYWORDS</h2> vector, import <h2>SYNOPSIS</h2> <b>v.in.ascii</b><br> <b>v.in.ascii help</b><br> <b>v.in.ascii</b> [-<b>zentbr</b>] [<b>input</b>=<em>name</em>] <b>output</b>=<em>name</em> [<b>format</b>=<em>string</em>] [<b>fs</b>=<em>character</em>] [<b>skip</b>=<em>integer</em>] [<b>columns</b>=<em>name</em>] [<b>x</b>=<em>integer</em>] [<b>y</b>=<em>integer</em>] [<b>z</b>=<em>integer</em>] [<b>cat</b>=<em>integer</em>] [--<b>overwrite</b>] [--<b>verbose</b>] [--<b>quiet</b>] <h3>Flags:</h3> <DL> <DT><b>-z</b></DT> <DD>Create 3D file</DD> <DT><b>-e</b></DT> <DD>Create a new empty map and exit. Nothing is read from input</DD> <DT><b>-n</b></DT> <DD>Don't expect a header when reading in standard format</DD> <DT><b>-t</b></DT> <DD>Do not create table in points mode</DD> <DT><b>-b</b></DT> <DD>Do not build topology in points mode</DD> <DT><b>-r</b></DT> <DD>Only import points falling within current region (points mode)</DD> <DT><b>--overwrite</b></DT> <DD>Allow output files to overwrite existing files</DD> <DT><b>--verbose</b></DT> <DD>Verbose module output</DD> <DT><b>--quiet</b></DT> <DD>Quiet module output</DD> </DL> <h3>Parameters:</h3> <DL> <DT><b>input</b>=<em>name</em></DT> <DD>ASCII file to be imported, if not given reads from standard input</DD> <DT><b>output</b>=<em>name</em></DT> <DD>Name for output vector map</DD> <DT><b>format</b>=<em>string</em></DT> <DD>Input file format</DD> <DD>Options: <em>point,standard</em></DD> <DD>Default: <em>point</em></DD> <DT><b>fs</b>=<em>character</em></DT> <DD>Field separator</DD> <DD>Default: <em>|</em></DD> <DT><b>skip</b>=<em>integer</em></DT> <DD>Number of header lines to skip at top of input file (points mode)</DD> <DD>Default: <em>0</em></DD> <DT><b>columns</b>=<em>name</em></DT> <DD>Column definition in SQL style (points mode)</DD> <DD>For example: 'x double precision, y double precision, cat int, name varchar(10)'</DD> <DT><b>x</b>=<em>integer</em></DT> <DD>Number of column used as x coordinate (first column is 1) for points mode</DD> <DD>Default: <em>1</em></DD> <DT><b>y</b>=<em>integer</em></DT> <DD>Number of column used as y coordinate (first column is 1) for points mode</DD> <DD>Default: <em>2</em></DD> <DT><b>z</b>=<em>integer</em></DT> <DD>Number of column used as z coordinate (first column is 1) for points mode</DD> <DD>If 0, z coordinate is not used</DD> <DD>Default: <em>0</em></DD> <DT><b>cat</b>=<em>integer</em></DT> <DD>Number of column used as category (first column is 1) for points mode</DD> <DD>If 0, unique category is assigned to each row and written to new column 'cat'</DD> <DD>Default: <em>0</em></DD> </DL> <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: <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 one row. Values are separated by a user definable deliminator. If the <b>columns</b> option is not defined, default names are used. It is possible to specify the column order for the x,y,z coordinates and category values.</li> </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. <h2>NOTES</h2> The input is read from the file specified by the <b>input</b> option or from standard input. <p> The field separator may be a character, the word '<tt>tab</tt>' (or '<tt>\t</tt>') for tab, or '<tt>space</tt>' (or ' ') for a blank. <p> Attribute table is only created if it is needed, i.e. when at least one attribute column is present in the input file besides geometry columns. The attribute column will be auto-scanned for type, but 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 disabling of topology. <p> A GRASS ASCII vector map (in <B>standard</B> mode) may contain a mix of primitives including points, lines, boundaries, centroids, areas, faces, and kernels. <!--This format is described in the <a HREF="http://freegis.org/cgi-bin/viewcvs.cgi/~checkout~/grass6/doc/vector/vector.html#ascii">GRASS Vector ASCII Format Specification</a>.--> On top a header can be defined (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: <pre> TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES] X Y [Z] .... X Y [Z] [ LAYER CATEGORY] .... [ LAYER CATEGORY] </pre> Everything above in <tt>[ ]</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 <pre> X Y [Z] </pre> <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. <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 -h</tt>). The skip option only works in <tt>points</tt> 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 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. <h3>Importing only selected columns</h3> Although <em>v.in.ascii</em> doesn't have an option to specify which columns should be imported, you can use a shell filter to achieve the same effect, e.g.: <div class="code"><pre> # Print out the column number for each field, supposing the file has a header head -1 input_file | tr '<the_field_separator_character>' '\n' | cat -n # From the listing, select the columns you want and feed them to v.in.ascii # do not use the input= option cut -d<the_field_separator_character> -f<comma-separated_list_of_columns> input_file | v.in.ascii <your_options> </pre></div> <h2>EXAMPLES</h2> <h3>Example 1a) - standard mode</h3> Sample ASCII polygon vector map for 'standard' 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> 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> <h3>Example 1b) - standard mode</h3> Sample ASCII 3D line vector map for 'standard' mode with simplified input (no header). The example can be tested in the Spearfish sample dataset: <div class="code"><pre> echo "L 5 1 591336 4927369 1224 594317 4925341 1292 599356 4925162 1469 602396 4926653 1235 607524 4925431 1216 1 321 " | v.in.ascii -zn out=line3d format=standard </pre></div> This can be used to create a vector line of a GPS track: the GPS points have to be stored into a file with a preceding 'L' and the number of points (per line). <h3>Example 2</h3> Generate a 2D points vector map 'coords.txt' as ASCII file: <div class="code"><pre> 1664619|5103481 1664473|5095782 1664273|5101919 1663427|5105234 1663709|5102614 </pre></div> <p> Import into GRASS: <div class="code"><pre> 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. <h3>Example 3</h3> Generate a 2D points vector map 'points.dat' as ASCII file: <div class="code"><pre> 1|1664619|5103481|studna 2|1664473|5095782|kadibudka 3|1664273|5101919|hruska 4|1663427|5105234|mysi dira 5|1663709|5102614|mineralni pramen </pre></div> <p> Import into GRASS: <div class="code"><pre> cat points.dat | v.in.ascii out=mypoints x=2 y=3 cat=1 \ columns='cat int, x double precision, y double precision, label varchar(20)' </pre></div> <p> The module is reading from standard input, using the default '|' (pipe) delimiter. <h3>Example 4</h3> Generating a 3D points vector map from DBMS (idcol must be an integer column):<br> <div class="code"><pre> echo "select east,north,elev,idcol from mytable" | db.select -c | v.in.ascii -z out=mymap </pre></div> The module is reading from standard input, using the default '|' (pipe) delimiter. <br> The import works for 2D maps as well (no elev column and no '-z' flag). <h3>Example 5</h3> Generate a 3D points vector map 'points3d.dat' with attributes as ASCII file: <div class="code"><pre> 593493.1|4914730.2|123.1|studna|well 591950.2|4923000.5|222.3|kadibudka|closet 589860.5|4922000.0|232.3|hruska|pear 590400.5|4922820.8|143.2|mysi dira|mouse hole 593549.3|4925500.7|442.6|mineralni pramen|mineral spring 600375.7|4925235.6|342.2|kozi stezka|goat path </pre></div> <P> Import into GRASS: <div class="code"><pre> #As the 'cat' option is set to 0 by default, an extra column 'cat' #containing the IDs will be auto-generated (no need to define that): cat points3d.dat | v.in.ascii -z z=3 cat=0 out=mypoints3D \ columns='x double precision, y double precision, z double precision, \ label_cz varchar(20), label_en varchar(20)' v.info -c mypoints3D v.info mypoints3D </pre></div> <h3>Example 6</h3> Generate points file by clicking onto the map: <div class="code"><pre> #For LatLong locations: d.where -d -l | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii out=points \ columns='x double precision, y double precision, label varchar(20)' #For other projections: d.where | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii out=points \ columns='x double precision, y double precision, label varchar(20)' </pre></div> The 'point' string (or some similar entry) is required to generate a database table. When simply piping the coordinates (and optionally height) without additional column(s) into <em>v.in.ascii</em>, only the vector map geometry will be generated. <h3>Example 7</h3> Convert ground control points from i.points into vector points: <div class="code"><pre> cat $MAPSET/group/$GROUP/POINTS | v.in.ascii out=$GROUP_gcp fs=space skip=3 \ col='x double precision, y double precision, x_target double precision, \ y_target double precision, ok int' </pre></div> <h2>REFERENCES</h2> <a HREF="sql.html">SQL command notes</a> for creating databases <h2>SEE ALSO</h2> <em> <a HREF="db.execute.html">db.execute</a>, <a HREF="r.in.ascii.html">r.in.ascii</a>, <a HREF="r.in.xyz.html">r.in.xyz</a>, <a HREF="v.db.connect.html">v.db.connect</a>, <a HREF="v.out.ascii.html">v.out.ascii</a>, <a HREF="v.info.html">v.info</a>, <a HREF="v.build.html">v.build</a>, <a HREF="v.build.polylines.html">v.build.polylines</a>, <a HREF="v.centroids.html">v.centroids</a>, <a HREF="v.clean.html">v.clean</a> </em> <h2>AUTHORS</h2> 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 <p> <i>Last changed: $Date: 2007-11-29 14:34:20 +0100 (Thu, 29 Nov 2007) $</i> <HR> <P><a href="index.html">Main index</a> - <a href="vector.html">vector index</a> - <a href="full_index.html">Full index</a></P> <P>© 2003-2008 <a href="http://grass.osgeo.org">GRASS Development Team</a></p> </body> </html>