DESCRIPTION

v.in.ascii converts a vector map in ASCII format to a vector map in binary format. The module may import two formats:

The input is read from a file specified by input option or from standard input.

NOTES

Use the -z flag to convert ASCII data into a 3D binary vector map.

A GRASS ASCII vector file (in standard mode) may contain a mix of primitives including points, lines, boundaries, centroids, areas, faces, and kernels.

The primitive codes are as follows:

The coordinates are listed following the initial line containing the primitive code and the total number of vertices in the series. The order of coordinates is

X Y [Z]

Import of files without ID column
In case that the input files does not contain any vector ID column, there is the possibility to auto-generate these IDs (categories). For that, to automatically add an additional column 'cat', the catcol parameter has to be set to the virtual column number 0 (catcol=0). The name for the auto-generated column is set to 'cat'.

Importing from a spreadsheet
Data may be imported from many spreadsheet programs by saving the spreadsheet as a comma separated variable (.csv) text file, and then using the fs=',' option with v.in.ascii in points mode.

Import of category attributes in standard mode
The user has to create a database table directly (with db.execute) and then link it to vector map: 

       db.execute ... # (CREATE TABLE ..., INSERT INTO ....)
       v.db.connect ... # link table to vector map)

EXAMPLES

Example 1
Direct file editing: Sample ASCII vector file. Note the blank before entering vertex coordinates:

       ORGANIZATION: GRASS Development Team
       DIGIT DATE:   1/9/2002
       DIGIT NAME:   -
       MAP NAME:     test
       MAP DATE:     2002
       MAP SCALE:    10000
       OTHER INFO:   Test polygons
       ZONE:         0
       MAP THRESH:   0.500000
       VERTI:
       A  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
       A  4
        5959010.9323622 3401338.36037757
        5959096.7459483 3401370.54047235
        5959091.38259917 3401450.99070932
        5959010.9323622 3401338.36037757


Example 2
Generate a 2D points vector file 'coords.txt' as ASCII file: 

  1664619|5103481
  1664473|5095782
  1664273|5101919
  1663427|5105234
  1663709|5102614

Import into GRASS: 

cat coords.txt | v.in.ascii out=mymap
As catcol is set to 0 by default, an extra column 'cat' containing the IDs will be auto-generated.


Example 3
Generate a 2D points vector file 'points.dat' as ASCII file: 

  1|1664619|5103481|studna
  2|1664473|5095782|kadibudka
  3|1664273|5101919|hruska
  4|1663427|5105234|mysi dira
  5|1663709|5102614|mineralni pramen

Import into GRASS: 

cat points.dat | v.in.ascii out=mypoints xcol=2 ycol=3 catcol=1 columns='cat int, x double, y double, label varchar(20)'

The module is reading from standard input, using the default '|' (pipe) delimiter.


Example 4
Generating a 3D points vector map from DBMS (idcol must be an integer column):

echo "select east,north,elev,idcol from mytable " | db.select -c | v.in.ascii -z out=mymap
The module is reading from standard input, using the default '|' (pipe) delimiter.
The import works for 2D maps as well (no elev column and no '-z' flag).


Example 5
Generate a 3D points vector file 'points3d.dat' with attributes as ASCII file: 

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

Import into GRASS: 

#As catcol 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 zcol=3 catcol=0 out=mypoints3D \
                   columns='x double, y double, z double, label_cz varchar(20), label_en varchar(20)'
v.info -c mypoints3D
v.info mypoints3D


Example 6
Generate points file by clicking onto the map: 

#For LatLong locations:
d.where -d -l | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii out=points catcol=0 columns='x double, y double, label varchar(20)'

#For other projections:
d.where | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii out=points catcol=0 columns='x double, y double, label varchar(20)'
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 v.in.ascii, only the vector map geometry will be generated.

The GRASS program v.out.ascii performs the function of v.in.ascii in reverse; i.e., it converts vector files in binary format to ASCII format. These two companion programs are useful both for importing and exporting vector files between GRASS and other software, and for transferring data between machines.

SEE ALSO

db.execute, v.db.connect, v.out.ascii, v.build
SQL command notes for creating databases
Vector ASCII Format Specification

AUTHORS

Michael Higgins, U.S.Army Construction Engineering Research Laboratory
James Westervelt, U.S.Army Construction Engineering Research Laboratory
Radim Blazek, ITC-Irst, Trento, Italy

Last changed: $Date$