---
name: v.in.ascii
description: "Creates a vector map from an ASCII points file or ASCII vector file."
keywords: [ vector, import, ASCII, level1, area, line, point ]
---

# v.in.ascii

Creates a vector map from an ASCII points file or ASCII vector file.

=== "Command line"

    **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**]
    [**--verbose**]
    [**--quiet**]
    [**--qq**]
    [**--ui**]

    Example:

    ```sh
    v.in.ascii input=name output=name
    ```

=== "Python (grass.tools)"

    *grass.tools.Tools.v_in_ascii*(**input**,
        **output**,
        **format**=*"point"*,
        **separator**=*"pipe"*,
        **text**=*None*,
        **skip**=*0*,
        **columns**=*None*,
        **x**=*1*,
        **y**=*2*,
        **z**=*0*,
        **cat**=*0*,
        **flags**=*None*,
        **overwrite**=*None*,
        **verbose**=*None*,
        **quiet**=*None*,
        **superquiet**=*None*)

    Example:

    ```python
    tools = Tools()
    tools.v_in_ascii(input="name", output="name")
    ```

    This grass.tools API is experimental in version 8.5 and expected to be stable in version 8.6.

=== "Python (grass.script)"

    *grass.script.run_command*("***v.in.ascii***",
        **input**,
        **output**,
        **format**=*"point"*,
        **separator**=*"pipe"*,
        **text**=*None*,
        **skip**=*0*,
        **columns**=*None*,
        **x**=*1*,
        **y**=*2*,
        **z**=*0*,
        **cat**=*0*,
        **flags**=*None*,
        **overwrite**=*None*,
        **verbose**=*None*,
        **quiet**=*None*,
        **superquiet**=*None*)

    Example:

    ```python
    gs.run_command("v.in.ascii", input="name", output="name")
    ```

## Parameters

