GDAL_GRID(1)

📦

version 3.13.3 · 11 versions

3.13.3 · alpine 3.24, arch rolling, ubuntu stonking (latest)
3.11.3 · opensuse-leap 16.0
3.11.5 · fedora 43
3.11.4 · fedora 43
3.4.1 · ubuntu jammy
3.12.4 · fedora 44
3.12.3 · fedora 44
3.8.4 · ubuntu noble
3.6.2 · debian bookworm
3.12.2 · ubuntu resolute
3.10.3 · centos-stream 10, centos-stream 9, debian trixie, ubuntu questing

, in alpine 3.24, arch rolling, ubuntu stonking

🌸 NAME 🌸

okay bestie, welcome to GDAL_GRID(1) — the GDAL manual page for the one and only gdal_grid 💅 and what it does, in the words of the manual itself, is creates regular grid from the scattered data. that's it, that's the whole job. slay.

✨ SYNOPSIS ✨

here's the shape of the whole thing, verbatim, no cap:

gdal_grid [--help] [--help-general]
          [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
          CInt16/CInt32/CFloat32/CFloat64}]
          [-oo <NAME>=<VALUE>]...
          [-of <format>] [-co <NAME>=<VALUE>]...
          [-zfield <field_name>] [-z_increase <increase_value>] [-z_multiply <multiply_value>]
          [-a_srs <srs_def>] [-spat <xmin> <ymin> <xmax> <ymax>]
          [-clipsrc <xmin> <ymin> <xmax> <ymax>|<WKT>|<datasource>|spat_extent]
          [-clipsrcsql <sql_statement>] [-clipsrclayer <layer>]
          [-clipsrcwhere <expression>]
          [-l <layername>]... [-where <expression>] [-sql <select_statement>]
          [-txe <xmin> <xmax>] [-tye <ymin> <ymax>] [-tr <xres> <yres>] [-outsize <xsize> <ysize>]
          [-a {<algorithm>[[:<parameter1>=<value1>]...]}] [-q]
          <src_datasource> <dst_filename>

okay don't panic, we're gonna go through ALL of it together, hand in hand 🫶

🦋 DESCRIPTION 🦋

so. this program creates a regular grid (raster) from the scattered data that it reads out of the OGR datasource. input data gets interpolated to fill in the grid nodes with values, and you get to pick from all kinds of interpolation methods, which is lowkey the fun part. choose your own adventure energy ✨

and here's a lil gift: you can totally set the GDAL_NUM_THREADS configuration option to parallelize the processing. the value you pass in is either the number of worker threads, or ALL_CPUS to use every single core/CPU of the computer. main character multithreading moment 👑

TIP: equivalent in the new "gdal" command line interface: see gdal vector grid.

🎀 the options, one by one, we're doing this 🎀

--help — shows you this help message, then exits. cute, quick, done.
--help-general — gives a brief usage message for the generic GDAL commandline options, then exits. for when you wanna know about the shared stuff, not the grid stuff.
-q, --quiet — suppresses progress messages and any other non-error output. it's giving "just do the thing and don't talk to me" 🍓
-ot <type> — forces the output image bands to have a specific data type that's supported by the driver. the options are: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.

if you don't set it, a default type gets used — and that default might not be supported by the relevant driver, which causes an error 😭 so like, heads up.

-of <format> — selects the output format. if you don't specify one, the format gets guessed from the extension. use the short format name, bestie.
-txe <xmin> <xmax> — sets the georeferenced X extents of the output file that's gonna be created.
-tye <ymin> <ymax> — sets the georeferenced Y extents of the output file that's gonna be created.
-tr <xres> <yres> — sets the output file resolution (in target georeferenced units). ⚠️ note that -tr just works in combination with a valid input from -txe and -tye.

added in version 3.2.

