v.in.ascii.html 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310
  1. <h2>DESCRIPTION</h2>
  2. <em>v.in.ascii</em> converts a vector map
  3. in <a href="vectorascii.html">GRASS ASCII vector format</a> to a
  4. vector map in binary format. The module may import two formats:
  5. <ul>
  6. <li><b>standard</b> contains all data types, each coordinate on one row</li>
  7. <li><b>point</b> (default) reads only points, each point defined on
  8. one row. Values are separated by a user-definable delimiter. If
  9. the <b>columns</b> option is not defined, default names are used. It
  10. is possible to specify the column order for the x,y,z coordinates
  11. and category values.</li>
  12. </ul>
  13. <p><em><a href="v.out.ascii.html">v.out.ascii</a></em> performs the
  14. function of <em>v.in.ascii</em> in reverse; i.e., it converts vector
  15. maps in binary format to GRASS ASCII vector format. These two companion programs
  16. are useful both for importing and exporting vector maps between GRASS
  17. and other software, and for transferring data between machines.
  18. <h2>NOTES</h2>
  19. The input is read from the file specified by the <b>input</b> option or
  20. from standard input.
  21. <p>The field separator may be a character, the word '<tt>tab</tt>'
  22. (or '<tt>\t</tt>') for tab, '<tt>space</tt>' (or '&nbsp;') for a blank,
  23. or '<tt>comma</tt>' (or ',') for a comma.
  24. <p>An attribute table is only created if it is needed, i.e. when at
  25. least one attribute column is present in the input file besides
  26. geometry columns. The attribute column will be auto-scanned for type, but
  27. may be explicitly declared along with the geometry columns using the
  28. <b>columns</b> parameter.
  29. <p>Use the <b>-z</b> flag to convert ASCII data into a 3D vector map.
  30. <p>In special cases of data import, such as the import of large LIDAR
  31. datasets (millions of data points), it may be necessary to disable
  32. topology support (vector level 1) due to memory constraints. This is
  33. done with the <b>-b</b> flag. As only very few vector modules support
  34. points data processing at vector level 1, usually topology is required
  35. (vector level 2). Therefore it is recommended that the user first try
  36. to import the data without creating a database (the <b>-t</b> flag) or
  37. within a subregion (the <b>-r</b> flag) before resorting to the
  38. disabling of topology.
  39. <p>If old version is requested, the <b>output</b> files
  40. from <em><a href="v.out.ascii.html">v.out.ascii</a></em> is placed in
  41. the <tt>$LOCATION/$MAPSET/dig_ascii/</tt>
  42. and <tt>$LOCATION/$MAPSET/dig_att</tt> directory.
  43. <h3>Import of files without category column</h3>
  44. If the input file does not contain a category column, there is the
  45. possibility to auto-generate these IDs (categories). To automatically
  46. add an additional column named 'cat', the <b>cat</b> parameter must be
  47. set to the virtual column number 0 (<tt>cat=0</tt>). This is the
  48. default action if the <b>cat</b> parameter is not set.
  49. <h3>Importing from a spreadsheet</h3>
  50. Data may be imported from many spreadsheet programs by saving the
  51. spreadsheet as a comma separated variable (.csv) text file, and then
  52. using the <b>separator=','</b> or <b>separator=comma</b> option
  53. with <em>v.in.ascii</em> in <b>points</b> mode. If the input file
  54. contains any header lines, such as column headings, the
  55. <b>skip</b> parameter should be used. These skipped header lines will
  56. be written to the map's history file for later reference (read with
  57. <tt>v.info&nbsp;-h</tt>). The skip option only works in <b>points</b> mode.
  58. <p>Any line starting with the hash character ('<tt>#</tt>') will be treated as
  59. a comment and skipped completely if located in the main data file. If located
  60. in the header, as defined by the <b>skip</b> parameter, it will be treated as
  61. a header line and written to the history file.
  62. <h3>Import of sexagesimal degree (degree, minutes, seconds, DMS)</h3>
  63. The import of DMS formatted degrees is supported (in this case no sign
  64. but N/S, E/W characters are used to indicate the hemispheres). While
  65. the positions are internally translated into decimal degrees during
  66. the import, the original DMS values are maintained in the attribute
  67. table. This requires both the latitude and the longitude columns to be
  68. defined as <tt>varchar()</tt>, not as numbers. A warning will be
  69. issued which can be ignored. See <a href="vectorascii.html">GRASS
  70. ASCII vector format specification</a> for details.
  71. <h3>Importing only selected columns</h3>
  72. Although <em>v.in.ascii</em> doesn't have an option to specify which columns
  73. should be imported, you can use a shell filter to achieve the same effect,
  74. e.g.:
  75. <div class="code"><pre>
  76. # Print out the column number for each field, supposing the file has a header
  77. head -1 input_file | tr '&lt;the_field_separator_character&gt;' '\n' | cat -n
  78. # From the listing, select the columns you want and feed them to v.in.ascii
  79. # use input=- to read from stdin
  80. cut -d&lt;the_field_separator_character&gt; -f&lt;comma-separated_list_of_columns&gt; input_file | v.in.ascii in=- &lt;your_options&gt;
  81. </pre></div>
  82. <h2>EXAMPLES</h2>
  83. <h3>Example 1a) - standard format mode</h3>
  84. Sample ASCII polygon vector map for 'standard' format mode.
  85. The two areas will be assigned categories 20 and 21.
  86. <p><div class="code"><pre>
  87. echo "ORGANIZATION: GRASS Development Team
  88. DIGIT DATE: 1/9/2005
  89. DIGIT NAME: -
  90. MAP NAME: test
  91. MAP DATE: 2005
  92. MAP SCALE: 10000
  93. OTHER INFO: Test polygons
  94. ZONE: 0
  95. MAP THRESH: 0.500000
  96. VERTI:
  97. B 6
  98. 5958812.48844435 3400828.84221011
  99. 5958957.29887089 3400877.11235229
  100. 5959021.65906046 3400930.7458436
  101. 5959048.47580612 3400973.65263665
  102. 5959069.92920264 3401032.64947709
  103. 5958812.48844435 3400828.84221011
  104. C 1 1
  105. 5958952.42189184 3400918.23126419
  106. 1 20
  107. B 4
  108. 5959010.9323622 3401338.36037757
  109. 5959096.7459483 3401370.54047235
  110. 5959091.38259917 3401450.99070932
  111. 5959010.9323622 3401338.36037757
  112. C 1 1
  113. 5959063.08352122 3401386.98533277
  114. 1 21" | v.in.ascii in=- format=standard output=test_polygons
  115. </pre></div>
  116. <h3>Example 1b) - standard format mode</h3>
  117. Sample ASCII 3D line vector map for 'standard' format mode with simplified input
  118. (note the space field separator).
  119. Note the <b>-z</b> flag indicating 3D vector input, and the <b>-n</b> flag
  120. indicating no vector header should be expected from the input file.
  121. <div class="code"><pre>
  122. echo "L 5 1
  123. 591336 4927369 1224
  124. 594317 4925341 1292
  125. 599356 4925162 1469
  126. 602396 4926653 1235
  127. 607524 4925431 1216
  128. 1 321 " | v.in.ascii -zn in=- out=line3d format=standard
  129. </pre></div>
  130. This can be used to create a vector line of a GPS track: the GPS points have
  131. to be stored into a file with a preceding 'L' and the number of points (per line).
  132. <h3>Example 2 - point format mode</h3>
  133. Generate a 2D points vector map 'coords.txt' as ASCII file:
  134. <div class="code"><pre>
  135. 1664619|5103481
  136. 1664473|5095782
  137. 1664273|5101919
  138. 1663427|5105234
  139. 1663709|5102614
  140. </pre></div>
  141. <p>Import into GRASS:
  142. <div class="code"><pre>
  143. v.in.ascii input=coords.txt output=mymap
  144. </pre></div>
  145. As the <b>cat</b> option is set to 0 by default, an extra column 'cat'
  146. containing the category numbers will be auto-generated.
  147. <h3>Example 3 - point format mode</h3>
  148. Generate a 2D points vector map 'points.dat' as ASCII file:
  149. <div class="code"><pre>
  150. 1|1664619|5103481|studna
  151. 2|1664473|5095782|kadibudka
  152. 3|1664273|5101919|hruska
  153. 4|1663427|5105234|mysi dira
  154. 5|1663709|5102614|mineralni pramen
  155. </pre></div>
  156. <p>Import into GRASS:
  157. <div class="code"><pre>
  158. cat points.dat | v.in.ascii in=- out=mypoints x=2 y=3 cat=1 \
  159. columns='cat int, x double precision, y double precision, label varchar(20)'
  160. </pre></div>
  161. <p>The module is reading from standard input, using the default '|' (pipe) delimiter.
  162. <h3>Example 4 - point format mode - CSV table</h3>
  163. Import of a 3D points CSV table ('points3d.csv') with attributes:
  164. <div class="code"><pre>
  165. "num","X","Y","Z","T"
  166. 1,2487491.643,5112118.33,120.5,18.62
  167. 2,2481985.459,5109162.78,123.9,18.46
  168. 3,2478284.289,5105331.04,98.3,19.61
  169. </pre></div>
  170. <p>Import into GRASS:
  171. <div class="code"><pre>
  172. # import: skipping the header line, categories generated automatically,
  173. # column names defined with type:
  174. v.in.ascii -z in=points3d.csv out=mypoints3D separator=comma \
  175. columns="num integer, x double precision, y double precision, z double precision, temp double precision" \
  176. x=2 y=3 z=4 skip=1
  177. # verify column types
  178. v.info -c mypoints3D
  179. # verify table content
  180. v.db.select mypoints3D
  181. </pre></div>
  182. <h3>Example 5 - point format mode</h3>
  183. Generating a 3D points vector map from DBMS (idcol must be an integer column):<br>
  184. <div class="code"><pre>
  185. echo "select east,north,elev,idcol from mytable" | db.select -c | v.in.ascii in=- -z out=mymap
  186. </pre></div>
  187. With <b>in=-</b>, the module is reading from standard input, using the default '|' (pipe) delimiter.
  188. <br>
  189. The import works for 2D maps as well (no elev column and no '-z' flag).
  190. <h3>Example 6 - point format mode</h3>
  191. Generate a 3D points vector map 'points3d.dat' with attributes as ASCII file:
  192. <div class="code"><pre>
  193. 593493.1|4914730.2|123.1|studna|well
  194. 591950.2|4923000.5|222.3|kadibudka|outhouse
  195. 589860.5|4922000.0|232.3|hruska|pear
  196. 590400.5|4922820.8|143.2|mysi dira|mouse hole
  197. 593549.3|4925500.7|442.6|mineralni pramen|mineral spring
  198. 600375.7|4925235.6|342.2|kozi stezka|goat path
  199. </pre></div>
  200. <p>Import into GRASS:
  201. <div class="code"><pre>
  202. #As the 'cat' option is set to 0 by default, an extra column 'cat'
  203. #containing the IDs will be auto-generated (no need to define that):
  204. cat points3d.dat | v.in.ascii in=- -z z=3 cat=0 out=mypoints3D \
  205. columns='x double precision, y double precision, z double precision, \
  206. label_cz varchar(20), label_en varchar(20)'
  207. v.info -c mypoints3D
  208. v.info mypoints3D
  209. </pre></div>
  210. <h3>Example 7 - point format mode</h3>
  211. Generate points file by clicking onto the map:
  212. <div class="code"><pre>
  213. #For LatLong locations:
  214. d.where -d -l | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii in=- out=points \
  215. columns='x double precision, y double precision, label varchar(20)'
  216. #For other projections:
  217. d.where | awk '{printf "%f|%f|point\n", $1, $2}' | v.in.ascii in=- out=points \
  218. columns='x double precision, y double precision, label varchar(20)'
  219. </pre></div>
  220. The 'point' string (or some similar entry) is required to generate a database table.
  221. When simply piping the coordinates (and optionally height) without additional column(s)
  222. into <em>v.in.ascii</em>, only the vector map geometry will be generated.
  223. <h3>Example 8 - point format mode</h3>
  224. Convert ground control points into vector points:
  225. <div class="code"><pre>
  226. cat $MAPSET/group/$GROUP/POINTS | v.in.ascii in=- out=$GROUP_gcp separator=space skip=3 \
  227. col='x double precision, y double precision, x_target double precision, \
  228. y_target double precision, ok int'
  229. </pre></div>
  230. <h2>REFERENCES</h2>
  231. <a href="sql.html">SQL command notes</a> for creating databases
  232. <br>
  233. <a href="vectorascii.html">GRASS ASCII vector format</a> specification
  234. <h2>SEE ALSO</h2>
  235. <em>
  236. <a href="db.execute.html">db.execute</a>,
  237. <a href="r.in.ascii.html">r.in.ascii</a>,
  238. <a href="r.in.xyz.html">r.in.xyz</a>,
  239. <a href="v.build.html">v.build</a>,
  240. <a href="v.build.polylines.html">v.build.polylines</a>,
  241. <a href="v.centroids.html">v.centroids</a>,
  242. <a href="v.clean.html">v.clean</a>,
  243. <a href="v.db.connect.html">v.db.connect</a>,
  244. <a href="v.import.html">v.import</a>,
  245. <a href="v.info.html">v.info</a>,
  246. <a href="v.out.ascii.html">v.out.ascii</a>
  247. </em>
  248. <h2>AUTHORS</h2>
  249. Michael Higgins,
  250. U.S.Army Construction Engineering
  251. Research Laboratory<br>
  252. James Westervelt, U.S.Army Construction Engineering
  253. Research Laboratory<br>
  254. Radim Blazek, ITC-Irst, Trento, Italy
  255. <p><i>Last changed: $Date$</i>