1r.in.xyz(1) Grass User's Manual r.in.xyz(1)
2
6 r.in.xyz - Create a raster map from an assemblage of many coordinates
7 using univariate statistics.
8
10 raster
11
13 r.in.xyz
14 r.in.xyz help
15 r.in.xyz [-sg] input=name output=name [method=string] [type=string]
16 [fs=character] [x=integer] [y=integer] [z=integer]
17 [zrange=min,max] [percent=integer] [--overwrite] [--verbose]
18 [--quiet]
19 Flags:
21 -s
22 Scan data file for extent then exit
23 -g
25 In scan mode, print using shell script style
26 --overwrite
28 Allow output files to overwrite existing files
29 --verbose
31 Verbose module output
32 --quiet
34 Quiet module output
35 Parameters:
37 input=name
38 ASCII file containing input data (or "-" to read from stdin)
39 output=name
41 Name for output raster map
42 method=string
44 Statistic to use for raster values
45 Options: n,min,max,range,sum,mean,stddev,variance,coeff_var
46 Default: mean
47 type=string
49 Storage type for resultant raster map
50 Options: CELL,FCELL,DCELL
51 Default: FCELL
52 fs=character
54 Field separator
55 Default: |
56 x=integer
58 Column number of x coordinates in input file (first column is 1)
59 Default: 1
60 y=integer
62 Column number of y coordinates in input file
63 Default: 2
64 z=integer
66 Column number of data values in input file
67 Default: 3
68 zrange=min,max
70 Filter range for z data (min,max)
71 percent=integer
73 Percent of map to keep in memory
74 Options: 1-100
75 Default: 100
76
78 The r.in.xyz module will load and bin ungridded x,y,z ASCII data into a
79 new raster map. The user may choose from a variety of statistical meth‐
80 ods in creating the new raster.
81 r.in.xyz is designed for processing massive point cloud datasets, for
83 example raw LIDAR or sidescan sonar swath data.
84 Available statistics for populating the raster are:
86 | n | number of points in cell
87 | min | minimum value of points in cell
88 | max | maximum value of points in cell
89 | range | range of points in cell
90 | sum | sum of points in cell
91 | mean | average value of points in cell
92 | stddev | standard deviation of points in cell
93 | variance | variance of points in cell
94 | coeff_var | coefficient of variance of points in cell
95 Variance and derivatives use the biased estimator (n).
97 [subject to change]
98 Coefficient of variance is given in percentage and
100 defined as (stddev/mean)*100.
101
103 Memory use
104 While the input file can be arbitrarily large, r.in.xyz will use a
105 large amount of system memory for large raster regions (10000x10000).
106 If the module refuses to start complaining that there isn't enough mem‐
107 ory, use the percent parameter to run the module in several passes. In
108 addition using a less precise map format (CELL [integer] or FCELL
109 [floating point]) will use less memory than a DCELL [double precision
110 floating point] output map. Methods such as n, min, max, sum will also
111 use less memory, while stddev, variance, and coeff_var will use more.
112 The default map type=FCELL is intended as compromise between preserving
113 data precision and limiting system resource consumption. If reading
114 data from a stdin stream, the program can only run using a single pass.
115 Setting region bounds and resolution
117 You can use the -s scan flag to find the extent of the input data (and
118 thus point density) before performing the full import. Use g.region to
119 adjust the region bounds to match. The -g shell style flag prints the
120 extent suitable as parameters for g.region. A suitable resolution can
121 be found by dividing the number of input points by the area covered.
122 e.g.
123 wc -l inputfile.txt
124 g.region -p
125 # points_per_cell = n_points / (rows * cols)
126 g.region -e
127 # UTM location:
128 # points_per_sq_m = n_points / (ns_extent * ew_extent)
129 # Lat/Lon location:
130 # points_per_sq_m = n_points / (ns_extent * ew_extent*cos(lat) *
131 (1852*60)^2)
132 If you only intend to interpolate the data with r.to.vect and
135 v.surf.rst, then there is little point to setting the region resolution
136 so fine that you only catch one data point per cell -- you might as
137 well use "v.in.ascii -zbt" directly.
138 Filtering
140 Points falling outside the current region will be skipped. This
141 includes points falling exactly on the southern region bound. (to cap‐
142 ture those adjust the region with "g.region s=s-0.000001"; see
143 g.region)
144 Blank lines and comment lines starting with the hash symbol (#) will be
146 skipped.
147 The zrange parameter may be used for filtering the input data by verti‐
149 cal extent. Example uses might include preparing multiple raster sec‐
150 tions to be combined into a 3D raster array with r.to.rast3, or for
151 filtering outliers on relatively flat terrain.
152 In varied terrain the user may find that min maps make for a good noise
154 filter as most LIDAR noise is from premature hits. The min map may also
155 be useful to find the underlying topography in a forested or urban
156 environment if the cells are over sampled.
157 The user can use a combination of r.in.xyz output maps to create custom
159 filters. e.g. use r.mapcalc to create a mean-(2*stddev) map. [In this
160 example the user may want to include a lower bound filter in r.mapcalc
161 to remove highly variable points (small n) or run r.neighbors to smooth
162 the stddev map before further use.]
163 Reprojection
165 If the raster map is to be reprojected, it may be more appropriate to
166 reproject the input points with m.proj or cs2cs before running
167 r.in.xyz.
168 Interpolation into a DEM
170 The vector engine's topographic abilities introduce a finite memory
171 overhead per vector point which will typically limit a vector map to
172 approximately 3 million points (~ 1750^2 cells). If you want more, use
173 the r.to.vect -b flag to skip building topology. Without topology, how‐
174 ever, all you'll be able to do with the vector map is display with
175 d.vect and interpolate with v.surf.rst. Run r.univar on your raster
176 map to check the number of non-NULL cells and adjust bounds and/or res‐
177 olution as needed before proceeding.
178 Typical commands to create a DEM using a regularized spline fit:
180 r.univar lidar_min
181 r.to.vect -z feature=point in=lidar_min out=lidar_min_pt
182 v.surf.rst layer=0 in=lidar_min_pt elev=lidar_min.rst
183
186 Import the Jockey's Ridge, NC, LIDAR dataset, and process into a clean
187 DEM:
188 # scan and set region bounds
189 r.in.xyz -s fs=, in=lidaratm2.txt out=test
190 g.region n=35.969493 s=35.949693 e=-75.620999 w=-75.639999
191 g.region res=0:00:00.075 -a
192 # create "n" map containing count of points per cell for checking
193 density
194 r.in.xyz in=lidaratm2.txt out=lidar_n fs=, method=n zrange=-2,50
195 # check point density [rho = n_sum / (rows*cols)]
196 r.univar lidar_n | grep sum
197 # create "min" map (elevation filtered for premature hits)
198 r.in.xyz in=lidaratm2.txt out=lidar_min fs=, method=min zrange=-2,50
199 # zoom to area of interest
200 g.region n=35:57:56.25N s=35:57:13.575N w=75:38:23.7W e=75:37:15.675W
201 # check number of non-null cells (try and keep under a few million)
202 r.univar lidar_min | grep '^n:'
203 # convert to points
204 r.to.vect -z feature=point in=lidar_min out=lidar_min_pt
205 # interpolate using a regularized spline fit
206 v.surf.rst layer=0 in=lidar_min_pt elev=lidar_min.rst
207 # set color scale to something interesting
208 r.colors lidar_min.rst rule=bcyr -n -e
209 # prepare a 1:1:1 scaled version for NVIZ visualization (for
210 lat/lon input)
211 r.mapcalc "lidar_min.rst_scaled = lidar_min.rst / (1852*60)"
212 r.colors lidar_min.rst_scaled rule=bcyr -n -e
213
216 Support for advanced statistics (as from r.univar).
217 Especially useful for dealing with outliers would be
218 median and 5-10% trimmed means.
219 Support for multiple map output from a single run.
221 method=string[,string,...] output=name[,name,...]
222
224 n map sum can be ever-so-slightly more than `wc -l` with
225 e.g. percent=10 or less.
226 Cause unknown.
227 n map percent=100 and percent=xx maps differ slightly
229 (point will fall above/below the segmentation line)
230 Investigate with "r.mapcalc diff=bin_n.100 - bin_n.33"
231 etc.
232 Cause unknown.
233 "nan" can leak into coeff_var maps.
235 Cause unknown. Possible work-around: "r.null setnull=nan"
236 If you encounter any problems (or solutions!) please contact the GRASS
237 Development Team.
238
240 g.region, m.proj, r.fillnulls, r.in.ascii, r.mapcalc, r.neighbors,
241 r.to.rast3, r.to.vect, r.univar, r.univar2, v.in.ascii, v.surf.rst
242
244 Hamish Bowman
245 Department of Marine Science
247 University of Otago
248 New Zealand
249 Last changed: $Date: 2007-07-11 09:04:42 +0200 (Wed, 11 Jul 2007) $
251 Full index
253 © 2003-2008 GRASS Development Team
255GRASS 6.3.0 r.in.xyz(1)