-outsize <xsize> <ysize> — sets the size of the output file in pixels and lines. note that -outsize cannot be used with -tr. pick a lane 💅
-a_srs <srs_def> — overrides the projection for the output file. <srs_def> can be any of the usual GDAL/OGR forms: complete WKT, PROJ.4, EPSG:n, or a file containing the WKT. no reprojection is done — this is a rename-not-a-glow-up situation.
-zfield <field_name> — identifies an attribute field on the features that'll be used to grab a Z value from. this value overrides the Z value read from the feature geometry record (which, naturally, only matters if you actually have a Z value in the geometry — otherwise you have no choice and should specify a field name containing a Z value).
-z_increase <increase_value> — an addition applied to the attribute field on the features, used to get a Z value from. the addition should be in the same unit as the Z value. the result value will be Z value + Z increase value. default is 0.
-z_multiply <multiply_value> — this is the multiplication ratio for the Z field. use it for a shift from, like, feet to meters, or from elevation to depth. the result value will be (Z value + Z increase value) * Z multiply value. default is 1.
-a {<algorithm>[[:<parameter1>=<value1>]...]} — sets the interpolation algorithm or data metric name, plus (optionally) its parameters. peek the Interpolation algorithms and Data metrics sections for the full discussion of what's available.
-spat <xmin> <ymin> <xmax> <ymax> — adds a spatial filter so only features contained inside the bounding box described by (xmin, ymin) - (xmax, ymax) get selected.
-clipsrc [<xmin> <ymin> <xmax> <ymax>]|<WKT>|<datasource>|spat_extent — adds a spatial filter to select only features contained within: the bounding box you specify (expressed in source SRS), a WKT geometry (POLYGON or MULTIPOLYGON), a datasource, or the spatial extent of the -spat option if you use the spat_extent keyword. when you're specifying a datasource, you'll generally want to pair it with the -clipsrclayer, -clipsrcwhere or -clipsrcsql options. team effort 🫶
-clipsrcsql <sql_statement> — selects the desired geometries using an SQL query instead.
-clipsrclayer <layername> — selects the named layer from the source clip datasource.
-clipsrcwhere <expression> — restricts the desired geometries based on an attribute query.
-l <layername> — indicates the layer(s) from the datasource that'll be used for input features. may be specified multiple times, but at least one layer name or a -sql option must be specified. you can't do neither, bestie.
-where <expression> — an optional SQL WHERE style query expression, applied to select which features to process out of the input layer(s).
-sql <select_statement> — an SQL statement to be evaluated against the datasource, producing a virtual layer of features to be processed.
-oo <NAME>=<VALUE> — source dataset open option (format specific).

added in version 3.7.

-co <NAME>=<VALUE> — many formats have one or more optional creation options that control the particulars of the file being created. for instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled.

the creation options available vary by format driver, and some simple formats have no creation options at all. you can list the options a format supports with the --format command line option, but the documentation for the format is the ✨definitive✨ source of info on driver creation options. see Raster drivers format specific documentation for the legal creation options of each format.

<src_datasource> — any OGR supported readable datasource. feed me data 🌈
<dst_filename> — the GDAL supported output file.

and there's so much more where that came from, we are absolutely not done yet — keep reading, bestie 💜

✨ INTERPOLATION ALGORITHMS ✨

okay bestie, so there's a whole menu of interpolation algorithms for you to pick from and honestly? iconic behavior. 🎀

and if you want even more tea on them, there's also more details to be found in the GDAL Grid Tutorial. iykyk 💅

🌸 invdist 🌸

Inverse distance to a power. this one is the default btw, so if you don't say anything, this is what you get. main character energy for real. 👑

it's got these parameters:

