1GDAL_GRID(1)                         GDAL                         GDAL_GRID(1)
2
3
4

NAME

6       gdal_grid - Creates regular grid from the scattered data.
7

SYNOPSIS

9          gdal_grid [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
10                    CInt16/CInt32/CFloat32/CFloat64}]
11                    [-of format] [-co "NAME=VALUE"]
12                    [-zfield field_name] [-z_increase increase_value] [-z_multiply multiply_value]
13                    [-a_srs srs_def] [-spat xmin ymin xmax ymax]
14                    [-clipsrc <xmin ymin xmax ymax>|WKT|datasource|spat_extent]
15                    [-clipsrcsql sql_statement] [-clipsrclayer layer]
16                    [-clipsrcwhere expression]
17                    [-l layername]* [-where expression] [-sql select_statement]
18                    [-txe xmin xmax] [-tye ymin ymax] [-tr xres yres] [-outsize xsize ysize]
19                    [-a algorithm[:parameter1=value1]*] [-q]
20                    <src_datasource> <dst_filename>
21

DESCRIPTION

23       This program creates regular grid (raster) from the scattered data read
24       from the OGR datasource. Input data will be interpolated to  fill  grid
25       nodes with values, you can choose from various interpolation methods.
26
27       It is possible to set the GDAL_NUM_THREADS configuration option to par‐
28       allelize the processing. The value to specify is the number  of  worker
29       threads, or ALL_CPUS to use all the cores/CPUs of the computer.
30
31       -ot <type>
32              Force  the  output image bands to have a specific data type sup‐
33              ported by the driver, which may be one of the  following:  Byte,
34              UInt16,  Int16, UInt32, Int32, Float32, Float64, CInt16, CInt32,
35              CFloat32 or CFloat64.
36
37       -of <format>
38              Select the output format. Starting with GDAL 2.3, if not  speci‐
39              fied,  the  format is guessed from the extension (previously was
40              GTiff). Use the short format name.
41
42       -txe <xmin> <xmax>
43              Set georeferenced X extents of output file to be created.
44
45       -tye <ymin> <ymax>
46              Set georeferenced Y extents of output file to be created.
47
48       -tr <xres> <yres>
49              Set output file  resolution  (in  target  georeferenced  units).
50              Note  that -tr just works in combination with a valid input from
51              -txe and -tye
52
53              New in version 3.2.
54
55
56       -outsize <xsize ysize>
57              Set the size of the output file in pixels and lines.  Note  that
58              -outsize cannot be used with -tr
59
60       -a_srs <srs_def>
61              Override  the  projection  for the output file.  The <i>srs_def>
62              may be any of the usual GDAL/OGR forms,  complete  WKT,  PROJ.4,
63              EPSG:n or a file containing the WKT.  No reprojection is done.
64
65       -zfield <field_name>
66              Identifies  an attribute field on the features to be used to get
67              a Z value from. This value overrides Z value read  from  feature
68              geometry  record  (naturally, if you have a Z value in geometry,
69              otherwise you have no choice and should  specify  a  field  name
70              containing Z value).
71
72       -z_increase <increase_value>
73              Addition  to  the  attribute field on the features to be used to
74              get a Z value from. The addition should be the same  unit  as  Z
75              value.  The result value will be Z value + Z increase value. The
76              default value is 0.
77
78       -z_multiply <multiply_value>
79              This is multiplication ratio for Z field. This can be  used  for
80              shift  from  e.g.  foot to meters or from elevation to deep. The
81              result value will be (Z value + Z increase value) *  Z  multiply
82              value.  The default value is 1.
83
84       -a <[algorithm[:parameter1=value1][:parameter2=value2]...]>
85              Set the interpolation algorithm or data metric name and (option‐
86              ally) its parameters. See Interpolation algorithms and Data met‐
87              rics sections for further discussion of available options.
88
89       -spat <xmin> <ymin> <xmax> <ymax>
90              Adds  a  spatial filter to select only features contained within
91              the bounding box described by (xmin, ymin) - (xmax, ymax).
92
93       -clipsrc [xmin ymin xmax ymax]|WKT|datasource|spat_extent
94              Adds a spatial filter to select only features  contained  within
95              the specified bounding box (expressed in source SRS), WKT geome‐
96              try (POLYGON or MULTIPOLYGON), from a datasource or to the  spa‐
97              tial  extent of the -spat option if you use the spat_extent key‐
98              word. When specifying a datasource, you will generally  want  to
99              use  it  in  combination  of the -clipsrclayer, -clipsrcwhere or
100              -clipsrcsql options.
101
102       -clipsrcsql <sql_statement>
103              Select desired geometries using an SQL query instead.
104
105       -clipsrclayer <layername>
106              Select the named layer from the source clip datasource.
107
108       -clipsrcwhere <expression>
109              Restrict desired geometries based on attribute query.
110
111       -l <layername>
112              Indicates the layer(s) from the datasource that will be used for
113              input  features.   May be specified multiple times, but at least
114              one layer name or a -sql option must be specified.
115
116       -where <expression>
117              An optional SQL WHERE style query expression to  be  applied  to
118              select features to process from the input layer(s).
119
120       -sql <select_statement>
121              An  SQL statement to be evaluated against the datasource to pro‐
122              duce a virtual layer of features to be processed.
123
124       -co <NAME=VALUE>
125              Many formats have one or more optional creation options that can
126              be  used  to control particulars about the file created. For in‐
127              stance, the GeoTIFF driver supports creation options to  control
128              compression, and whether the file should be tiled.
129
130              The  creation  options available vary by format driver, and some
131              simple formats have no creation options at all. A  list  of  op‐
132              tions  supported  for  a format can be listed with the --formats
133              command line option but the documentation for the format is  the
134              definitive  source  of  information  on driver creation options.
135              See Raster drivers format specific documentation for legal  cre‐
136              ation options for each format.
137
138       -q     Suppress progress monitor and other non-error output.
139
140       <src_datasource>
141              Any OGR supported readable datasource.
142
143       <dst_filename>
144              The GDAL supported output file.
145

