1.. _gdal_grid_tut:
2
3================================================================================
4GDAL Grid Tutorial
5================================================================================
6
7Introduction to Gridding
8------------------------
9
10Gridding is a process of creating a regular grid (or call it a raster image)
11from the scattered data. Typically you have a set of arbitrary scattered over
12the region of survey measurements and you would like to convert them into the
13regular grid for further processing and combining with other grids.
14
15.. only:: latex
16
17    .. image:: ../../images/grid/gridding.eps
18        :alt:   Scattered data gridding
19
20.. only:: not latex
21
22    .. image:: ../../images/grid/gridding.png
23        :alt:   Scattered data gridding
24
25This problem can be solved using data interpolation or approximation
26algorithms. But you are not limited by interpolation here. Sometimes you don't
27need to interpolate your data but rather compute some statistics or data
28metrics over the region. Statistics is valuable itself or could be used for
29better choosing the interpolation algorithm and parameters.
30
31That is what GDAL Grid API is about. It helps you to interpolate your data
32(see `Interpolation of the Scattered Data`_) or compute data metrics (see
33`Data Metrics Computation`_).
34
35There are two ways of using this interface. Programmatically it is available
36through the :cpp:func:`GDALGridCreate` C function; for end users there is a
37:ref:`gdal_grid` utility. The rest of this document discusses details on algorithms
38and their parameters implemented in GDAL Grid API.
39
40Interpolation of the Scattered Data
41-----------------------------------
42
43Inverse Distance to a Power
44+++++++++++++++++++++++++++
45
46The Inverse Distance to a Power gridding method is a weighted average
47interpolator. You should supply the input arrays with the scattered data
48values including coordinates of every data point and output grid geometry. The
49function will compute interpolated value for the given position in output
50grid.
51
52For every grid node the resulting value :math:`Z` will be calculated using
53formula:
54
55.. math::
56
57    Z=\frac{\sum_{i=1}^n{\frac{Z_i}{r_i^p}}}{\sum_{i=1}^n{\frac{1}{r_i^p}}}
58
59where:
60
61- :math:`Z_i` is a known value at point :math:`i`,
62- :math:`r_i` is a distance from the grid node to point :math:`i`,
63- :math:`p` is a weighting power,
64- :math:`n` is a number of points in `Search Ellipse`_.
65
66The smoothing parameter :math:`s` is used as an additive term in the Euclidean distance calculation:
67
68.. math::
69
70    {r_i}=\sqrt{{r_{ix}}^2 + {r_{iy}}^2 + s^2}
71
72where :math:`r_{ix}` and :math:`r_{iy}` are the horizontal and vertical
73distances between the grid node to point :math:`i` respectively.
74
75In this method the weighting factor :math:`w` is
76
77.. math::
78
79    w=\frac{1}{r^p}
80
81See :cpp:class:`GDALGridInverseDistanceToAPowerOptions` for the list of
82:cpp:func:`GDALGridCreate` parameters and :ref:`gdal_grid_invdist` for the list
83of :ref:`gdal_grid` options.
84
85Moving Average
86++++++++++++++
87
88The Moving Average is a simple data averaging algorithm. It uses a moving
89window of elliptic form to search values and averages all data points within
90the window. `Search Ellipse`_ can be rotated by
91specified angle, the center of ellipse located at the grid node. Also the
92minimum number of data points to average can be set, if there are not enough
93points in window, the grid node considered empty and will be filled with
94specified NODATA value.
95
96Mathematically it can be expressed with the formula:
97
98.. math::
99
100     Z=\frac{\sum_{i=1}^n{Z_i}}{n}
101
102where:
103
104- :math:`Z` is a resulting value at the grid node,
105- :math:`Z_i` is a known value at point :math:`i`,
106- :math:`n` is a number of points in search `Search Ellipse`_.
107
108See :cpp:class:`GDALGridMovingAverageOptions` for the list of :cpp:func:`GDALGridCreate`
109parameters and  :ref:`gdal_grid_average` for the list of :ref:`gdal_grid` options.
110
111Nearest Neighbor
112++++++++++++++++
113
114The Nearest Neighbor method doesn't perform any interpolation or smoothing, it
115just takes the value of nearest point found in grid node search ellipse and
116returns it as a result. If there are no points found, the specified NODATA
117value will be returned.
118
119See :cpp:class:`GDALGridNearestNeighborOptions` for the list of :cpp:func:`GDALGridCreate`
120parameters and :ref:`gdal_grid_nearest` for the list of :ref:`gdal_grid` options.
121
122Data Metrics Computation
123------------------------
124
125All the metrics have the same set controlling options. See the
126:cpp:class:`GDALGridDataMetricsOptions`.
127
128Minimum Data Value
129++++++++++++++++++
130
131Minimum value found in grid node `Search Ellipse`_.
132If there are no points found, the specified NODATA value will be returned.
133
134.. math::
135
136     Z=\min{(Z_1,Z_2,\ldots,Z_n)}
137
138where:
139
140- :math:`Z` is a resulting value at the grid node,
141- :math:`Z_i` is a known value at point :math:`i`,
142- :math:`n` is a number of points in `Search Ellipse`_.
143
144Maximum Data Value
145++++++++++++++++++
146
147Maximum value found in grid node `Search Ellipse`_.
148If there are no points found, the specified NODATA value will be returned.
149
150.. math::
151
152     Z=\max{(Z_1,Z_2,\ldots,Z_n)}
153
154where:
155
156- :math:`Z` is a resulting value at the grid node,
157- :math:`Z_i` is a known value at point :math:`i`,
158- :math:`n` is a number of points in `Search Ellipse`_.
159
160Data Range
161++++++++++
162
163A difference between the minimum and maximum values found in grid `Search Ellipse`_.
164If there are no points found, the
165specified NODATA value will be returned.
166
167.. math::
168
169     Z=\max{(Z_1,Z_2,\ldots,Z_n)}-\min{(Z_1,Z_2,\ldots,Z_n)}
170
171where:
172
173- :math:`Z` is a resulting value at the grid node,
174- :math:`Z_i` is a known value at point :math:`i`,
175- :math:`n` is a number of points in `Search Ellipse`_.
176
177Search Ellipse
178--------------
179
180Search window in gridding algorithms specified in the form of rotated ellipse.
181It is described by the three parameters:
182
183- :math:`radius_1` is the first radius (:math:`x` axis if rotation angle is 0),
184- :math:`radius_2` is the second radius (:math:`y` axis if rotation angle is 0),
185- :math:`angle` is a search ellipse rotation angle (rotated counter clockwise).
186
187.. only:: latex
188
189    .. image:: ../../images/grid/ellipse.eps
190        :alt:   Search ellipse
191
192.. only:: not latex
193
194    .. image:: ../../images/grid/ellipse.png
195        :alt:   Search ellipse
196
197Only points located inside the search ellipse (including its border line) will
198be used for computation.
199