power — the weighting power. default is 2.0.
smoothing — the smoothing parameter. default is 0.0.
radius1 — the first radius (that's the X axis if the rotation angle is 0) of the search ellipse. set it to zero and it uses the whole point array. default is 0.0.
radius2 — the second radius (Y axis when the rotation angle is 0) of the search ellipse. set it to zero and it uses the whole point array. default is 0.0.
radius — sets both the first and second radius (mutually exclusive with radius1 and radius2, so pick a lane bestie 💀). default is 0.0. Added in GDAL 3.6.
angle — angle of search ellipse rotation in degrees, counter clockwise. default is 0.0.
max_points — maximum number of data points to use. it does not search for more points than this number. this only kicks in if the search ellipse is set (so both radii are non-zero). zero means all the found points should be used. default is 0.
min_points — minimum number of data points to use. if fewer points than this get found, the grid node is considered empty and gets filled with the NODATA marker. this only kicks in if the search ellipse is set (both radii non-zero). default is 0.
max_points_per_quadrant — maximum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. when you specify it, this actually uses the invdistnn implementation. lowkey a plot twist.
min_points_per_quadrant — minimum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. when you specify it, this actually uses the invdistnn implementation too.
nodata — the NODATA marker used to fill empty points. default is 0.0.

🦋 invdistnn 🦋

Inverse distance to a power with nearest neighbor searching. this one is ideal when max_points is used. a serve. 💖

it's got these parameters:

power — the weighting power. default is 2.0.
smoothing — the smoothing parameter. default is 0.0.
radius — the radius of the search circle, which should be non-zero. default is 1.0.
max_points — maximum number of data points to use. it doesn't search for more points than this number. found points get ranked from nearest to furthest distance when weighting. default is 12.
min_points — minimum number of data points to use. if fewer points than this get found, the grid node is considered empty and gets filled with the NODATA marker. default is 0.
max_points_per_quadrant — maximum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. when you specify it, the algorithm will only take into account up to max_points_per_quadrant points for each of the right-top, left-top, right-bottom and right-top quadrant relative to the point being interpolated.
min_points_per_quadrant — minimum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. if that number isn't reached, the point being interpolated gets set with the NODATA marker. when you specify it, the algorithm will collect at least min_points_per_quadrant points for each of the right-top, left-top, right-bottom and right-top quadrant relative to the point being interpolated.
nodata — the NODATA marker used to fill empty points. default is 0.0.

so when min_points_per_quadrant or max_points_per_quadrant is specified, the search starts with the closest point to the point being interpolated from the first quadrant, then the closest point to the point being interpolated from the second quadrant, etc., all the way up to the 4th quadrant, and then it keeps going with the next closest point in the first quadrant, etc. until the max_points and/or max_points_per_quadrant thresholds are reached. it's giving very organized. 🌀

🎀 average 🎀

Moving average algorithm. it's got these parameters:

radius1 — the first radius (X axis if the rotation angle is 0) of the search ellipse. set it to zero to use the whole point array. default is 0.0.
radius2 — the second radius (Y axis if the rotation angle is 0) of the search ellipse. set it to zero to use the whole point array. default is 0.0.
radius — sets both the first and second radius (mutually exclusive with radius1 and radius2). default is 0.0. Added in GDAL 3.6.
angle — angle of search ellipse rotation in degrees, counter clockwise. default is 0.0.
max_points — maximum number of data points to use. it doesn't search for more points than this number. found points get ranked from nearest to furthest distance when weighting. default is 0. Added in GDAL 3.6. this is only taken into account if one or both of min_points_per_quadrant or max_points_per_quadrant is specified.
min_points — minimum number of data points to use. if fewer points than this get found, the grid node is considered empty and gets filled with the NODATA marker. default is 0.
max_points_per_quadrant — maximum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. when you specify it, the algorithm will only take into account up to max_points_per_quadrant points for each of the right-top, left-top, right-bottom and right-top quadrant relative to the point being interpolated.
min_points_per_quadrant — minimum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. if that number isn't reached, the point being interpolated gets set with the NODATA marker. when you specify it, the algorithm will collect at least min_points_per_quadrant points for each of the right-top, left-top, right-bottom and right-top quadrant relative to the point being interpolated.
nodata — the NODATA marker used to fill empty points. default is 0.0.

🚨 bestie listen up: it is essential to set the search ellipse for the moving average method. it's literally the window that gets averaged when computing the grid node values. no window, no vibe.

and when min_points_per_quadrant or max_points_per_quadrant is specified, the search starts with the closest point to the point being interpolated from the first quadrant, then the closest point to the point being interpolated from the second quadrant, etc., up to the 4th quadrant, and keeps going with the next closest point in the first quadrant, etc. until the max_points and/or max_points_per_quadrant thresholds are reached. ✨

🧚 nearest 🧚

Nearest neighbor algorithm. it's got these parameters:

radius1 — the first radius (X axis if the rotation angle is 0) of the search ellipse. set it to zero to use the whole point array. default is 0.0.
radius2 — the second radius (Y axis if the rotation angle is 0) of the search ellipse. set it to zero to use the whole point array. default is 0.0.
radius — sets both the first and second radius (mutually exclusive with radius1 and radius2). default is 0.0. Added in GDAL 3.6.
angle — angle of search ellipse rotation in degrees, counter clockwise. default is 0.0.
nodata — the NODATA marker used to fill empty points. default is 0.0.

⭐ linear ⭐

Linear interpolation algorithm. periodt.

the Linear method does its linear interpolation by computing a Delaunay triangulation of the point cloud, finding in which triangle of the triangulation the point is, and then doing linear interpolation from its barycentric coordinates within the triangle. and if the point is not in any triangle, then depending on the radius, the algorithm will either use the value of the nearest point or the nodata value. 💫

it's got these parameters:

radius — in case the point to be interpolated doesn't fit into a triangle of the Delaunay triangulation, use that maximum distance to search a nearest neighbour, or use nodata otherwise. if set to -1, the search distance is infinite. if set to 0, the nodata value will always be used. default is -1.
nodata — the NODATA marker used to fill empty points. default is 0.0.

💜 DATA METRICS 💜

besides all the interpolation functionality, gdal_grid can also be used to compute some data metrics using the specified window and output grid geometry. and these metrics are:

minimum — minimum value found in the grid node search ellipse.
maximum — maximum value found in the grid node search ellipse.
range — the difference between the minimum and maximum values found in the grid node search ellipse.
count — a number of data points found in the grid node search ellipse.
average_distance — an average distance between the grid node (which is the center of the search ellipse) and all of the data points found in the grid node search ellipse.
average_distance_pts — an average distance between the data points found in the grid node search ellipse. the distance between each pair of points within the ellipse is calculated, and the average of all those distances becomes the grid node value.

and all of these metrics share the same set of options, no cap:

radius1 — the first radius (X axis if the rotation angle is 0) of the search ellipse. set it to zero to use the whole point array. default is 0.0.
radius2 — the second radius (Y axis if the rotation angle is 0) of the search ellipse. set it to zero to use the whole point array. default is 0.0.
radius — sets both the first and second radius (mutually exclusive with radius1 and radius2). default is 0.0. Added in GDAL 3.6.
angle — angle of search ellipse rotation in degrees, counter clockwise. default is 0.0.
min_points — minimum number of data points to use. if fewer points than this get found, the grid node is considered empty and gets filled with the NODATA marker. this is only used if the search ellipse is set (both radii non-zero). default is 0.
max_points_per_quadrant — maximum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. when you specify it, the algorithm will only take into account up to max_points_per_quadrant points for each of the right-top, left-top, right-bottom and right-top quadrant relative to the point being interpolated.
min_points_per_quadrant — minimum number of data points to use per quadrant. default is 0. Added in GDAL 3.6. if that number isn't reached, the point being interpolated gets set with the NODATA marker. when you specify it, the algorithm will collect at least min_points_per_quadrant points for each of the right-top, left-top, right-bottom and right-top quadrant relative to the point being interpolated.
nodata — the NODATA marker used to fill empty points. default is 0.0.

and when min_points_per_quadrant or max_points_per_quadrant is specified, the search starts with the closest point to the point being interpolated from the first quadrant, then the closest point to the point being interpolated from the second quadrant, etc., up to the 4th quadrant, and continues with the next closest point in the first quadrant, etc. until the max_points and/or max_points_per_quadrant thresholds are reached. 🫶

🍓 READING COMMA SEPARATED VALUES 🍓

Okay bestie, real talk: SO often you've got a lil text file just sitting there with a list of comma separated XYZ values, right? That's your classic CSV file. And the good news is you can absolutely feed that kind of datasource straight into gdal_grid — it's giving effortless. ✨

All you gotta do is make a virtual dataset header (a VRT) for your CSV file and hand it over as the input datasource for gdal_grid. If you want the full tea on the VRT format, it's all on the VRT -- OGR Virtual Format description page.

Here's a tiny example, because examples are the moment. Say we have a CSV file called dem.csv containing:

Easting,Northing,Elevation
86943.4,891957,139.13
87124.3,892075,135.01
86962.4,892321,182.04
87077.6,891995,135.01
...

For that data, we're gonna create a dem.vrt header that looks like this:

<OGRVRTDataSource>
    <OGRVRTLayer name="dem">
        <SrcDataSource>dem.csv</SrcDataSource>
        <GeometryType>wkbPoint</GeometryType>
        <GeometryField encoding="PointFromColumns" x="Easting" y="Northing" z="Elevation"/>
    </OGRVRTLayer>
</OGRVRTDataSource>

This description specifies a so-called 2.5D geometry with three coordinates: X, Y and Z. And the Z value is the one that'll be used for interpolation, periodt. 💅

Now you can use dem.vrt with all OGR programs — start with ogrinfo to vibe check that everything works fine. The datasource will contain a single layer called "dem", filled with point features constructed from the values in the CSV file. And using this technique you can handle CSV files with more than three columns, switch columns around, etc. Versatile icon behavior honestly. 👑

OK now the final step:

gdal_grid dem.vrt demv.tif

Or, if we do not wish to use a VRT file:

gdal_grid -l dem -oo X_POSSIBLE_NAMES=Easting \
-oo Y_POSSIBLE_NAMES=Northing -zfield Elevation dem.csv dem.tif

And if your CSV file doesn't contain column headers, no stress, it can be handled in the VRT file like this:

<GeometryField encoding="PointFromColumns" x="field_1" y="field_2" z="field_3"/>

The Comma Separated Value (.csv) description page contains all the details on the CSV format supported by GDAL/OGR. 🦋

🌈 CREATING MULTIBAND FILES 🌈

Ugh, okay, the tea here is: creating multiband files is not directly possible with gdal_grid. Not me being the bearer of bad news. 😭 But bestie, there's a workaround and it slays:

One might use gdal_grid multiple times to create one band per file, and then use gdalbuildvrt -separate and then gdal_translate:

gdal_grid ... 1.tif; gdal_grid ... 2.tif; gdal_grid ... 3.tif
gdalbuildvrt -separate 123.vrt 1.tif 2.tif 3.tif
gdal_translate 123.vrt 123.tif

Or just use gdal_merge to combine the one-band files into a single one:

gdal_grid ... a.tif; gdal_grid ... b.tif; gdal_grid ... c.tif
gdal_merge -separate a.tif b.tif c.tif -o d.tif

Two paths, both iconic. Pick your fighter. 🫶

⭐ RETURN STATUS CODE ⭐

The program returns status code 0 in case of success, and non-zero in case of error. And yes, small print moment: non-blocking errors emitted as warnings are considered as a successful execution. So like, a lil grumble is not a fail, iykyk. 💖

💜 C API 💜

This utility is also callable from C with GDALGrid(). Look at her being multilingual. ✨

🎀 EXAMPLES 🎀

💅 Example 1: Create a raster from a VRT datasource using inverse distance to a power

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

This example creates a raster TIFF file from the VRT datasource described in the Reading comma separated values section, using the inverse distance to a power method. Values to interpolate will be read from the Z value of the geometry record.

🌸 Example 2: Read values to interpolate from an attribute field

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

This command does the same thing as the previous one, but it reads the values to interpolate from the attribute field specified with the -zfield option instead of the geometry record. So in this case, X and Y coordinates are being taken from geometry, and Z is being taken from the "Elevation" field. The GDAL_NUM_THREADS is also set to parallelize the computation, because we love a sped-up queen. 🔥

👑 AUTHOR 👑

Andrey Kiselev <dron@ak4719.spb.edu>

🦋 COPYRIGHT 🦋

1998-2026

okay that's the whole page bestie, we ate and left absolutely no crumbs 💖✨ this treasure was brought to you by the GDAL_GRID(1) manual, dated Aug 18, 2026, and the copyright window runs all the way back to 1998-2026 — historic behavior fr fr 🎀

📦 where this page comes from

alpine 3.24: gdal-doc 3.13.3-r0 · MIT
arch rolling: gdal 3.13.3-6 · MIT
ubuntu stonking: gdal-bin 3.13.3+dfsg-1ubuntu4 · MIT
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-02: a language model's rewrite of the original, under its terms