INTERPOLATION ALGORITHMS

147       There are number of interpolation algorithms to choose from.
148
149       More details about them can also be found in GDAL Grid Tutorial
150
151   invdist
152       Inverse  distance to a power. This is default algorithm. It has follow‐
153       ing parameters:
154
155power: Weighting power (default 2.0).
156
157smoothing: Smoothing parameter (default 0.0).
158
159radius1: The first radius (X axis if rotation angle is 0)  of  search
160         ellipse.  Set  this  parameter to zero to use whole point array.  De‐
161         fault is 0.0.
162
163radius2: The second radius (Y axis if rotation angle is 0) of  search
164         ellipse.  Set  this  parameter to zero to use whole point array.  De‐
165         fault is 0.0.
166
167angle: Angle of search ellipse rotation in  degrees  (counter  clock‐
168         wise, default 0.0).
169
170max_points:  Maximum  number of data points to use. Do not search for
171         more points than this number. This is only used if search ellipse  is
172         set  (both  radii  are  non-zero).  Zero  means that all found points
173         should be used. Default is 0.
174
175min_points: Minimum number of data points to use. If less  amount  of
176         points  found  the grid node considered empty and will be filled with
177         NODATA marker. This is only used if search ellipse is set (both radii
178         are non-zero). Default is 0.
179
180nodata: NODATA marker to fill empty points (default 0.0).
181
182   invdistnn
183       New in version 2.1.
184
185
186       Inverse distance to a power with nearest neighbor searching, ideal when
187       max_points is used. It has following parameters:
188
189power: Weighting power (default 2.0).
190
191smoothing: Smoothing parameter (default 0.0).
192
193radius: The radius of the search circle, which  should  be  non-zero.
194         Default is 1.0.
195
196max_points:  Maximum  number of data points to use. Do not search for
197         more points than this number. Found points will be ranked from  near‐
198         est to furthest distance when weighting. Default is 12.
199
200min_points:  Minimum  number of data points to use. If less amount of
201         points found the grid node is considered empty  and  will  be  filled
202         with NODATA marker. Default is 0.
203
204nodata: NODATA marker to fill empty points (default 0.0).
205
206   average
207       Moving average algorithm. It has following parameters:
208
209radius1:  The  first radius (X axis if rotation angle is 0) of search
210         ellipse. Set this parameter to zero to use whole  point  array.   De‐
211         fault is 0.0.
212
213radius2:  The second radius (Y axis if rotation angle is 0) of search
214         ellipse. Set this parameter to zero to use whole  point  array.   De‐
215         fault is 0.0.
216
217angle:  Angle  of  search ellipse rotation in degrees (counter clock‐
218         wise, default 0.0).
219
220min_points: Minimum number of data points to use. If less  amount  of
221         points  found  the grid node considered empty and will be filled with
222         NODATA marker. Default is 0.
223
224nodata: NODATA marker to fill empty points (default 0.0).
225
226       Note, that it is essential to set search  ellipse  for  moving  average
227       method.  It is a window that will be averaged when computing grid nodes
228       values.
229
230   nearest
231       Nearest neighbor algorithm. It has following parameters:
232
233radius1: The first radius (X axis if rotation angle is 0)  of  search
234         ellipse.  Set  this  parameter to zero to use whole point array.  De‐
235         fault is 0.0.
236
237radius2: The second radius (Y axis if rotation angle is 0) of  search
238         ellipse.  Set  this  parameter to zero to use whole point array.  De‐
239         fault is 0.0.
240
241angle: Angle of search ellipse rotation in  degrees  (counter  clock‐
242         wise, default 0.0).
243
244nodata: NODATA marker to fill empty points (default 0.0).
245
246   linear
247       New in version 2.1.
248
249
250       Linear interpolation algorithm.
251
252       The Linear method performs linear interpolation by computing a Delaunay
253       triangulation of the point cloud, finding in which triangle of the tri‐
254       angulation  the  point  is,  and by doing linear interpolation from its
255       barycentric coordinates within the triangle.  If the point  is  not  in
256       any triangle, depending on the radius, the algorithm will use the value
257       of the nearest point or the nodata value.
258
259       It has following parameters:
260
261radius: In case the point to be interpolated does not fit into a tri‐
262         angle  of  the  Delaunay  triangulation, use that maximum distance to
263         search a nearest neighbour, or use nodata otherwise. If  set  to  -1,
264         the  search  distance is infinite.  If set to 0, nodata value will be
265         always used. Default is -1.
266
267nodata: NODATA marker to fill empty points (default 0.0).
268

