v.in.ascii(1grass)

💖 v.in.ascii 💖

okay bestie, welcome to v.in.ascii — the GRASS User's Manual glow-up edition ✨ this is the module that makes vector maps out of ASCII files, and I'm gonna walk you through every single flag like we're texting at 2am 🫶

KEYWORDS: vector, import, ASCII, level1, area, line, point 🌸

---

✨ SYNOPSIS ✨

v.in.ascii
v.in.ascii --help
v.in.ascii [-zentbri] input=name output=name  [format=string]
[separator=character]   [text=character]   [skip=integer]
[columns=string]   [x=integer]   [y=integer]   [z=integer]
[cat=integer]   [--overwrite]  [--help]  [--verbose]  [--quiet]  [--ui]

---

🎀 Flags 🎀

• -z — bestie this is the 3D button. Creates a 3D vector map. the way that a flat map could NEVER 💅
• -e — makes a brand new empty vector map and dips. nothing gets read from input at all. iconic minimalism ✨
• -n — do NOT expect a header when you're reading in standard format. no header, no problem 🙈
• -t — points mode only: don't create a table. table? never met her 💀
• -b — do not build topology. also: do not build topology in points mode. (yes, both, she said what she said 👑)
• -r — points mode only: only import the points that fall inside your current region. if it's not in the region, it's not invited to the party 🚫
• -i — points mode only: ignore broken line(s). lowkey forgiving, highkey necessary sometimes 😭
• --overwrite — let output files overwrite files that already exist. she's bold, she's rewriting history 💅
• --help — print the usage summary. your little cheat sheet 🫶
• --verbose — verbose module output. she's chatty and we love that for her ✨
• --quiet — quiet module output. she's giving mysterious ✨
• --ui — force launching the GUI dialog. clicking > typing, sometimes 🎀

---

🌸 Parameters 🌸

• input=name [required] — name of the input file you're importing. and yes, '-' means standard input, so you can pipe her in 🍓
• output=name [required] — the name for your output vector map. name her something cute 💜
• format=string — the input file format. options: point, standard. default: point.
  • point: a simple x,y[,z] list — just vibes and numbers
  • standard: the GRASS vector ASCII format, the full deluxe edition 👑
• separator=character — the field separator. special characters you can name: pipe, comma, space, tab, newline. default: pipe. pick your fighter 🎀
• text=character — the text delimiter. special characters: doublequote, singlequote, none. the way she quotes is a whole personality ✨
• skip=integer — how many header lines to skip at the top of the input file (points mode). default: 0. bye bye header row 👋
• columns=string — the column definition in SQL style (points mode). for example: 'x double precision, y double precision, cat int, name varchar(10)'. go off, SQL queen 💅
• x=integer — which column gets used as the x coordinate (points mode). first column is 1. default: 1 🌸
• y=integer — which column gets used as the y coordinate (points mode). first column is 1. default: 2 🌈
• z=integer — which column gets used as the z coordinate (points mode). first column is 1. if it's 0, the z coordinate is not used at all. default: 0 ✨
• cat=integer — which column gets used as the category (points mode). first column is 1. if it's 0, a unique category is assigned to every single row and written to a new column named 'cat'. default: 0 🐱

---

🌈 DESCRIPTION 🌈

okay so v.in.ascii converts a vector map in GRASS ASCII vector format into a vector map in binary format. she's a translator, she's multilingual, she's everything 💖

The module may import two formats:

• standard — contains all the data types, and each coordinate sits on one row 👑
• point (this is the default, no cap) — reads only points, each point defined on one row. values are separated by a delimiter you get to define, bestie. if the columns option isn't defined, default names get used instead. and yes, you can specify the column order for the x,y,z coordinates and the category values. customize her 💅

Also, quick shoutout to her sibling: v.out.ascii performs the function of v.in.ascii in reverse — i.e., it converts vector maps in binary format back into 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. it's giving dream team 🫶

---

🦋 NOTES 🦋

The input is read from the file specified by the input option, or from standard input. either way she's eating 🍓

The field separator may be a character, or the word 'tab' (or '\t') for tab, 'space' (or ' ') for a blank, or 'comma' (or ',') for a comma. so many options, so little time ✨

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 the geometry columns. The attribute column will be auto-scanned for type (she's intuitive like that 🔮), but it may be explicitly declared along with the geometry columns using the columns parameter. if you wanna be specific, be specific 💅

Use the -z flag to convert ASCII data into a 3D vector map. flat who? don't know her 🌈

In special cases of data import — like importing large LIDAR datasets (millions of data points, fr fr 😭) — it may be necessary to disable topology support (vector level 1) due to memory constraints. This is done with the -b flag. But bestie listen: 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 disabling topology. try the cute options first, ok? 🥺

If an old version is requested, the output files from v.out.ascii are placed in the $LOCATION/$MAPSET/dig_ascii/ and $LOCATION/$MAPSET/dig_att directory. vintage ✨

🎀 Import of files without category column

If the input file does not contain a category column, there's a 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. she generates her own, she's independent 💅

💜 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 separator=',' or separator=comma 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. she's keeping receipts 📝

Any line starting with the hash character ('#') will be treated as a comment and skipped completely if located in the main data file. If it's located in the header (as defined by the skip parameter), it will be treated as a header line and written to the history file. # is the universal "no thoughts, head empty" symbol 💀

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

The import of DMS formatted degrees is supported — and in this case, no sign is used, but the N/S and 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 varchar(), not as numbers. A warning will be issued which can be ignored. See the GRASS ASCII vector format specification for details. compass girlie behavior 🧭✨

🍓 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
# use input=- to read from stdin
cut -d<the_field_separator_character> -f<comma-separated_list_of_columns> input_file | v.in.ascii in=- <your_options>

see, we do a little plumbing, we get exactly the columns we want. it's giving resourceful 🫶

💖 EXAMPLES 💖

okay bestie this is the part where it gets FUN. real data, real commands, real slay. 🫶

---

🌸 Example 1a) - standard format mode

