## NAME

v.in.ascii - Convert GRASS ascii file or points file to binary vector.

## KEYWORDS

vector

## SYNOPSIS

v.in.ascii
v.in.ascii help
v.in.ascii [-ztenb] [input=string] output=name [format=string] [fs=string] [skip=integer] [columns=string] [x=integer] [y=integer] [z=integer] [cat=integer] [--overwrite]

### Flags:

-z
  Create 3D file
-t
  Do not create table in points mode
-e
  Create a new empty map and exit. Nothing is read from input.
-n
  Don't expect a header when reading in standard format
-b
  Do not build topology in points mode
--overwrite
  Force overwrite of output files

### Parameters:

input=string
  ASCII file to be converted to binary vector file, if not given reads from standard input
output=name
  Name for output vector map
format=string
  Input file format
  Options: point,standard
  Default: point
fs=string
  Field separator
  Default: |
skip=integer
  Number of header lines to skip at top of input file (written to map history)
  Default: 0
columns=string
  Columns definition for points mode in SQL style, for example:
  'x double precision, y double precision, cat int, name varchar(10)'
x=integer
  Number of column used as x coordinate (first column is 1) for points mode
  Default: 1
y=integer
  Number of column used as y coordinate (first column is 1) for points mode
  Default: 2
z=integer
  Number of column used as z coordinate (first column is 1) for points mode. If 0, z coordinate is not used.
  Default: 0
cat=integer
  Number of column used as category (first column is 1) for points mode. If 0, unique category is assigned to each row and written to new column 'cat'.
  Default: 0

## DESCRIPTION

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

standard
  contains all data types, each coordinate on one row
point
  (default) reads only points, each point defined on one row. Values are separated by a user definable deliminator. If the 'columns' 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.

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

Field separator may be a character, the word 'tab' (or '\t') for tab, or 'space' (or ' ') for blank.

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 types have to be declared along with the geometry columns using the columns parameter.

In special cases of data import, such as the import of large points map from LIDAR, it will be desired to disable topology support (GRASS vector level 1). This can be done by setting the -b flag. Only very few vector modules support points data processing at vector level 1, usually topology is required (vector level 2).

The v.out.ascii GRASS module 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.

## 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. On top a header can be defined (see example below).

The primitive codes are as follows:

- 'P': point
- 'L': line
- 'B': boundary
- 'C': centroid
- 'F': face (3D boundary)
- 'K': kernel (3D centroid)
- 'A': area (boundary) - better use 'B'; kept only for backward compatibility

The coordinates are listed following the initial line containing the primitive code, the total number of vectors in the series, and 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).
The order of coordinates is
X Y [Z]

### Import of files without category ID column

If the input file does not contain any vector ID column, there is the possibility to auto-generate these IDs (categories). To automatically add an additional column named 'cat', the cat parameter must be set to the virtual column number 0 (`cat=0`). This is the default action if the cat parameter is not set.

### 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. If the input file contains any header lines, such as column headings, the skip parameter should be used. These skipped header lines will be written to the map's history file for later reference (read with `v.info -h`).

Any line starting with the hash character ('`#`') 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 skip parameter, it will be treated as a header line and written to the history file.

### Import of sexagesimal degree (degree, minutes, seconds, DMS)

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.

### Importing only selected columns

Although v.in.ascii 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.:

    # 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 input_file | v.in.ascii <your_options>

## EXAMPLES

### Example 1a) - standard mode

Sample ASCII polygon vector map for 'standard' mode. Note the blank before entering vertex coordinates. The example can be tested in the Spearfish sample dataset:

    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 1
     5958812.48844435 3400828.84221011
     5958957.29887089 3400877.11235229
     5959021.65906046 3400930.7458436
     5959048.47580612 3400973.65263665
     5959069.92920264 3401032.64947709
     5958812.48844435 3400828.84221011
     1 1
    B  4 1
     5959010.9323622 3401338.36037757
     5959096.7459483 3401370.54047235
     5959091.38259917 3401450.99070932
     5959010.9323622 3401338.36037757
     1 2

### Example 1b) - standard mode

Sample ASCII 3D line vector map for 'standard' mode with simplified input (no header). The example can be tested in the Spearfish sample dataset:

    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

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).

### 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:

    v.in.ascii input=coords.txt output=mymap

As the cat option 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 x=2 y=3 cat=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 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, 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 \
        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 \
        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.

### Example 7

Convert ground control points from i.points into vector points:

    cat $MAPSET/group/$GROUP/POINTS | v.in.ascii out=$GROUP_gcp fs=space skip=3 \
        col='x double, y double, x_target double, y_target double, ok int'

## SEE ALSO

db.execute
v.db.connect
v.out.ascii
v.info
v.build
v.build.polylines
v.clean
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: 2007/07/23 07:57:28 $

Main index - vector index - Full index