=== "Command line"

    **input**=*name* **[required]**  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of input file to be imported  
    &nbsp;&nbsp;&nbsp;&nbsp;'-' for standard input  
    **output**=*name* **[required]**  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output vector map  
    **format**=*string*  
    &nbsp;&nbsp;&nbsp;&nbsp;Input file format  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *point, standard*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *point*  
    &nbsp;&nbsp;&nbsp;&nbsp;**point**: simple x,y[,z] list  
    &nbsp;&nbsp;&nbsp;&nbsp;**standard**: GRASS vector ASCII format  
    **separator**=*character*  
    &nbsp;&nbsp;&nbsp;&nbsp;Field separator  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: pipe, comma, space, tab, newline  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *pipe*  
    **text**=*character*  
    &nbsp;&nbsp;&nbsp;&nbsp;Text delimiter  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: doublequote, singlequote, none  
    **skip**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of header lines to skip at top of input file (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **columns**=*string*  
    &nbsp;&nbsp;&nbsp;&nbsp;Column definition in SQL style (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;For example: 'x double precision, y double precision, cat int, name varchar(10)'  
    **x**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as x coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *1*  
    **y**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as y coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *2*  
    **z**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as z coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1. If 0, z coordinate is not used  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **cat**=*integer*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as category (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1. If 0, unique category is assigned to each row and written to new column 'cat'  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **-z**  
    &nbsp;&nbsp;&nbsp;&nbsp;Create 3D vector map  
    **-e**  
    &nbsp;&nbsp;&nbsp;&nbsp;Create a new empty vector map and exit. Nothing is read from input.  
    **-n**  
    &nbsp;&nbsp;&nbsp;&nbsp;Do not expect a header when reading in standard format  
    **-t**  
    &nbsp;&nbsp;&nbsp;&nbsp;Do not create table in points mode  
    **-b**  
    &nbsp;&nbsp;&nbsp;&nbsp;Do not build topology  
    &nbsp;&nbsp;&nbsp;&nbsp;Do not build topology in points mode  
    **-r**  
    &nbsp;&nbsp;&nbsp;&nbsp;Only import points falling within current region (points mode)  
    **-i**  
    &nbsp;&nbsp;&nbsp;&nbsp;Ignore broken line(s) in points mode  
    **--overwrite**  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    **--help**  
    &nbsp;&nbsp;&nbsp;&nbsp;Print usage summary  
    **--verbose**  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    **--quiet**  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    **--qq**  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    **--ui**  
    &nbsp;&nbsp;&nbsp;&nbsp;Force launching GUI dialog

=== "Python (grass.tools)"

    **input** : str | io.StringIO, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of input file to be imported  
    &nbsp;&nbsp;&nbsp;&nbsp;'-' for standard input  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, file, *name*  
    **output** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output vector map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, vector, *name*  
    **format** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Input file format  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *point, standard*  
    &nbsp;&nbsp;&nbsp;&nbsp;**point**: simple x,y[,z] list  
    &nbsp;&nbsp;&nbsp;&nbsp;**standard**: GRASS vector ASCII format  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *point*  
    **separator** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Field separator  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: pipe, comma, space, tab, newline  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, separator, *character*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *pipe*  
    **text** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Text delimiter  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: doublequote, singlequote, none  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, separator, *character*  
    **skip** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of header lines to skip at top of input file (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **columns** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Column definition in SQL style (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;For example: 'x double precision, y double precision, cat int, name varchar(10)'  
    **x** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as x coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *1*  
    **y** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as y coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *2*  
    **z** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as z coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1. If 0, z coordinate is not used  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **cat** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as category (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1. If 0, unique category is assigned to each row and written to new column 'cat'  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *z*, *e*, *n*, *t*, *b*, *r*, *i*  
    &nbsp;&nbsp;&nbsp;&nbsp;**z**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create 3D vector map  
    &nbsp;&nbsp;&nbsp;&nbsp;**e**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create a new empty vector map and exit. Nothing is read from input.  
    &nbsp;&nbsp;&nbsp;&nbsp;**n**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not expect a header when reading in standard format  
    &nbsp;&nbsp;&nbsp;&nbsp;**t**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not create table in points mode  
    &nbsp;&nbsp;&nbsp;&nbsp;**b**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not build topology  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not build topology in points mode  
    &nbsp;&nbsp;&nbsp;&nbsp;**r**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Only import points falling within current region (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;**i**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ignore broken line(s) in points mode  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  

    Returns:

    **result** : grass.tools.support.ToolResult | None  
    If the tool produces text as standard output, a *ToolResult* object will be returned. Otherwise, `None` will be returned.

    Raises:

    *grass.tools.ToolError*: When the tool ended with an error.

=== "Python (grass.script)"

    **input** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name of input file to be imported  
    &nbsp;&nbsp;&nbsp;&nbsp;'-' for standard input  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, file, *name*  
    **output** : str, *required*  
    &nbsp;&nbsp;&nbsp;&nbsp;Name for output vector map  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: output, vector, *name*  
    **format** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Input file format  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *point, standard*  
    &nbsp;&nbsp;&nbsp;&nbsp;**point**: simple x,y[,z] list  
    &nbsp;&nbsp;&nbsp;&nbsp;**standard**: GRASS vector ASCII format  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *point*  
    **separator** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Field separator  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: pipe, comma, space, tab, newline  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, separator, *character*  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *pipe*  
    **text** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Text delimiter  
    &nbsp;&nbsp;&nbsp;&nbsp;Special characters: doublequote, singlequote, none  
    &nbsp;&nbsp;&nbsp;&nbsp;Used as: input, separator, *character*  
    **skip** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of header lines to skip at top of input file (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **columns** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Column definition in SQL style (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;For example: 'x double precision, y double precision, cat int, name varchar(10)'  
    **x** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as x coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *1*  
    **y** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as y coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *2*  
    **z** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as z coordinate (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1. If 0, z coordinate is not used  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **cat** : int, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Number of column used as category (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;First column is 1. If 0, unique category is assigned to each row and written to new column 'cat'  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *0*  
    **flags** : str, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allowed values: *z*, *e*, *n*, *t*, *b*, *r*, *i*  
    &nbsp;&nbsp;&nbsp;&nbsp;**z**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create 3D vector map  
    &nbsp;&nbsp;&nbsp;&nbsp;**e**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Create a new empty vector map and exit. Nothing is read from input.  
    &nbsp;&nbsp;&nbsp;&nbsp;**n**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not expect a header when reading in standard format  
    &nbsp;&nbsp;&nbsp;&nbsp;**t**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not create table in points mode  
    &nbsp;&nbsp;&nbsp;&nbsp;**b**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not build topology  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Do not build topology in points mode  
    &nbsp;&nbsp;&nbsp;&nbsp;**r**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Only import points falling within current region (points mode)  
    &nbsp;&nbsp;&nbsp;&nbsp;**i**  
    &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Ignore broken line(s) in points mode  
    **overwrite** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Allow output files to overwrite existing files  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **verbose** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Verbose module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **quiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*  
    **superquiet** : bool, *optional*  
    &nbsp;&nbsp;&nbsp;&nbsp;Very quiet module output  
    &nbsp;&nbsp;&nbsp;&nbsp;Default: *None*

## DESCRIPTION

*v.in.ascii* converts a vector map in [GRASS ASCII vector
format](vectorascii.md) 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.

*[v.out.ascii](v.out.ascii.md)* performs the function of *v.in.ascii* in
reverse; i.e., it converts vector maps in binary format to 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.

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

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 (vector level 1) 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.

If old version is requested, the **output** files from
*[v.out.ascii](v.out.ascii.md)* is placed in the
`$LOCATION/$MAPSET/dig_ascii/` and `$LOCATION/$MAPSET/dig_att`
directory.

### Import of files without category column

If the input file does not contain a category 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 **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.

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 `varchar()`, not as numbers. A warning will be issued which can be
ignored. See [GRASS ASCII vector format specification](vectorascii.md)
for details.

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

```sh
# 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>
```

## 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. For details on the
structure of standard format data files see the second reference at the
bottom of this page.

```sh
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

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 first line in this
example specifies that the line (L) has 5 vertices and 1 category. The
last line specifies the layer (1) and the category value (321).

```sh
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 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:

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

Import into GRASS:

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

As the **cat** option is set to 0 by default, an extra column 'cat'
containing the category numbers will be auto-generated.

### Example 3 - point format mode

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

```sh
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:

```sh
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, using the default '\|' (pipe)
delimiter.

### Example 4 - point format mode - CSV table

Import of a 3D points CSV table ('points3d.csv') with attributes:

```sh
"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 into GRASS:

```sh
# 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
```

### Example 5 - point format mode

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

```sh
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.  
The import works for 2D maps as well (no elev column and no '-z' flag).

### Example 6 - point format mode

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

```sh
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 into GRASS:

```sh
#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
```

### Example 7 - point format mode

Generate points file by clicking onto the map:

```sh
#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. 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 8 - point format mode

Convert ground control points into vector points:

```sh
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](sql.md) for creating databases,  
[GRASS ASCII vector format](vectorascii.md) specification

## SEE ALSO

*[db.execute](db.execute.md), [r.in.ascii](r.in.ascii.md),
[r.in.poly](r.in.poly.md), [r.in.xyz](r.in.xyz.md),
[v.build](v.build.md), [v.build.polylines](v.build.polylines.md),
[v.centroids](v.centroids.md), [v.clean](v.clean.md),
[v.db.connect](v.db.connect.md), [v.import](v.import.md),
[v.info](v.info.md), [v.in.lines](v.in.lines.md),
[v.in.mapgen](v.in.mapgen.md), [v.out.ascii](v.out.ascii.md)*

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

## SOURCE CODE

Available at: [v.in.ascii source code](https://github.com/OSGeo/grass/tree/main/vector/v.in.ascii)
([history](https://github.com/OSGeo/grass/commits/main/vector/v.in.ascii))  
Latest change: Sunday Jul 27 05:53:30 2025 in commit [da40958](https://github.com/OSGeo/grass/commit/da409580ef15011f3bac379c76d41101c9e36347)
