Provided by: grass-doc_6.4.3-3_all 
NAME
v.in.ascii - Creates a vector map from ASCII points file or ASCII vector file.
KEYWORDS
vector, import
SYNOPSIS
v.in.ascii
v.in.ascii help
v.in.ascii [-zentbr] [input=name] output=name [format=string] [fs=character]
[skip=integer] [columns=string] [x=integer] [y=integer] [z=integer]
[cat=integer] [--overwrite] [--verbose] [--quiet]
Flags:
-z
Create 3D vector map
-e
Create a new empty vector map and exit. Nothing is read from input.
-n
Don't expect a header when reading in standard format
-t
Do not create table in points mode
-b
Do not build topology in points mode
-r
Only import points falling within current region (points mode)
--overwrite
Allow output files to overwrite existing files
--verbose
Verbose module output
--quiet
Quiet module output
Parameters:
input=name
ASCII file to be imported, if not given reads from standard input
output=name
Name for output vector map
format=string
Input file format
Options: point,standard
Default: point
point: simple x,y[,z] list
standard: GRASS vector ASCII format
fs=character
Field separator
Special characters: newline, space, comma, tab
Default: |
skip=integer
Number of header lines to skip at top of input file (points mode)
Default: 0
columns=string
Column definition in SQL style (points mode)
For example: 'x double precision, y double precision, cat int, name varchar(10)'
x=integer
Number of column used as x coordinate (points mode)
First column is 1
Default: 1
y=integer
Number of column used as y coordinate (points mode)
First column is 1
Default: 2
z=integer
Number of column used as z coordinate (points mode)
First column is 1. If 0, z coordinate is not used
Default: 0
cat=integer
Number of column used as category (points mode)
First column is 1. 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 delimiter. 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 v.out.ascii GRASS module performs the function of v.in.ascii 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.
NOTES
The input is read from the file specified by the input option or from standard input.
The field separator may be a character, the word 'tab' (or '\t') for tab, 'space' (or ' ')
for a blank, or 'comma' (or ',') for a comma.
An 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 columns parameter.
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
167:03:04.567; and not 167:3:4.567).
Acceptable formats:
key: D=Degrees; M=Minutes; S=Seconds; h=Hemisphere (N,S,E,W)
(+/-)DDD.DDDDD DDDh DDD:MMh DDD:MM.MMMMMh DDD:MM:SSh DDD:MM:SS.SSSSSh
Use the -z flag to convert ASCII data into a 3D vector map.
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 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 recommended that the user first try to
import the data without creating a database (the -t flag) or within a subregion (the -r
flag) before resorting to the disabling of topology.
A GRASS ASCII vector map (in standard format 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 -n flag is used.
The header is similar as the head file of vector binary format but contains bounding box
also. Key words are:
ORGANIZATION
DIGIT DATE
DIGIT NAME
MAP NAME
MAP DATE
MAP SCALE
OTHER INFO
ZONE
WEST EDGE
EAST EDGE
SOUTH EDGE
NORTH EDGE
MAP THRESH
The body begins with the row:
VERTI:
followed by records of primitives:
TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
X Y [Z]
X Y [Z]
[ LAYER CATEGORY]
[ LAYER CATEGORY]
Everything above in [ ] is optional.
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 (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).
The order of coordinates is
X Y [Z]
In pre-GRASS 6 versions of the ASCII file, the order of coordinates is:
Y X
If old version is requested, the output files from v.out.ascii is placed in the
$LOCATION/$MAPSET/dig_ascii/ and $LOCATION/$MAPSET/dig_att directory.
Import of files without category ID column
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 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). The skip option only works in
points mode.
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<comma-separated_list_of_columns> input_file |
v.in.ascii <your_options>
EXAMPLES
Example 1a) - standard format mode
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:
echo "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" | v.in.ascii format=standard output=test_polygons
Example 1b) - standard format mode
Sample ASCII 3D line vector map for 'standard' format mode with simplified input (note the
space field separator). Note the -z flag indicating 3D vector input, and the -n flag
indicating no vector header should be expected from the input file. 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 - point format mode
Generate a 2D points vector map '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 - point format mode
Generate a 2D points vector map '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 precision, y double precision, label varchar(20)'
The module is reading from standard input, using the default '|' (pipe) delimiter.
Example 4 - point format mode
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 - point format mode
Generate a 3D points vector map '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 precision, y double precision, z double precision, \
label_cz varchar(20), label_en varchar(20)'
v.info -c mypoints3D
v.info mypoints3D
Example 6 - point format mode
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 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)'
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 - point format mode
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 precision, y double precision, x_target double precision, \
y_target double precision, ok int'
REFERENCES
SQL command notes for creating databases
SEE ALSO
db.execute, r.in.ascii, r.in.xyz, v.build, v.build.polylines, v.centroids, v.clean,
v.db.connect, v.info, v.out.ascii,
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: 2013-05-03 12:47:09 -0700 (Fri, 03 May 2013) $
Full index
© 2003-2013 GRASS Development Team