/usr/share/doc/grass-doc/html/r.in.xyz.html is in grass-doc 6.4.3-3.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 | <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
<html>
<head>
<title>GRASS GIS manual: r.in.xyz</title>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1">
<link rel="stylesheet" href="grassdocs.css" type="text/css">
</head>
<body bgcolor="white">
<img src="grass_logo.png" alt="GRASS logo"><hr align=center size=6 noshade>
<h2>NAME</h2>
<em><b>r.in.xyz</b></em> - Create a raster map from an assemblage of many coordinates using univariate statistics.
<h2>KEYWORDS</h2>
raster, import, LIDAR
<h2>SYNOPSIS</h2>
<b>r.in.xyz</b><br>
<b>r.in.xyz help</b><br>
<b>r.in.xyz</b> [-<b>sgi</b>] <b>input</b>=<em>name</em> <b>output</b>=<em>name</em> [<b>method</b>=<em>string</em>] [<b>type</b>=<em>string</em>] [<b>fs</b>=<em>character</em>] [<b>x</b>=<em>integer</em>] [<b>y</b>=<em>integer</em>] [<b>z</b>=<em>integer</em>] [<b>zrange</b>=<em>min,max</em>] [<b>zscale</b>=<em>float</em>] [<b>percent</b>=<em>integer</em>] [<b>pth</b>=<em>integer</em>] [<b>trim</b>=<em>float</em>] [--<b>overwrite</b>] [--<b>verbose</b>] [--<b>quiet</b>]
<h3>Flags:</h3>
<DL>
<DT><b>-s</b></DT>
<DD>Scan data file for extent then exit</DD>
<DT><b>-g</b></DT>
<DD>In scan mode, print using shell script style</DD>
<DT><b>-i</b></DT>
<DD>Ignore broken lines</DD>
<DT><b>--overwrite</b></DT>
<DD>Allow output files to overwrite existing files</DD>
<DT><b>--verbose</b></DT>
<DD>Verbose module output</DD>
<DT><b>--quiet</b></DT>
<DD>Quiet module output</DD>
</DL>
<h3>Parameters:</h3>
<DL>
<DT><b>input</b>=<em>name</em></DT>
<DD>ASCII file containing input data (or "-" to read from stdin)</DD>
<DT><b>output</b>=<em>name</em></DT>
<DD>Name for output raster map</DD>
<DT><b>method</b>=<em>string</em></DT>
<DD>Statistic to use for raster values</DD>
<DD>Options: <em>n,min,max,range,sum,mean,stddev,variance,coeff_var,median,percentile,skewness,trimmean</em></DD>
<DD>Default: <em>mean</em></DD>
<DT><b>type</b>=<em>string</em></DT>
<DD>Storage type for resultant raster map</DD>
<DD>Options: <em>CELL,FCELL,DCELL</em></DD>
<DD>Default: <em>FCELL</em></DD>
<DT><b>fs</b>=<em>character</em></DT>
<DD>Field separator</DD>
<DD>Special characters: newline, space, comma, tab</DD>
<DD>Default: <em>|</em></DD>
<DT><b>x</b>=<em>integer</em></DT>
<DD>Column number of x coordinates in input file (first column is 1)</DD>
<DD>Default: <em>1</em></DD>
<DT><b>y</b>=<em>integer</em></DT>
<DD>Column number of y coordinates in input file</DD>
<DD>Default: <em>2</em></DD>
<DT><b>z</b>=<em>integer</em></DT>
<DD>Column number of data values in input file</DD>
<DD>Default: <em>3</em></DD>
<DT><b>zrange</b>=<em>min,max</em></DT>
<DD>Filter range for z data (min,max)</DD>
<DT><b>zscale</b>=<em>float</em></DT>
<DD>Scale to apply to z data</DD>
<DD>Default: <em>1.0</em></DD>
<DT><b>percent</b>=<em>integer</em></DT>
<DD>Percent of map to keep in memory</DD>
<DD>Options: <em>1-100</em></DD>
<DD>Default: <em>100</em></DD>
<DT><b>pth</b>=<em>integer</em></DT>
<DD>pth percentile of the values</DD>
<DD>Options: <em>1-100</em></DD>
<DT><b>trim</b>=<em>float</em></DT>
<DD>Discard <trim> percent of the smallest and <trim> percent of the largest observations</DD>
<DD>Options: <em>0-50</em></DD>
</DL>
<h2>DESCRIPTION</h2>
The <em>r.in.xyz</em> module will load and bin ungridded x,y,z ASCII data
into a new raster map. The user may choose from a variety of statistical
methods in creating the new raster. Gridded data provided as a stream of
x,y,z points may also be imported.
<p>
<em>r.in.xyz</em> is designed for processing massive point cloud datasets,
for example raw LIDAR or sidescan sonar swath data. It has been tested with
datasets as large as tens of billion of points (705GB in a single file).
<!-- Doug Newcomb, US Fish & Wildlife Service -->
<p>
Available statistics for populating the raster are:<br>
<ul>
<table>
<tr><td><em>n</em></td> <td>number of points in cell</td></tr>
<tr><td><em>min</em></td> <td>minimum value of points in cell</td></tr>
<tr><td><em>max</em></td> <td>maximum value of points in cell</td></tr>
<tr><td><em>range</em></td> <td>range of points in cell</td></tr>
<tr><td><em>sum</em></td> <td>sum of points in cell</td></tr>
<tr><td><em>mean</em></td> <td>average value of points in cell</td></tr>
<tr><td><em>stddev</em></td> <td>standard deviation of points in cell</td></tr>
<tr><td><em>variance</em></td> <td>variance of points in cell</td></tr>
<tr><td><em>coeff_var</em></td><td>coefficient of variance of points in cell</td></tr>
<tr><td><em>median</em></td> <td>median value of points in cell</td></tr>
<tr valign="baseline"><td><em>percentile</em> </td>
<td>p<sup><i>th</i></sup> percentile of points in cell</td></tr>
<tr><td><em>skewness</em></td> <td>skewness of points in cell</td></tr>
<tr><td><em>trimmean</em></td> <td>trimmed mean of points in cell</td></tr>
</table><br>
<li><em>Variance</em> and derivatives use the biased estimator (n). [subject to change]
<li><em>Coefficient of variance</em> is given in percentage and defined as
<tt>(stddev/mean)*100</tt>.
</ul>
<br>
<h2>NOTES</h2>
<h3>Gridded data</h3>
If data is known to be on a regular grid <em>r.in.xyz</em> can reconstruct
the map perfectly as long as some care is taken to set up the region
correctly and that the data's native map projection is used. A typical
method would involve determining the grid resolution either by examining
the data's associated documentation or by studying the text file. Next scan
the data with <em>r.in.xyz</em>'s <b>-s</b> (or <b>-g</b>) flag to find the
input data's bounds. GRASS uses the cell-center raster convention where
data points fall within the center of a cell, as opposed to the grid-node
convention. Therefore you will need to grow the region out by half a cell
in all directions beyond what the scan found in the file. After the region
bounds and resolution are set correctly with <em>g.region</em>, run
<em>r.in.xyz</em> using the <i>n</i> method and verify that n=1 at all places.
<em>r.univar</em> can help. Once you are confident that the region exactly
matches the data proceed to run <em>r.in.xyz</em> using one of the <i>mean,
min, max</i>, or <i>median</i> methods. With n=1 throughout, the result
should be identical regardless of which of those methods are used.
<h3>Memory use</h3>
While the <b>input</b> file can be arbitrarily large, <em>r.in.xyz</em>
will use a large amount of system memory for large raster regions (10000x10000).
If the module refuses to start complaining that there isn't enough memory,
use the <b>percent</b> parameter to run the module in several passes.
In addition using a less precise map format (<tt>CELL</tt> [integer] or
<tt>FCELL</tt> [floating point]) will use less memory than a <tt>DCELL</tt>
[double precision floating point] <b>output</b> map. Methods such as <em>n,
min, max, sum</em> will also use less memory, while <em>stddev, variance,
and coeff_var</em> will use more.
The aggregate functions <em>median, percentile, skewness</em> and
<em>trimmed mean</em> will use even more memory and may not be appropriate
for use with arbitrarily large input files<!-- without a small value for percent= -->.
<!-- explained: memory use for regular stats will be based solely on region size,
but for the aggregate fns it will also depend on the number of data points. (?) -->
<p>
The default map <b>type</b>=<tt>FCELL</tt> is intended as compromise between
preserving data precision and limiting system resource consumption.
If reading data from a <tt>stdin</tt> stream, the program can only run using
a single pass.
<h3>Setting region bounds and resolution</h3>
You can use the <b>-s</b> scan flag to find the extent of the input data
(and thus point density) before performing the full import. Use
<em>g.region</em> to adjust the region bounds to match. The <b>-g</b> shell
style flag prints the extent suitable as parameters for <em>g.region</em>.
A suitable resolution can be found by dividing the number of input points
by the area covered. e.g.
<div class="code"><pre>
wc -l inputfile.txt
g.region -p
# points_per_cell = n_points / (rows * cols)
g.region -e
# UTM location:
# points_per_sq_m = n_points / (ns_extent * ew_extent)
# Lat/Lon location:
# points_per_sq_m = n_points / (ns_extent * ew_extent*cos(lat) * (1852*60)^2)
</pre></div>
<p>
If you only intend to interpolate the data with <em>r.to.vect</em> and
<em>v.surf.rst</em>, then there is little point to setting the region
resolution so fine that you only catch one data point per cell -- you might
as well use "<tt>v.in.ascii -zbt</tt>" directly.
<h3>Filtering</h3>
Points falling outside the current region will be skipped. This includes
points falling <em>exactly</em> on the southern region bound.
(to capture those adjust the region with "<tt>g.region s=s-0.000001</tt>";
see <em>g.region</em>)
<p>
Blank lines and comment lines starting with the hash symbol (<tt>#</tt>)
will be skipped.
<p>
The <b>zrange</b> parameter may be used for filtering the input data by
vertical extent. Example uses might include preparing multiple raster
sections to be combined into a 3D raster array with <em>r.to.rast3</em>, or
for filtering outliers on relatively flat terrain.
<p>
In varied terrain the user may find that <em>min</em> maps make for a good
noise filter as most LIDAR noise is from premature hits. The <em>min</em> map
may also be useful to find the underlying topography in a forested or urban
environment if the cells are over sampled.
<p>
The user can use a combination of <em>r.in.xyz</em> <b>output</b> maps to create
custom filters. e.g. use <em>r.mapcalc</em> to create a <tt>mean-(2*stddev)</tt>
map. [In this example the user may want to include a lower bound filter in
<em>r.mapcalc</em> to remove highly variable points (small <em>n</em>) or run
<em>r.neighbors</em> to smooth the stddev map before further use.]
<h3>Reprojection</h3>
If the raster map is to be reprojected, it may be more appropriate to reproject
the input points with <em>m.proj</em> or <em>cs2cs</em> before running
<em>r.in.xyz</em>.
<h3>Interpolation into a DEM</h3>
The vector engine's topographic abilities introduce a finite memory overhead
per vector point which will typically limit a vector map to approximately
3 million points (~ 1750^2 cells). If you want more, use the <em>r.to.vect</em>
<b>-b</b> flag to skip building topology. Without topology, however, all
you'll be able to do with the vector map is display with <em>d.vect</em> and
interpolate with <em>v.surf.rst</em>.
Run <em>r.univar</em> on your raster map to check the number of non-NULL cells
and adjust bounds and/or resolution as needed before proceeding.
<p>
Typical commands to create a DEM using a regularized spline fit:
<div class="code"><pre>
r.univar lidar_min
r.to.vect -z feature=point in=lidar_min out=lidar_min_pt
v.surf.rst layer=0 in=lidar_min_pt elev=lidar_min.rst
</pre></div>
<br>
<h2>EXAMPLE</h2>
Import the <a href="http://www.grassbook.org/data_menu2nd.phtml">Jockey's
Ridge, NC, LIDAR dataset</a>, and process into a clean DEM:
<div class="code"><pre>
# scan and set region bounds
r.in.xyz -s fs=, in=lidaratm2.txt out=test
g.region n=35.969493 s=35.949693 e=-75.620999 w=-75.639999
g.region res=0:00:00.075 -a
# create "n" map containing count of points per cell for checking density
r.in.xyz in=lidaratm2.txt out=lidar_n fs=, method=n zrange=-2,50
# check point density [rho = n_sum / (rows*cols)]
r.univar lidar_n | grep sum
# create "min" map (elevation filtered for premature hits)
r.in.xyz in=lidaratm2.txt out=lidar_min fs=, method=min zrange=-2,50
# zoom to area of interest
g.region n=35:57:56.25N s=35:57:13.575N w=75:38:23.7W e=75:37:15.675W
# check number of non-null cells (try and keep under a few million)
r.univar lidar_min | grep '^n:'
# convert to points
r.to.vect -z feature=point in=lidar_min out=lidar_min_pt
# interpolate using a regularized spline fit
v.surf.rst layer=0 in=lidar_min_pt elev=lidar_min.rst
# set color scale to something interesting
r.colors lidar_min.rst rule=bcyr -n -e
# prepare a 1:1:1 scaled version for NVIZ visualization (for lat/lon input)
r.mapcalc "lidar_min.rst_scaled = lidar_min.rst / (1852*60)"
r.colors lidar_min.rst_scaled rule=bcyr -n -e
</pre></div>
<br>
<h2>TODO</h2>
<ul>
<li> Support for multiple map output from a single run.<br>
<tt>method=string[,string,...] output=name[,name,...]</tt>
</ul>
<h2>BUGS</h2>
<ul>
<li> <em>n</em> map sum can be ever-so-slightly more than `<tt>wc -l</tt>`
with e.g. <tt>percent=10</tt> or less.
<br>Cause unknown.
<li> <em>n</em> map <tt>percent=100</tt> and <tt>percent=xx</tt> maps
differ slightly (point will fall above/below the segmentation line)
<br>Investigate with "<tt>r.mapcalc diff=bin_n.100 - bin_n.33</tt>" etc.
<br>Cause unknown.
<li> "<tt>nan</tt>" can leak into <em>coeff_var</em> maps.
<br>Cause unknown. Possible work-around: "<tt>r.null setnull=nan</tt>"
<!-- Another method: r.mapcalc 'No_nan = if(map == map, map, null() )' -->
</ul>
If you encounter any problems (or solutions!) please contact the GRASS
Development Team.
<h2>SEE ALSO</h2>
<i>
<a href="g.region.html">g.region</a><br>
<a href="m.proj.html">m.proj</a><br>
<a href="r.fillnulls.html">r.fillnulls</a><br>
<a href="r.in.ascii.html">r.in.ascii</a><br>
<a href="r.mapcalc.html">r.mapcalc</a><br>
<a href="r.neighbors.html">r.neighbors</a><br>
<a href="r.out.xyz.html">r.out.xyz</a><br>
<a href="r.to.rast3.html">r.to.rast3</a><br>
<a href="r.to.vect.html">r.to.vect</a><br>
<a href="r.univar.html">r.univar</a><br>
<a href="v.in.ascii.html">v.in.ascii</a><br>
<a href="v.surf.rst.html">v.surf.rst</a><br>
<br>
<a href="v.lidar.correction.html">v.lidar.correction</a>,
<a href="v.lidar.edgedetection.html">v.lidar.edgedetection</a>,
<a href="v.lidar.growing.html">v.lidar.growing</a>,
<a href="v.outlier.html">v.outlier</a>,
<a href="v.surf.bspline.html">v.surf.bspline</a>
</i>
<p>
<i><a href="http://www.ivarch.com/programs/pv.shtml">pv</a></i>
- The UNIX pipe viewer utility
<br><br>
<h2>AUTHORS</h2>
Hamish Bowman<br> <i>
Department of Marine Science<br>
University of Otago<br>
New Zealand</i><br>
<br>
Extended by Volker Wichmann to support the aggregate functions
<i>median, percentile, skewness</i> and <i>trimmed mean</i>.
<br>
<p>
<i>Last changed: $Date: 2012-06-20 02:33:07 -0700 (Wed, 20 Jun 2012) $</i>
<HR>
<P><a href="index.html">Main index</a> - <a href="raster.html">raster index</a> - <a href="full_index.html">Full index</a></P>
<P>© 2003-2013 <a href="http://grass.osgeo.org">GRASS Development Team</a></p>
</body>
</html>
|