1GDAL_GRID(1) GDAL GDAL_GRID(1)
2
6 gdal_grid - Creates regular grid from the scattered data.
7
9 gdal_grid [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
10 CInt16/CInt32/CFloat32/CFloat64}]
11 [-oo NAME=VALUE]*
12 [-of format] [-co "NAME=VALUE"]
13 [-zfield field_name] [-z_increase increase_value] [-z_multiply multiply_value]
14 [-a_srs srs_def] [-spat xmin ymin xmax ymax]
15 [-clipsrc <xmin ymin xmax ymax>|WKT|datasource|spat_extent]
16 [-clipsrcsql sql_statement] [-clipsrclayer layer]
17 [-clipsrcwhere expression]
18 [-l layername]* [-where expression] [-sql select_statement]
19 [-txe xmin xmax] [-tye ymin ymax] [-tr xres yres] [-outsize xsize ysize]
20 [-a algorithm[:parameter1=value1]*] [-q]
21 <src_datasource> <dst_filename>
22
24 This program creates regular grid (raster) from the scattered data read
25 from the OGR datasource. Input data will be interpolated to fill grid
26 nodes with values, you can choose from various interpolation methods.
27 It is possible to set the GDAL_NUM_THREADS configuration option to par‐
29 allelize the processing. The value to specify is the number of worker
30 threads, or ALL_CPUS to use all the cores/CPUs of the computer.
31 -ot <type>
33 Force the output image bands to have a specific data type sup‐
34 ported by the driver, which may be one of the following: Byte,
35 Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32,
36 Float64, CInt16, CInt32, CFloat32 or CFloat64.
37 -of <format>
39 Select the output format. Starting with GDAL 2.3, if not speci‐
40 fied, the format is guessed from the extension (previously was
41 GTiff). Use the short format name.
42 -txe <xmin> <xmax>
44 Set georeferenced X extents of output file to be created.
45 -tye <ymin> <ymax>
47 Set georeferenced Y extents of output file to be created.
48 -tr <xres> <yres>
50 Set output file resolution (in target georeferenced units).
51 Note that -tr just works in combination with a valid input from
52 -txe and -tye
53 New in version 3.2.
55 -outsize <xsize ysize>
58 Set the size of the output file in pixels and lines. Note that
59 -outsize cannot be used with -tr
60 -a_srs <srs_def>
62 Override the projection for the output file. The srs_def may be
63 any of the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or
64 a file containing the WKT. No reprojection is done.
65 -zfield <field_name>
67 Identifies an attribute field on the features to be used to get
68 a Z value from. This value overrides Z value read from feature
69 geometry record (naturally, if you have a Z value in geometry,
70 otherwise you have no choice and should specify a field name
71 containing Z value).
72 -z_increase <increase_value>
74 Addition to the attribute field on the features to be used to
75 get a Z value from. The addition should be the same unit as Z
76 value. The result value will be Z value + Z increase value. The
77 default value is 0.
78 -z_multiply <multiply_value>
80 This is multiplication ratio for Z field. This can be used for
81 shift from e.g. foot to meters or from elevation to deep. The
82 result value will be (Z value + Z increase value) * Z multiply
83 value. The default value is 1.
84 -a <[algorithm[:parameter1=value1][:parameter2=value2]...]>
86 Set the interpolation algorithm or data metric name and (option‐
87 ally) its parameters. See Interpolation algorithms and Data met‐
88 rics sections for further discussion of available options.
89 -spat <xmin> <ymin> <xmax> <ymax>
91 Adds a spatial filter to select only features contained within
92 the bounding box described by (xmin, ymin) - (xmax, ymax).
93 -clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent
95 Adds a spatial filter to select only features contained within
96 the specified bounding box (expressed in source SRS), WKT geome‐
97 try (POLYGON or MULTIPOLYGON), from a datasource or to the spa‐
98 tial extent of the -spat option if you use the spat_extent key‐
99 word. When specifying a datasource, you will generally want to
100 use it in combination of the -clipsrclayer, -clipsrcwhere or
101 -clipsrcsql options.
102 -clipsrcsql <sql_statement>
104 Select desired geometries using an SQL query instead.
105 -clipsrclayer <layername>
107 Select the named layer from the source clip datasource.
108 -clipsrcwhere <expression>
110 Restrict desired geometries based on attribute query.
111 -l <layername>
113 Indicates the layer(s) from the datasource that will be used for
114 input features. May be specified multiple times, but at least
115 one layer name or a -sql option must be specified.
116 -where <expression>
118 An optional SQL WHERE style query expression to be applied to
119 select features to process from the input layer(s).
120 -sql <select_statement>
122 An SQL statement to be evaluated against the datasource to pro‐
123 duce a virtual layer of features to be processed.
124 -oo <NAME=VALUE>
126 New in version 3.7.
127 Source dataset open option (format specific)
130 -co <NAME=VALUE>
132 Many formats have one or more optional creation options that can
133 be used to control particulars about the file created. For in‐
134 stance, the GeoTIFF driver supports creation options to control
135 compression, and whether the file should be tiled.
136 The creation options available vary by format driver, and some
138 simple formats have no creation options at all. A list of op‐
139 tions supported for a format can be listed with the --formats
140 command line option but the documentation for the format is the
141 definitive source of information on driver creation options.
142 See Raster drivers format specific documentation for legal cre‐
143 ation options for each format.
144 -q Suppress progress monitor and other non-error output.
146 <src_datasource>
148 Any OGR supported readable datasource.
149 <dst_filename>
151 The GDAL supported output file.
152
154 There are number of interpolation algorithms to choose from.
155 More details about them can also be found in GDAL Grid Tutorial
157 invdist
159 Inverse distance to a power. This is default algorithm. It has follow‐
160 ing parameters:
161 • power: Weighting power (default 2.0).
163 • smoothing: Smoothing parameter (default 0.0).
165 • radius1: The first radius (X axis if rotation angle is 0) of search
167 ellipse. Set this parameter to zero to use whole point array. De‐
168 fault is 0.0.
169 • radius2: The second radius (Y axis if rotation angle is 0) of search
171 ellipse. Set this parameter to zero to use whole point array. De‐
172 fault is 0.0.
173 • radius: Set first and second radius (mutually exclusive with radius1
175 and radius2). Default is 0.0. Added in GDAL 3.6
176 • angle: Angle of search ellipse rotation in degrees (counter clock‐
178 wise, default 0.0).
179 • max_points: Maximum number of data points to use. Do not search for
181 more points than this number. This is only used if search ellipse is
182 set (both radii are non-zero). Zero means that all found points
183 should be used. Default is 0.
184 • min_points: Minimum number of data points to use. If less amount of
186 points found the grid node considered empty and will be filled with
187 NODATA marker. This is only used if search ellipse is set (both radii
188 are non-zero). Default is 0.
189 • max_points_per_quadrant: Maximum number of data points to use per
191 quadrant. Default is 0. Added in GDAL 3.6. When specified, this ac‐
192 tually uses invdistnn implementation.
193 • min_points_per_quadrant: Minimum number of data points to use per
195 quadrant. Default is 0. Added in GDAL 3.6. When specified, this ac‐
196 tually uses invdistnn implementation.
197 • nodata: NODATA marker to fill empty points (default 0.0).
199 invdistnn
201 New in version 2.1.
202 Inverse distance to a power with nearest neighbor searching, ideal when
205 max_points is used. It has following parameters:
206 • power: Weighting power (default 2.0).
208 • smoothing: Smoothing parameter (default 0.0).
210 • radius: The radius of the search circle, which should be non-zero.
212 Default is 1.0.
213 • max_points: Maximum number of data points to use. Do not search for
215 more points than this number. Found points will be ranked from near‐
216 est to furthest distance when weighting. Default is 12.
217 • min_points: Minimum number of data points to use. If less amount of
219 points found the grid node is considered empty and will be filled
220 with NODATA marker. Default is 0.
221 • max_points_per_quadrant: Maximum number of data points to use per
223 quadrant. Default is 0. Added in GDAL 3.6. When specified, the al‐
224 gorithm will only take into account up to max_points_per_quadrant
225 points for each of the right-top, left-top, right-bottom and
226 right-top quadrant relative to the point being interpolated.
227 • min_points_per_quadrant: Minimum number of data points to use per
229 quadrant. Default is 0. Added in GDAL 3.6. If that number is not
230 reached, the point being interpolated will be set with the NODATA
231 marker. When specified, the algorithm will collect at least
232 min_points_per_quadrant points for each of the right-top, left-top,
233 right-bottom and right-top quadrant relative to the point being in‐
234 terpolated.
235 • nodata: NODATA marker to fill empty points (default 0.0).
237 When min_points_per_quadrant or max_points_per_quadrant is specified,
239 the search will start with the closest point to the point being inter‐
240 polated from the first quadrant, then the closest point to the point
241 being interpolated from the second quadrant, etc. up to the 4th quad‐
242 rant, and will continue with the next closest point in the first quad‐
243 rant, etc. until max_points and/or max_points_per_quadrant thresholds
244 are reached.
245 average
247 Moving average algorithm. It has following parameters:
248 • radius1: The first radius (X axis if rotation angle is 0) of search
250 ellipse. Set this parameter to zero to use whole point array. De‐
251 fault is 0.0.
252 • radius2: The second radius (Y axis if rotation angle is 0) of search
254 ellipse. Set this parameter to zero to use whole point array. De‐
255 fault is 0.0.
256 • radius: Set first and second radius (mutually exclusive with radius1
258 and radius2). Default is 0.0. Added in GDAL 3.6
259 • angle: Angle of search ellipse rotation in degrees (counter clock‐
261 wise, default 0.0).
262 • max_points: Maximum number of data points to use. Do not search for
264 more points than this number. Found points will be ranked from near‐
265 est to furthest distance when weighting. Default is 0. Added in GDAL
266 3.6 Only taken into account if one or both of min_points_per_quadrant
267 or max_points_per_quadrant is specified
268 • min_points: Minimum number of data points to use. If less amount of
270 points found the grid node considered empty and will be filled with
271 NODATA marker. Default is 0.
272 • max_points_per_quadrant: Maximum number of data points to use per
274 quadrant. Default is 0. Added in GDAL 3.6. When specified, the al‐
275 gorithm will only take into account up to max_points_per_quadrant
276 points for each of the right-top, left-top, right-bottom and
277 right-top quadrant relative to the point being interpolated.
278 • min_points_per_quadrant: Minimum number of data points to use per
280 quadrant. Default is 0. Added in GDAL 3.6. If that number is not
281 reached, the point being interpolated will be set with the NODATA
282 marker. When specified, the algorithm will collect at least
283 min_points_per_quadrant points for each of the right-top, left-top,
284 right-bottom and right-top quadrant relative to the point being in‐
285 terpolated.
286 • nodata: NODATA marker to fill empty points (default 0.0).
288 Note, that it is essential to set search ellipse for moving average
290 method. It is a window that will be averaged when computing grid nodes
291 values.
292 When min_points_per_quadrant or max_points_per_quadrant is specified,
294 the search will start with the closest point to the point being inter‐
295 polated from the first quadrant, then the closest point to the point
296 being interpolated from the second quadrant, etc. up to the 4th quad‐
297 rant, and will continue with the next closest point in the first quad‐
298 rant, etc. until max_points and/or max_points_per_quadrant thresholds
299 are reached.
300 nearest
302 Nearest neighbor algorithm. It has following parameters:
303 • radius1: The first radius (X axis if rotation angle is 0) of search
305 ellipse. Set this parameter to zero to use whole point array. De‐
306 fault is 0.0.
307 • radius2: The second radius (Y axis if rotation angle is 0) of search
309 ellipse. Set this parameter to zero to use whole point array. De‐
310 fault is 0.0.
311 • radius: Set first and second radius (mutually exclusive with radius1
313 and radius2). Default is 0.0. Added in GDAL 3.6
314 • angle: Angle of search ellipse rotation in degrees (counter clock‐
316 wise, default 0.0).
317 • nodata: NODATA marker to fill empty points (default 0.0).
319 linear
321 New in version 2.1.
322 Linear interpolation algorithm.
325 The Linear method performs linear interpolation by computing a Delaunay
327 triangulation of the point cloud, finding in which triangle of the tri‐
328 angulation the point is, and by doing linear interpolation from its
329 barycentric coordinates within the triangle. If the point is not in
330 any triangle, depending on the radius, the algorithm will use the value
331 of the nearest point or the nodata value.
332 It has following parameters:
334 • radius: In case the point to be interpolated does not fit into a tri‐
336 angle of the Delaunay triangulation, use that maximum distance to
337 search a nearest neighbour, or use nodata otherwise. If set to -1,
338 the search distance is infinite. If set to 0, nodata value will be
339 always used. Default is -1.
340 • nodata: NODATA marker to fill empty points (default 0.0).
342
344 Besides the interpolation functionality ref gdal_grid can be used to
345 compute some data metrics using the specified window and output grid
346 geometry. These metrics are:
347 • minimum: Minimum value found in grid node search ellipse.
349 • maximum: Maximum value found in grid node search ellipse.
351 • range: A difference between the minimum and maximum values found in
353 grid node search ellipse.
354 • count: A number of data points found in grid node search ellipse.
356 • average_distance: An average distance between the grid node (center
358 of the search ellipse) and all of the data points found in grid node
359 search ellipse.
360 • average_distance_pts: An average distance between the data points
362 found in grid node search ellipse. The distance between each pair of
363 points within ellipse is calculated and average of all distances is
364 set as a grid node value.
365 All the metrics have the same set of options:
367 • radius1: The first radius (X axis if rotation angle is 0) of search
369 ellipse. Set this parameter to zero to use whole point array. De‐
370 fault is 0.0.
371 • radius2: The second radius (Y axis if rotation angle is 0) of search
373 ellipse. Set this parameter to zero to use whole point array. De‐
374 fault is 0.0.
375 • radius: Set first and second radius (mutually exclusive with radius1
377 and radius2). Default is 0.0. Added in GDAL 3.6
378 • angle: Angle of search ellipse rotation in degrees (counter clock‐
380 wise, default 0.0).
381 • min_points: Minimum number of data points to use. If less amount of
383 points found the grid node considered empty and will be filled with
384 NODATA marker. This is only used if search ellipse is set (both radii
385 are non-zero). Default is 0.
386 • max_points_per_quadrant: Maximum number of data points to use per
388 quadrant. Default is 0. Added in GDAL 3.6. When specified, the al‐
389 gorithm will only take into account up to max_points_per_quadrant
390 points for each of the right-top, left-top, right-bottom and
391 right-top quadrant relative to the point being interpolated.
392 • min_points_per_quadrant: Minimum number of data points to use per
394 quadrant. Default is 0. Added in GDAL 3.6. If that number is not
395 reached, the point being interpolated will be set with the NODATA
396 marker. When specified, the algorithm will collect at least
397 min_points_per_quadrant points for each of the right-top, left-top,
398 right-bottom and right-top quadrant relative to the point being in‐
399 terpolated.
400 • nodata: NODATA marker to fill empty points (default 0.0).
402 When min_points_per_quadrant or max_points_per_quadrant is specified,
404 the search will start with the closest point to the point being inter‐
405 polated from the first quadrant, then the closest point to the point
406 being interpolated from the second quadrant, etc. up to the 4th quad‐
407 rant, and will continue with the next closest point in the first quad‐
408 rant, etc. until max_points and/or max_points_per_quadrant thresholds
409 are reached.
410
412 Often you have a text file with a list of comma separated XYZ values to
413 work with (so called CSV file). You can easily use that kind of data
414 source in ref gdal_grid. All you need is create a virtual dataset
415 header (VRT) for you CSV file and use it as input datasource for ref
416 gdal_grid. You can find details on VRT format at VRT -- Virtual Format
417 description page.
418 Here is a small example. Let we have a CSV file called dem.csv contain‐
420 ing
421 Easting,Northing,Elevation
423 86943.4,891957,139.13
424 87124.3,892075,135.01
425 86962.4,892321,182.04
426 87077.6,891995,135.01
427 ...
428 For above data we will create dem.vrt header with the following con‐
430 tent:
431 <OGRVRTDataSource>
433 <OGRVRTLayer name="dem">
434 <SrcDataSource>dem.csv</SrcDataSource>
435 <GeometryType>wkbPoint</GeometryType>
436 <GeometryField encoding="PointFromColumns" x="Easting" y="Northing" z="Elevation"/>
437 </OGRVRTLayer>
438 </OGRVRTDataSource>
439 This description specifies so called 2.5D geometry with three coordi‐
441 nates X, Y and Z. Z value will be used for interpolation. Now you can
442 use dem.vrt with all OGR programs (start with ref ogrinfo to test that
443 everything works fine). The datasource will contain single layer called
444 "dem" filled with point features constructed from values in CSV file.
445 Using this technique you can handle CSV files with more than three col‐
446 umns, switch columns, etc.
447 If your CSV file does not contain column headers then it can be handled
449 in the following way:
450 <GeometryField encoding="PointFromColumns" x="field_1" y="field_2" z="field_3"/>
452 The Comma Separated Value (.csv) description page contains details on
454 CSV format supported by GDAL/OGR.
455
457 This utility is also callable from C with GDALGrid().
458
460 The following would create raster TIFF file from VRT datasource de‐
461 scribed in Reading comma separated values section using the inverse
462 distance to a power method. Values to interpolate will be read from Z
463 value of geometry record.
464 gdal_grid -a invdist:power=2.0:smoothing=1.0 -txe 85000 89000 -tye 894000 890000 -outsize 400 400 -of GTiff -ot Float64 -l dem dem.vrt dem.tiff
466 The next command does the same thing as the previous one, but reads
468 values to interpolate from the attribute field specified with -zfield
469 option instead of geometry record. So in this case X and Y coordinates
470 are being taken from geometry and Z is being taken from the "Elevation"
471 field. The GDAL_NUM_THREADS is also set to parallelize the computa‐
472 tion.
473 gdal_grid -zfield "Elevation" -a invdist:power=2.0:smoothing=1.0 -txe 85000 89000 -tye 894000 890000 -outsize 400 400 -of GTiff -ot Float64 -l dem dem.vrt dem.tiff --config GDAL_NUM_THREADS ALL_CPUS
475
477 Andrey Kiselev <dron@ak4719.spb.edu>
478
480 1998-2023
481 Oct 30, 2023 GDAL_GRID(1)