1v.in.ascii(1) GRASS GIS User's Manual v.in.ascii(1)
2
3
4
6 v.in.ascii - Creates a vector map from an ASCII points file or ASCII
7 vector file.
8
10 vector, import, ASCII, level1, area, line, point
11
13 v.in.ascii
14 v.in.ascii --help
15 v.in.ascii [-zentbri] input=name output=name [format=string] [sepa‐
16 rator=character] [text=character] [skip=integer] [columns=string]
17 [x=integer] [y=integer] [z=integer] [cat=integer] [--overwrite]
18 [--help] [--verbose] [--quiet] [--ui]
19
20 Flags:
21 -z
22 Create 3D vector map
23
24 -e
25 Create a new empty vector map and exit. Nothing is read from input.
26
27 -n
28 Do not expect a header when reading in standard format
29
30 -t
31 Do not create table in points mode
32
33 -b
34 Do not build topology
35 Do not build topology in points mode
36
37 -r
38 Only import points falling within current region (points mode)
39
40 -i
41 Ignore broken line(s) in points mode
42
43 --overwrite
44 Allow output files to overwrite existing files
45
46 --help
47 Print usage summary
48
49 --verbose
50 Verbose module output
51
52 --quiet
53 Quiet module output
54
55 --ui
56 Force launching GUI dialog
57
58 Parameters:
59 input=name [required]
60 Name of input file to be imported
61 ’-’ for standard input
62
63 output=name [required]
64 Name for output vector map
65
66 format=string
67 Input file format
68 Options: point, standard
69 Default: point
70 point: simple x,y[,z] list
71 standard: GRASS vector ASCII format
72
73 separator=character
74 Field separator
75 Special characters: pipe, comma, space, tab, newline
76 Default: pipe
77
78 text=character
79 Text delimiter
80 Special characters: doublequote, singlequote, none
81
82 skip=integer
83 Number of header lines to skip at top of input file (points mode)
84 Default: 0
85
86 columns=string
87 Column definition in SQL style (points mode)
88 For example: ’x double precision, y double precision, cat int, name
89 varchar(10)’
90
91 x=integer
92 Number of column used as x coordinate (points mode)
93 First column is 1
94 Default: 1
95
96 y=integer
97 Number of column used as y coordinate (points mode)
98 First column is 1
99 Default: 2
100
101 z=integer
102 Number of column used as z coordinate (points mode)
103 First column is 1. If 0, z coordinate is not used
104 Default: 0
105
106 cat=integer
107 Number of column used as category (points mode)
108 First column is 1. If 0, unique category is assigned to each row
109 and written to new column ’cat’
110 Default: 0
111
113 v.in.ascii converts a vector map in GRASS ASCII vector format to a vec‐
114 tor map in binary format. The module may import two formats:
115
116 • standard contains all data types, each coordinate on one row
117
118 • point (default) reads only points, each point defined on one
119 row. Values are separated by a user-definable delimiter. If the
120 columns option is not defined, default names are used. It is
121 possible to specify the column order for the x,y,z coordinates
122 and category values.
123
124 v.out.ascii performs the function of v.in.ascii in reverse; i.e., it
125 converts vector maps in binary format to GRASS ASCII vector format.
126 These two companion programs are useful both for importing and export‐
127 ing vector maps between GRASS and other software, and for transferring
128 data between machines.
129
131 The input is read from the file specified by the input option or from
132 standard input.
133
134 The field separator may be a character, the word ’tab’ (or ’\t’) for
135 tab, ’space’ (or ’Â ’) for a blank, or ’comma’ (or ’,’) for a comma.
136
137 An attribute table is only created if it is needed, i.e. when at least
138 one attribute column is present in the input file besides geometry col‐
139 umns. The attribute column will be auto-scanned for type, but may be
140 explicitly declared along with the geometry columns using the columns
141 parameter.
142
143 Use the -z flag to convert ASCII data into a 3D vector map.
144
145 In special cases of data import, such as the import of large LIDAR
146 datasets (millions of data points), it may be necessary to disable
147 topology support (vector level 1) due to memory constraints. This is
148 done with the -b flag. As only very few vector modules support points
149 data processing at vector level 1, usually topology is required (vector
150 level 2). Therefore it is recommended that the user first try to import
151 the data without creating a database (the -t flag) or within a subre‐
152 gion (the -r flag) before resorting to the disabling of topology.
153
154 If old version is requested, the output files from v.out.ascii is
155 placed in the $LOCATION/$MAPSET/dig_ascii/ and $LOCA‐
156 TION/$MAPSET/dig_att directory.
157
158 Import of files without category column
159 If the input file does not contain a category column, there is the pos‐
160 sibility to auto-generate these IDs (categories). To automatically add
161 an additional column named ’cat’, the cat parameter must be set to the
162 virtual column number 0 (cat=0). This is the default action if the cat
163 parameter is not set.
164
165 Importing from a spreadsheet
166 Data may be imported from many spreadsheet programs by saving the
167 spreadsheet as a comma separated variable (.csv) text file, and then
168 using the separator=’,’ or separator=comma option with v.in.ascii in
169 points mode. If the input file contains any header lines, such as col‐
170 umn headings, the skip parameter should be used. These skipped header
171 lines will be written to the map’s history file for later reference
172 (read with v.info -h). The skip option only works in points mode.
173
174 Any line starting with the hash character (’#’) will be treated as a
175 comment and skipped completely if located in the main data file. If lo‐
176 cated in the header, as defined by the skip parameter, it will be
177 treated as a header line and written to the history file.
178
179 Import of sexagesimal degree (degree, minutes, seconds, DMS)
180 The import of DMS formatted degrees is supported (in this case no sign
181 but N/S, E/W characters are used to indicate the hemispheres). While
182 the positions are internally translated into decimal degrees during the
183 import, the original DMS values are maintained in the attribute table.
184 This requires both the latitude and the longitude columns to be defined
185 as varchar(), not as numbers. A warning will be issued which can be
186 ignored. See GRASS ASCII vector format specification for details.
187
188 Importing only selected columns
189 Although v.in.ascii doesn’t have an option to specify which columns
190 should be imported, you can use a shell filter to achieve the same ef‐
191 fect, e.g.:
192 # Print out the column number for each field, supposing the file has a header
193 head -1 input_file | tr ’<the_field_separator_character>’ ’\n’ | cat -n
194 # From the listing, select the columns you want and feed them to v.in.ascii
195 # use input=- to read from stdin
196 cut -d<the_field_separator_character> -f<comma-separated_list_of_columns> input_file | v.in.ascii in=- <your_options>
197
199 Example 1a) - standard format mode
200 Sample ASCII polygon vector map for ’standard’ format mode. The two
201 areas will be assigned categories 20 and 21. For details on the struc‐
202 ture of standard format data files see the second reference at the bot‐
203 tom of this page.
204
205 echo "ORGANIZATION: GRASS Development Team
206 DIGIT DATE: 1/9/2005
207 DIGIT NAME: -
208 MAP NAME: test
209 MAP DATE: 2005
210 MAP SCALE: 10000
211 OTHER INFO: Test polygons
212 ZONE: 0
213 MAP THRESH: 0.500000
214 VERTI:
215 B 6
216 5958812.48844435 3400828.84221011
217 5958957.29887089 3400877.11235229
218 5959021.65906046 3400930.7458436
219 5959048.47580612 3400973.65263665
220 5959069.92920264 3401032.64947709
221 5958812.48844435 3400828.84221011
222 C 1 1
223 5958952.42189184 3400918.23126419
224 1 20
225 B 4
226 5959010.9323622 3401338.36037757
227 5959096.7459483 3401370.54047235
228 5959091.38259917 3401450.99070932
229 5959010.9323622 3401338.36037757
230 C 1 1
231 5959063.08352122 3401386.98533277
232 1 21" | v.in.ascii in=- format=standard output=test_polygons
233
234 Example 1b) - standard format mode
235 Sample ASCII 3D line vector map for ’standard’ format mode with simpli‐
236 fied input (note the space field separator). Note the -z flag indicat‐
237 ing 3D vector input, and the -n flag indicating no vector header should
238 be expected from the input file. The first line in this example speci‐
239 fies that the line (L) has 5 vertices and 1 category. The last line
240 specifies the layer (1) and the category value (321).
241 echo "L 5 1
242 591336 4927369 1224
243 594317 4925341 1292
244 599356 4925162 1469
245 602396 4926653 1235
246 607524 4925431 1216
247 1 321 " | v.in.ascii -zn in=- out=line3d format=standard
248 This can be used to create a vector line of a GPS track: the GPS points
249 have to be stored into a file with a preceding ’L’ and the number of
250 points (per line).
251
252 Example 2 - point format mode
253 Generate a 2D points vector map ’coords.txt’ as ASCII file:
254 1664619|5103481
255 1664473|5095782
256 1664273|5101919
257 1663427|5105234
258 1663709|5102614
259
260 Import into GRASS:
261 v.in.ascii input=coords.txt output=mymap
262 As the cat option is set to 0 by default, an extra column ’cat’ con‐
263 taining the category numbers will be auto-generated.
264
265 Example 3 - point format mode
266 Generate a 2D points vector map ’points.dat’ as ASCII file:
267 1|1664619|5103481|studna
268 2|1664473|5095782|kadibudka
269 3|1664273|5101919|hruska
270 4|1663427|5105234|mysi dira
271 5|1663709|5102614|mineralni pramen
272
273 Import into GRASS:
274 cat points.dat | v.in.ascii in=- out=mypoints x=2 y=3 cat=1 \
275 columns=’cat int, x double precision, y double precision, label varchar(20)’
276
277 The module is reading from standard input, using the default ’|’ (pipe)
278 delimiter.
279
280 Example 4 - point format mode - CSV table
281 Import of a 3D points CSV table (’points3d.csv’) with attributes:
282 "num","X","Y","Z","T"
283 1,2487491.643,5112118.33,120.5,18.62
284 2,2481985.459,5109162.78,123.9,18.46
285 3,2478284.289,5105331.04,98.3,19.61
286
287 Import into GRASS:
288 # import: skipping the header line, categories generated automatically,
289 # column names defined with type:
290 v.in.ascii -z in=points3d.csv out=mypoints3D separator=comma \
291 columns="num integer, x double precision, y double precision, z double precision, temp double precision" \
292 x=2 y=3 z=4 skip=1
293 # verify column types
294 v.info -c mypoints3D
295 # verify table content
296 v.db.select mypoints3D
297
298 Example 5 - point format mode
299 Generating a 3D points vector map from DBMS (idcol must be an integer
300 column):
301 echo "select east,north,elev,idcol from mytable" | db.select -c | v.in.ascii in=- -z out=mymap
302 With in=-, the module is reading from standard input, using the default
303 ’|’ (pipe) delimiter.
304 The import works for 2D maps as well (no elev column and no ’-z’ flag).
305
306 Example 6 - point format mode
307 Generate a 3D points vector map ’points3d.dat’ with attributes as ASCII
308 file:
309 593493.1|4914730.2|123.1|studna|well
310 591950.2|4923000.5|222.3|kadibudka|outhouse
311 589860.5|4922000.0|232.3|hruska|pear
312 590400.5|4922820.8|143.2|mysi dira|mouse hole
313 593549.3|4925500.7|442.6|mineralni pramen|mineral spring
314 600375.7|4925235.6|342.2|kozi stezka|goat path
315
316 Import into GRASS:
317 #As the ’cat’ option is set to 0 by default, an extra column ’cat’
318 #containing the IDs will be auto-generated (no need to define that):
319 cat points3d.dat | v.in.ascii in=- -z z=3 cat=0 out=mypoints3D \
320 columns=’x double precision, y double precision, z double precision, \
321 label_cz varchar(20), label_en varchar(20)’
322 v.info -c mypoints3D
323 v.info mypoints3D
324
325 Example 7 - point format mode
326 Generate points file by clicking onto the map:
327 #For LatLong locations:
328 d.where -d -l | awk ’{printf "%f|%f|point\n", $1, $2}’ | v.in.ascii in=- out=points \
329 columns=’x double precision, y double precision, label varchar(20)’
330 #For other projections:
331 d.where | awk ’{printf "%f|%f|point\n", $1, $2}’ | v.in.ascii in=- out=points \
332 columns=’x double precision, y double precision, label varchar(20)’
333 The ’point’ string (or some similar entry) is required to generate a
334 database table. When simply piping the coordinates (and optionally
335 height) without additional column(s) into v.in.ascii, only the vector
336 map geometry will be generated.
337
338 Example 8 - point format mode
339 Convert ground control points into vector points:
340 cat $MAPSET/group/$GROUP/POINTS | v.in.ascii in=- out=$GROUP_gcp separator=space skip=3 \
341 col=’x double precision, y double precision, x_target double precision, \
342 y_target double precision, ok int’
343
345 SQL command notes for creating databases
346 GRASS ASCII vector format specification
347
349 db.execute, r.in.ascii, r.in.poly, r.in.xyz, v.build, v.build.poly‐
350 lines, v.centroids, v.clean, v.db.connect, v.import, v.info,
351 v.in.lines, v.in.mapgen, v.out.ascii
352
354 Michael Higgins, U.S.Army Construction Engineering Research Laboratory
355 James Westervelt, U.S.Army Construction Engineering Research Laboratory
356 Radim Blazek, ITC-Irst, Trento, Italy
357
359 Available at: v.in.ascii source code (history)
360
361 Accessed: Saturday Oct 28 18:18:32 2023
362
363 Main index | Vector index | Topics index | Keywords index | Graphical
364 index | Full index
365
366 © 2003-2023 GRASS Development Team, GRASS GIS 8.3.1 Reference Manual
367
368
369
370GRASS 8.3.1 v.in.ascii(1)