here's a sample ASCII polygon vector map for the 'standard' format mode. the two areas are gonna get assigned categories 20 and 21. wanna know the whole structure of standard format data files? the second reference at the bottom of this page has you covered, bestie.

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 in=- format=standard output=test_polygons

---

🎀 Example 1b) - standard format mode

and now a sample ASCII 3D line vector map for 'standard' format mode, but with simplified input (peep the space field separator 👀). note the -z flag — that's the 3D vector input vibe — and the -n flag, which says "bestie, don't expect a vector header from this input file". the first line here says the line (L) has 5 vertices and 1 category. the last line says the layer (1) and the category value (321).

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 in=- out=line3d format=standard

this one's iconic for making a vector line out of a GPS track: you pop your GPS points into a file with an 'L' in front and the number of points (per line). boom. 📍

---

✨ Example 2 - point format mode

make a 2D points vector map 'coords.txt' as an ASCII file:

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

import it into GRASS:

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

and because the cat option defaults to 0, an extra column 'cat' full of category numbers gets auto-generated for you. no effort, all reward. 💅

---

🦋 Example 3 - point format mode

make a 2D points vector map 'points.dat' as an 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 it into GRASS:

cat points.dat | v.in.ascii in=- 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 here, using the default '|' (pipe) delimiter. default behavior ate, no notes. 😌

---

🍓 Example 4 - point format mode - CSV table

importing a 3D points CSV table ('points3d.csv') that's got attributes:

"num","X","Y","Z","T"
1,2487491.643,5112118.33,120.5,18.62
2,2481985.459,5109162.78,123.9,18.46
3,2478284.289,5105331.04,98.3,19.61

import it into GRASS:

# import: skipping the header line, categories generated automatically,
# column names defined with type:
v.in.ascii -z in=points3d.csv out=mypoints3D separator=comma \
  columns="num integer, x double precision, y double precision, z double precision, temp double precision" \
  x=2 y=3 z=4 skip=1
# verify column types
v.info -c mypoints3D
# verify table content
v.db.select mypoints3D

see how we skip=1 past that header line? chef's kiss. 👑

---

💜 Example 5 - point format mode

generating a 3D points vector map straight from DBMS (heads up: idcol must be an integer column, no cap):

echo "select east,north,elev,idcol from mytable" | db.select -c | v.in.ascii in=- -z out=mymap

with in=-, the module is reading from standard input, using the default '|' (pipe) delimiter. same as always.

and fr fr, the import works for 2D maps too — just no elev column and no '-z' flag. versatile icon. 🌈

---

🧚 Example 6 - point format mode

make a 3D points vector map 'points3d.dat' with attributes as an ASCII file:

593493.1|4914730.2|123.1|studna|well
591950.2|4923000.5|222.3|kadibudka|outhouse
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 it 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 in=- -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

no need to define cat yourself — the module does it for you. that's the kind of main character energy we love. ✨

---

🌸 Example 7 - point format mode

generate a points file by clicking onto the map (yes, clicking, we're doing interactive GIS today):

#For LatLong projects:
d.where -d -l | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii in=- 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 in=- 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, bestie. don't skip it. because if you just pipe the coordinates — and optionally the height — into v.in.ascii without any extra column(s), you'll only get the vector map geometry and no table. so sad. 😭

---

🎀 Example 8 - point format mode

convert ground control points into vector points:

cat $MAPSET/group/$GROUP/POINTS | v.in.ascii in=- out=$GROUP_gcp separator=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
• GRASS ASCII vector format specification

---

💖 SEE ALSO

db.execute, r.in.ascii, r.in.poly, r.in.xyz, v.build, v.build.polylines, v.centroids, v.clean, v.db.connect, v.import, v.info, v.in.lines, v.in.mapgen, v.out.ascii

the whole friend group fr fr. go say hi. 🫶

---

👑 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

absolute legends, all three of them. 💜

---

🌈 SOURCE CODE

Available at: v.in.ascii source code (history)

latest change: Sunday Jul 27 05:53:30 2025 in commit da409580ef15011f3bac379c76d41101c9e36347

Main index | Vector index | Topics index | Keywords index | Graphical index | Full index

© 2003-2026 GRASS Development Team, GRASS 8.5.0 Reference Manual

---

and that's a wrap, bestie!! ✨ this whole page is from the GRASS 8.5.0 reference manual, last touched Sunday Jul 27 05:53:30 2025, and it's all © 2003-2026 GRASS Development Team. go import something cursed. i believe in you. 🦋💖🎀