GRASS logo

NAME - Creates multiple vector layers from just one textfile


vector, import, ASCII, multiple

SYNOPSIS --help [-zentrx] input=name [separator=character] [pt_rules=string[,string,...]] [ln_rules=string[,string,...]] [poly_rules=string[,string,...]] [skip=integer] [columns=string] [easting=integer] [northing=integer] [elevation=integer] [outdir=name] [merge_lyrs=string[,string,...]] [dxf_file=string] [draw_unit=string] [textsize=string] [--help] [--verbose] [--quiet] [--ui]


Create 3D vector map
Create a new empty vector map and exit. Nothing is read from input.
Do not expect a header when reading in standard format
Do not create table in points mode
Only import points falling within current region (points mode)
Convert to DXF
Print usage summary
Verbose module output
Quiet module output
Force launching GUI dialog


input=name [required]
Name of input file to be imported
Field separator
Special characters: pipe, comma, space, tab, newline
Default: pipe
Point(s):, forest.tree.01 -> 'pt,tree'
Line(s): road.ln.01..., Danube.river.01 -> 'ln,river'
Polygon(s): hosp.area.01,..., forest.area.01 -> 'area'
Number of lines to skip at top of input file (points mode)
Default: 0
Column definition in SQL style (points mode))
E.g.: 'x double precision, y double precision, cat int, name varchar(10)'
Number of column used as easting coordinate (points mode)
First column is 1
Default: 2
Number of column used as northing coordinate (points mode)
First column is 1
Default: 3
Number of column used as elevation (points mode)
First column is 1. If 0, z coordinate is not used
Default: 0
Name of directory to store separated files for each layer
Pattern(s) for layers to be merged
Name of the DXF file
Drawing units
Options: metric, imperial
Default: metric
Text height of the labels in DXF file
Default: 0.

Table of contents

DESCRIPTION imports points from ASCII file into specific vector layers by point names. The script joins several modules to perform following steps:


Input data

Several recommendations how to format the data:

Conversion to DXF

If you wish to convert the data to DXF, please use -x flag. Then, it is necessary to set up: Output drawing consists of geometry layers (point, line and polygon) supplemented with text. The text layers contain elevation of the vertices and labels of the points and of the objects as Fig. 4 shows.


This example is based on the sample dataset of North Carolina (nc_spm_08_grass7). Point vector layer hospitals, line vector layer railroads and polygon vector layer soil_general have been exported to the text files, vertices have been renamed and the files have been merged. This final input was used as test data for the script. input=test_data.dat separator=tab skip=1 easting=2 northing=3 pt_rules=pt ln_rules=ln poly_rules=poly outdir=NC_test
As might be seen in Fig. 1, points and lines fit original dataset well, but areas are broken. This is caused by input data - it was created exporting lines from areas and then exporting points from lines. Boundary of each area was split into lines according to topological rule that vertices of the line are given by its intersection with at least two other lines. Thus, each new area was generated as the space surrounded by a line and connection between its vertices.

Fig. 1: Imported features with broken areas Fig. 2: Lines with the directions Fig. 3: Imported features with correct areas
Broken areas Criteria for the reconstruction of the boundaries Correct areas

To fix broken areas, original lines have been merged using v.edit according to their categories. Then points have been exported again and they were copied to enclose each area - respecting lines and the directions as might be seen in Fig. 2. In Fig. 3, there is shown that areas fit well too after editing input file.

If it is necessary also to merge some of the layers, then merging rules can be set up: input=test_data_small_corrected_soils.dat separator=tab easting=2 northing=3 pt_rules=pt ln_rules=ln poly_rules=poly \
	outdir=NC_test_small_merge merge_lyrs=road,soil

Fig. 1: DXF drawing together with the labels
(north arrow and scale have been added later)

The colours in DXF drawing have been set up automatically. In this case, labels of roads and elevation labels of soil types have been switched of because of too large amount of the data. Examples of more detailed exports can be seen in (Stopkova, 2016).


WARNING: There are no layers to merge into <item>.
Any imported layer does not match given item referring how to merge layers in script settings.


Input data:

ERROR: Too many columns. Use input data in format 'name east north [elev]', please.
Current version supports only import of 2D or 3D geometry and point name. Edit input file and run script again.

ERROR: Please rename point in line i according to the script request in format 'lyr_name.vect_type_code.number'.
Point name is expected to provide information in particular format. Edit point name in ith line of the input file and run script again.

ERROR: Please do not use SQL forbidden characters in your input data. Remove all 'char' from the file.
Any special characters are not allowed in the data. Please use just dots to separate parts of point names. If necessary, make the names more clear using underscores.

ERROR: Not enough points to make line layer <layer>.
ERROR: Not enough points to make polygon layer <layer>.
These errors may refer to:

Script settings:

ERROR: Wrong separator type.
The separator does not fit the data file. Please set up another type: pipe, comma, space, tab, newline. Default: pipe

ERROR: Vector layer layer is not point, neither line, nor boundary. Please check your input data and rules that you have typed in.
Vector type information (middle part of the point name) does not match to any of geometry codes that you have entered. Please compare input settings with point names in the data file, complete input settings (or edit input data) and run the script again.

ERROR: Please redefine merging option <char>. Different vector types match this rule.
Merging different vector types is not allowed. This might be matter of comparing layer names with too free rules:

Tab. 1: Example of too free rules for merging layers
river river -> river_stream
river_stream_Danube river_area_Danube
river_stream_Vah river_stream_Vah
river_stream_Hron river_stream_Hron

In the left column, there are summarized line objects that should be merged to one single layers called river. This merge is possible, as all the features are represented by line. In the right column, there are summarized rivers as well. But they cannot be merged, because the Danube river is represented by polygon and the rest of the features are lines. It would be better to use merging criteria river_stream to separate just line object to be merged.


ERROR: File filename does not exist.
Missing input file.

Output layers:

ERROR: Vector layer <layer> exists. Please remove the layer or rename the input points.
There is a layer with identical name in the mapset. Overwrite it, rename it or rename the layer in the input file (edit points names). However, this error usually happens if points that belong to several layers are mixed in the file as well. How to prevent this, examples in (Stopkova, 2016) can demonstrate.

Empty layer (not reported in command output): if the layer exists but is empty, please check the input points. This might happened because of wrong point order (especially if the point order has been edited).

DXF conversion:

ERROR: Please set up the drawing units to 'metric' or to 'imperial'.
Anything else cannot be accepted (in accordance to DXF settings). Default value: metric.

SEE ALSO, v.centroids, g.remove, v.db.addtable, v.db.update, v.patch, v.clean, v.out.dxf

Stopkova, E. (in print). Open-source tool for automatic import of coded surveying data to multiple vector layers in GIS environment. In Geoinformatics FCE CTU. Vol. 15, No. 2 (2016). Prague: Czech Technical University, Faculty of Civil Engineering. ISSN 1802-2669. DOI.


Eva Stopkova
functions for DXF conversion are taken from (or based on) the module v.out.dxf (Charles Ehlschlaeger and Radim Blazek)


Available at: source code (history)

Latest change: Monday Jan 30 19:52:26 2023 in commit: cac8d9d848299297977d1315b7e90cc3f7698730

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

© 2003-2024 GRASS Development Team, GRASS GIS 8.3.3dev Reference Manual