1v.in.ascii(1) Grass User's Manual v.in.ascii(1)
2
6 v.in.ascii - Creates a vector map from ASCII points file or ASCII vec‐
7 tor file.
8
10 vector, import
11
13 v.in.ascii
14 v.in.ascii help
15 v.in.ascii [-zentbr] [input=name] output=name [format=string]
16 [fs=character] [skip=integer] [columns=name] [x=integer]
17 [y=integer] [z=integer] [cat=integer] [--overwrite] [--verbose]
18 [--quiet]
19 Flags:
21 -z
22 Create 3D file
23 -e
25 Create a new empty map and exit. Nothing is read from input
26 -n
28 Don't 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 in points mode
35 -r
37 Only import points falling within current region (points mode)
38 --overwrite
40 Allow output files to overwrite existing files
41 --verbose
43 Verbose module output
44 --quiet
46 Quiet module output
47 Parameters:
49 input=name
50 ASCII file to be imported, if not given reads from standard input
51 output=name
53 Name for output vector map
54 format=string
56 Input file format
57 Options: point,standard
58 Default: point
59 fs=character
61 Field separator
62 Default: |
63 skip=integer
65 Number of header lines to skip at top of input file (points mode)
66 Default: 0
67 columns=name
69 Column definition in SQL style (points mode)
70 For example: 'x double precision, y double precision, cat int, name
71 varchar(10)'
72 x=integer
74 Number of column used as x coordinate (first column is 1) for
75 points mode
76 Default: 1
77 y=integer
79 Number of column used as y coordinate (first column is 1) for
80 points mode
81 Default: 2
82 z=integer
84 Number of column used as z coordinate (first column is 1) for
85 points mode
86 If 0, z coordinate is not used
87 Default: 0
88 cat=integer
90 Number of column used as category (first column is 1) for points
91 mode
92 If 0, unique category is assigned to each row and written to new
93 column 'cat'
94 Default: 0
95
97 v.in.ascii converts a vector map in ASCII format to a vector map in
98 binary format. The module may import two formats:
99 standard contains all data types, each coordinate on one
101 row
102 point (default) reads only points, each point defined on
104 one row. Values are separated by a user definable delimi‐
105 nator. If the columns option is not defined, default
106 names are used. It is possible to specify the column
107 order for the x,y,z coordinates and category values.
108 The v.out.ascii GRASS module performs the function of v.in.ascii in
110 reverse; i.e., it converts vector maps in binary format to ASCII for‐
111 mat. These two companion programs are useful both for importing and
112 exporting vector maps between GRASS and other software, and for trans‐
113 ferring data between machines.
114
116 The input is read from the file specified by the input option or from
117 standard input.
118 The field separator may be a character, the word 'tab' (or '\t') for
120 tab, or 'space' (or ' ') for a blank.
121 Attribute table is only created if it is needed, i.e. when at least one
123 attribute column is present in the input file besides geometry columns.
124 The attribute column will be auto-scanned for type, but may be explic‐
125 itly declared along with the geometry columns using the columns parame‐
126 ter.
127 Latitude/Longitude data may be given in a number of ways. Decimal
129 degrees must be positive or negative instead of using a hemisphere let‐
130 ter. Mixed coordinates must use a hemisphere letter. Whole minutes and
131 seconds must always contain two digits (example: use 167:03:04.567; and
132 not 167:3:4.567).
133 Acceptable formats:
134 key: D=Degrees; M=Minutes; S=Seconds; h=Hemisphere (N,S,E,W)
135 (+/-)DDD.DDDDD
137 DDDh
139 DDD:MMh
141 DDD:MM.MMMMMh
143 DDD:MM:SSh
145 DDD:MM:SS.SSSSSh
147 Use the -z flag to convert ASCII data into a 3D vector map.
149 In special cases of data import, such as the import of large LIDAR
151 datasets (millions of data points), it may be necessary to disable
152 topology support (creating a GRASS vector level 1 vector map) due to
153 memory constraints. This is done with the -b flag. As only very few
154 vector modules support points data processing at vector level 1, usu‐
155 ally topology is required (vector level 2). Therefore it is recommened
156 that the user first try to import the data without creating a database
157 (the -t flag) or within a subregion (the -r flag) before resorting the
158 to disabling of topology.
159 A GRASS ASCII vector map (in standard mode) may contain a mix of primi‐
161 tives including points, lines, boundaries, centroids, areas, faces, and
162 kernels.
163 On top a header can be defined (see example below). The header is not
164 required if the -n flag is used.
165 The header is similar as the head file of vector binary format but con‐
167 tains bounding box also. Key words are:
168 ORGANIZATION
169 DIGIT DATE
170 DIGIT NAME
171 MAP NAME
172 MAP DATE
173 MAP SCALE
174 OTHER INFO
175 ZONE
176 WEST EDGE
177 EAST EDGE
178 SOUTH EDGE
179 NORTH EDGE
180 MAP THRESH
181 The body begins with the row:
184 VERTI:
185 followed by records of primitives:
186 TYPE NUMBER_OF_COORDINATES [NUMBER_OF_CATEGORIES]
187 X Y [Z]
188 X Y [Z]
189 [ LAYER CATEGORY]
190 [ LAYER CATEGORY]
191 Everything above in [ ] is optional.
192 The primitive codes are as follows:
194 ’P': point
196 ’L': line
198 ’B': boundary
200 ’C': centroid
202 ’F': face (3D boundary)
204 ’K': kernel (3D centroid)
206 ’A': area (boundary) - better use 'B'; kept only for
208 backward compatibility
209 The coordinates are listed following the initial line containing the
210 primitive code, the total number of vectors in the series, and (option‐
211 ally) the number of categories (1 for a single layer, higher for multi‐
212 ple layers). Below that 1 or several lines follow to indicate the
213 layer number and the category number (ID).
214 The order of coordinates is
215 X Y [Z]
216 Import of files without category ID column
219 If the input file does not contain a vector ID column, there is the
220 possibility to auto-generate these IDs (categories). To automatically
221 add an additional column named 'cat', the cat parameter must be set to
222 the virtual column number 0 (cat=0). This is the default action if the
223 cat parameter is not set.
224 Importing from a spreadsheet
226 Data may be imported from many spreadsheet programs by saving the
227 spreadsheet as a comma separated variable (.csv) text file, and then
228 using the fs=',' option with v.in.ascii in points mode. If the input
229 file contains any header lines, such as column headings, the skip
230 parameter should be used. These skipped header lines will be written to
231 the map's history file for later reference (read with v.info -h). The
232 skip option only works in points mode.
233 Any line starting with the hash character ('#') will be treated as a
235 comment and skipped completely if located in the main data file. If
236 located in the header, as defined by the skip parameter, it will be
237 treated as a header line and written to the history file.
238 Import of sexagesimal degree (degree, minutes, seconds, DMS)
240 The import of DMS formatted degrees is supported (in this case no sign
241 but N/S, E/W characters are used to indicate the hemispheres). While
242 the positions are internally translated into decimal degrees during the
243 import, the original DMS values are maintained in the attribute table.
244 This requires both the latitude and the longitude columns to be defined
245 as varchars(), not as numbers. A warning will be issued which can be
246 ignored.
247 Importing only selected columns
249 Although v.in.ascii doesn't have an option to specify which columns
250 should be imported, you can use a shell filter to achieve the same
251 effect, e.g.:
252 # Print out the column number for each field, supposing the file has a
253 header
254 head -1 input_file | tr '<the_field_separator_character>' '\n' | cat -n
255 # From the listing, select the columns you want and feed them to
256 v.in.ascii
257 # do not use the input= option
258 cut -d<the_field_separator_character> -f<comma-separated_list_of_col‐
259 umns> input_file | v.in.ascii <your_options>
260
263 Example 1a) - standard mode
264 Sample ASCII polygon vector map for 'standard' mode. The two areas
265 will be assigned categories 20 and 21. The example can be tested in
266 the Spearfish sample dataset:
267 ORGANIZATION: GRASS Development Team
270 DIGIT DATE: 1/9/2005
271 DIGIT NAME: -
272 MAP NAME: test
273 MAP DATE: 2005
274 MAP SCALE: 10000
275 OTHER INFO: Test polygons
276 ZONE: 0
277 MAP THRESH: 0.500000
278 VERTI:
279 B 6
280 5958812.48844435 3400828.84221011
281 5958957.29887089 3400877.11235229
282 5959021.65906046 3400930.7458436
283 5959048.47580612 3400973.65263665
284 5959069.92920264 3401032.64947709
285 5958812.48844435 3400828.84221011
286 C 1 1
287 5958952.42189184 3400918.23126419
288 1 20
289 B 4
290 5959010.9323622 3401338.36037757
291 5959096.7459483 3401370.54047235
292 5959091.38259917 3401450.99070932
293 5959010.9323622 3401338.36037757
294 C 1 1
295 5959063.08352122 3401386.98533277
296 1 21
297 Example 1b) - standard mode
300 Sample ASCII 3D line vector map for 'standard' mode with simplified
301 input (no header). The example can be tested in the Spearfish sample
302 dataset:
303 echo "L 5 1
304 591336 4927369 1224
305 594317 4925341 1292
306 599356 4925162 1469
307 602396 4926653 1235
308 607524 4925431 1216
309 1 321 " | v.in.ascii -zn out=line3d format=standard
310 This can be used to create a vector line of a GPS track: the GPS
311 points have to be stored into a file with a preceding 'L' and the num‐
312 ber of points (per line).
313 Example 2
315 Generate a 2D points vector map 'coords.txt' as ASCII file:
316 1664619|5103481
317 1664473|5095782
318 1664273|5101919
319 1663427|5105234
320 1663709|5102614
321 Import into GRASS:
324 v.in.ascii input=coords.txt output=mymap
325 As the cat option is set to 0 by default, an extra column 'cat' con‐
326 taining the IDs will be auto-generated.
327 Example 3
329 Generate a 2D points vector map 'points.dat' as ASCII file:
330 1|1664619|5103481|studna
331 2|1664473|5095782|kadibudka
332 3|1664273|5101919|hruska
333 4|1663427|5105234|mysi dira
334 5|1663709|5102614|mineralni pramen
335 Import into GRASS:
338 cat points.dat | v.in.ascii out=mypoints x=2 y=3 cat=1 \
339 columns='cat int, x double precision, y double precision, label
340 varchar(20)'
341 The module is reading from standard input, using the default '|' (pipe)
344 delimiter.
345 Example 4
347 Generating a 3D points vector map from DBMS (idcol must be an integer
348 column):
349 echo "select east,north,elev,idcol from mytable" | db.select -c |
351 v.in.ascii -z out=mymap
352 The module is reading from standard input, using the default '|'
353 (pipe) delimiter.
354 The import works for 2D maps as well (no elev column and no '-z' flag).
355 Example 5
357 Generate a 3D points vector map 'points3d.dat' with attributes as ASCII
358 file:
359 593493.1|4914730.2|123.1|studna|well
360 591950.2|4923000.5|222.3|kadibudka|closet
361 589860.5|4922000.0|232.3|hruska|pear
362 590400.5|4922820.8|143.2|mysi dira|mouse hole
363 593549.3|4925500.7|442.6|mineralni pramen|mineral spring
364 600375.7|4925235.6|342.2|kozi stezka|goat path
365 Import into GRASS:
368 #As the 'cat' option is set to 0 by default, an extra column 'cat'
369 #containing the IDs will be auto-generated (no need to define that):
370 cat points3d.dat | v.in.ascii -z z=3 cat=0 out=mypoints3D \
371 columns='x double precision, y double precision, z double preci‐
372 sion, \
373 label_cz varchar(20), label_en varchar(20)'
374 v.info -c mypoints3D
375 v.info mypoints3D
376 Example 6
379 Generate points file by clicking onto the map:
380 #For LatLong locations:
381 d.where -d -l | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii
382 out=points \
383 columns='x double precision, y double precision, label varchar(20)'
384 #For other projections:
385 d.where | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii
386 out=points \
387 columns='x double precision, y double precision, label varchar(20)'
388 The 'point' string (or some similar entry) is required to generate a
389 database table. When simply piping the coordinates (and optionally
390 height) without additional column(s) into v.in.ascii, only the vector
391 map geometry will be generated.
392 Example 7
394 Convert ground control points from i.points into vector points:
395 cat $MAPSET/group/$GROUP/POINTS | v.in.ascii out=$GROUP_gcp fs=space
396 skip=3 \
397 col='x double precision, y double precision, x_target double preci‐
398 sion, \
399 y_target double precision, ok int'
400
403 SQL command notes for creating databases
404
406 db.execute, r.in.ascii, r.in.xyz, v.db.connect, v.out.ascii, v.info,
407 v.build, v.build.polylines, v.centroids, v.clean
408
410 Michael Higgins, U.S.Army Construction Engineering Research Laboratory
411 James Westervelt, U.S.Army Construction Engineering Research Laboratory
412 Radim Blazek, ITC-Irst, Trento, Italy
413 Last changed: $Date: 2007-11-29 14:34:20 +0100 (Thu, 29 Nov 2007) $
415 Full index
417 © 2003-2008 GRASS Development Team
419GRASS 6.3.0 v.in.ascii(1)