DATA METRICS

270       Besides the interpolation functionality ref gdal_grid can  be  used  to
271       compute  some  data  metrics using the specified window and output grid
272       geometry. These metrics are:
273
274minimum: Minimum value found in grid node search ellipse.
275
276maximum: Maximum value found in grid node search ellipse.
277
278range: A difference between the minimum and maximum values  found  in
279         grid node search ellipse.
280
281count:  A number of data points found in grid node search ellipse.
282
283average_distance:  An  average distance between the grid node (center
284         of the search ellipse) and all of the data points found in grid  node
285         search ellipse.
286
287average_distance_pts:  An  average  distance  between the data points
288         found in grid node search ellipse. The distance between each pair  of
289         points  within  ellipse is calculated and average of all distances is
290         set as a grid node value.
291
292       All the metrics have the same set of options:
293
294radius1: The first radius (X axis if rotation angle is 0)  of  search
295         ellipse.  Set  this  parameter to zero to use whole point array.  De‐
296         fault is 0.0.
297
298radius2: The second radius (Y axis if rotation angle is 0) of  search
299         ellipse.  Set  this  parameter to zero to use whole point array.  De‐
300         fault is 0.0.
301
302angle: Angle of search ellipse rotation in  degrees  (counter  clock‐
303         wise, default 0.0).
304
305min_points:  Minimum  number of data points to use. If less amount of
306         points found the grid node considered empty and will be  filled  with
307         NODATA marker. This is only used if search ellipse is set (both radii
308         are non-zero). Default is 0.
309
310nodata: NODATA marker to fill empty points (default 0.0).
311

READING COMMA SEPARATED VALUES

313       Often you have a text file with a list of comma separated XYZ values to
314       work  with  (so  called CSV file). You can easily use that kind of data
315       source in ref gdal_grid. All you  need  is  create  a  virtual  dataset
316       header  (VRT)  for  you CSV file and use it as input datasource for ref
317       gdal_grid. You can find details on VRT format at VRT -- Virtual  Format
318       description page.
319
320       Here is a small example. Let we have a CSV file called <i>dem.csv> con‐
321       taining
322
323          Easting,Northing,Elevation
324          86943.4,891957,139.13
325          87124.3,892075,135.01
326          86962.4,892321,182.04
327          87077.6,891995,135.01
328          ...
329
330       For above data we will create <i>dem.vrt>  header  with  the  following
331       content:
332
333          <OGRVRTDataSource>
334              <OGRVRTLayer name="dem">
335                  <SrcDataSource>dem.csv</SrcDataSource>
336                  <GeometryType>wkbPoint</GeometryType>
337                  <GeometryField encoding="PointFromColumns" x="Easting" y="Northing" z="Elevation"/>
338              </OGRVRTLayer>
339          </OGRVRTDataSource>
340
341       This  description  specifies so called 2.5D geometry with three coordi‐
342       nates X, Y and Z. Z value will be used for interpolation. Now  you  can
343       use  <i>dem.vrt>  with all OGR programs (start with ref ogrinfo to test
344       that everything works fine). The datasource will contain  single  layer
345       called  <i>"dem"> filled with point features constructed from values in
346       CSV file. Using this technique you can handle CSV files with more  than
347       three columns, switch columns, etc.
348
349       If your CSV file does not contain column headers then it can be handled
350       in the following way:
351
352          <GeometryField encoding="PointFromColumns" x="field_1" y="field_2" z="field_3"/>
353
354       The Comma Separated Value (.csv) description page contains  details  on
355       CSV format supported by GDAL/OGR.
356

C API

358       This utility is also callable from C with GDALGrid().
359

EXAMPLES

361       The  following  would  create  raster TIFF file from VRT datasource de‐
362       scribed in Reading comma separated values  section  using  the  inverse
363       distance  to a power method.  Values to interpolate will be read from Z
364       value of geometry record.
365
366          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
367
368       The next command does the same thing as the  previous  one,  but  reads
369       values   to   interpolate  from  the  attribute  field  specified  with
370       <b>-zfield</b> option instead of geometry record. So in this case X and
371       Y  coordinates  are being taken from geometry and Z is being taken from
372       the <i>"Elevation"> field.  The GDAL_NUM_THREADS is also set to  paral‐
373       lelize the computation.
374
375          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
376

AUTHOR

378       Andrey Kiselev <dron@ak4719.spb.edu>
379
381       1998-2022
382
383
384
385
386                                 Sep 02, 2022                     GDAL_GRID(1)
Impressum