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