GDALWARP(1)

📦
version 3.13.3 · 11 versions
, in alpine 3.24, arch rolling, ubuntu stonking

GDALWARP(1)

okay bestie, this is the GDAL manual page for gdalwarp 💖 it is long, so buckle up, we're doing this in parts 🎀

🌸 NAME 🌸

gdalwarp — Image reprojection and warping utility. that's the whole vibe, no cap 💅

✨ SYNOPSIS ✨

Usage: gdalwarp [--help] [--long-usage] [--help-general]
                [--quiet] [-overwrite] [-of <output_format>]
                [-co <NAME>=<VALUE>]... [-s_srs <srs_def>] [-t_srs <srs_def>]
                [[-srcalpha]|[-nosrcalpha]]
                [-dstalpha] [-tr <xres> <yres>|square] [-ts <width> <height>]
                [-te <xmin> <ymin> <xmax> <ymax>] [-te_srs <srs_def>]
                [-r near|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum]
                [-ot Byte|Int8|[U]Int{16|32|64}|CInt{16|32}|[C]Float{32|64}]
                <src_dataset_name>... <dst_dataset_name>

Advanced options:
                [-wo <NAME>=<VALUE>]... [-multi] [-s_coord_epoch <epoch>]
                [-t_coord_epoch <epoch>] [-ct <string>]
                [[-tps]|[-rpc]|[-geoloc]]
                [-order <1|2|3>] [-refine_gcps <tolerance> [<minimum_gcps>]]
                [-to <NAME>=<VALUE>]... [-et <err_threshold>]
                [-wm <memory_in_mb>] [-srcnodata "<value>[ <value>]..."]
                [-dstnodata "<value>[ <value>]..."] [-tap]
                [-wt Byte|Int8|[U]Int{16|32|64}|CInt{16|32}|[C]Float{32|64}]
                [-cutline <datasource>|<WKT>] [-cutline_srs <srs_def>]
                [-cwhere <expression>]
                [[-cl <layername>]|[-csql <query>]]
                [-cblend <distance>] [-crop_to_cutline] [-nomd]
                [-cvmd <meta_conflict_value>] [-setci] [-oo <NAME>=<VALUE>]...
                [-doo <NAME>=<VALUE>]... [-ovr <level>|AUTO|AUTO-<n>|NONE]
                [[-vshift]|[-novshiftgrid]]
                [-if <format>]... [-srcband <band>]... [-dstband <band>]...

💫 DESCRIPTION 💫

so gdalwarp is your image mosaicing, reprojection and warping utility 🦋 The program can reproject to any supported projection, and can also apply GCPs stored with the image if the image is "raw" with control information. it's giving glow-up for your rasters, fr fr ✨

💡 TIP: there's an equivalent in the new gdal command line interface, bestie: - gdal raster reproject for reprojection - gdal raster update to update the content of a raster with another one

👑 OPTIONS 👑

  • --help — show this help message and exit 🫶
  • --help-general — gives a brief usage message for the generic GDAL commandline options and exits. very "hi bestie, here's the generic stuff" energy 💅
  • -q, --quiet — suppress progress messages and other non-error output. silence is golden, no commentary 🌸
  • -b <n> — the page gives this one no description at all, it just sits there 💀 moving on
  • -srcband <n> — Added in version 3.7.

Specify an input band number to warp (between 1 and the number of bands of the source dataset).

This option is used to warp a subset of the input bands. All input bands are used when it is not specified.

This option may be repeated multiple times to select several input bands. The order in which bands are specified will be the order in which they appear in the output dataset (unless -dstband is specified).

The alpha band should not be specified in the list, as it will be automatically retrieved (unless -nosrcalpha is specified).

The following invocation will warp an input datasets with bands ordered as Blue, Green, Red, NearInfraRed in an output dataset with bands ordered as Red, Green, Blue.

gdalwarp in_bgrn.tif out_rgb.tif -b 3 -b 2 -b 1 -overwrite
  • -dstband <n> — Added in version 3.7.

Specify the output band number in which to warp. In practice, this option is only useful when updating an existing dataset, e.g to warp one band at at time.

gdal_create -if in_red.tif -bands 3 out_rgb.tif
gdalwarp in_red.tif out_rgb.tif -srcband 1 -dstband 1
gdalwarp in_green.tif out_rgb.tif -srcband 1 -dstband 2
gdalwarp in_blue.tif out_rgb.tif -srcband 1 -dstband 3

If -srcband is specified, there must be as many occurrences of -dstband as there are of -srcband. periodt 📌

The output alpha band should not be specified, as it will be automatically created if the input dataset has an alpha band, or if -dstalpha is specified.

If -dstband is not specified, then -dstband 1 -dstband 2 ... -dstband N is assumed where N is the number of input bands (specified explicitly either with -srcband or implicitly)

  • -s_srs <srs def> — set source spatial reference. If not specified the SRS found in the input dataset will be used.

The coordinate reference systems that can be passed are anything supported by the OGRSpatialReference.SetFromUserInput() call, which includes EPSG Projected, Geographic or Compound CRS (i.e. EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 declarations, or the name of a .prj file containing a WKT CRS definition.

If the SRS has an explicit vertical datum that points to a geoid grid, and the input dataset is a single band dataset, a vertical correction will be applied to the values of the dataset. 🌈

  • -s_coord_epoch <epoch> — Added in version 3.4.

Assign a coordinate epoch, linked with the source SRS. Useful when the source SRS is a dynamic CRS. Only taken into account if -s_srs is used.

⚠️ Before PROJ 9.4, -s_coord_epoch and -t_coord_epoch were mutually exclusive, due to lack of support for transformations between two dynamic CRS. (they literally could not be in the same room 💀)
  • -t_srs <srs_def> — set target spatial reference. that's the glow-up destination 💖

A source SRS must be available for reprojection to occur. The source SRS will be by default the one found in the input dataset when it is available, or as overridden by the user with -s_srs

The coordinate reference systems that can be passed are anything supported by the OGRSpatialReference.SetFromUserInput() call, which includes EPSG Projected, Geographic or Compound CRS (i.e. EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 declarations, or the name of a .prj file containing a WKT CRS definition.

If the SRS has an explicit vertical datum that points to a geoid grid, and the input dataset is a single band dataset, a vertical correction will be applied to the values of the dataset.

  • -t_coord_epoch <epoch> — Added in version 3.4.

Assign a coordinate epoch, linked with the target SRS. Useful when the target SRS is a dynamic CRS. Only taken into account if -t_srs is used.

⚠️ Before PROJ 9.4, -s_coord_epoch and -t_coord_epoch were mutually exclusive, due to lack of support for transformations between two dynamic CRS.
  • -ct <string> — a PROJ string (single step operation or multiple step string starting with +proj=pipeline), a WKT2 string describing a CoordinateOperation, or a urn:ogc:def:coordinateOperation:EPSG::XXXX URN overriding the default transformation from the source to the target CRS.

It must take into account the axis order of the source and target CRS, that is typically include a step proj=axisswap order=2,1 at the beginning of the pipeline if the source CRS has northing/easting axis order, and/or at the end of the pipeline if the target CRS has northing/easting axis order. lowkey the axis order is always the plot twist 🙈

When creating a new output file, using -t_srs is still necessary to have the target CRS written in the metadata of the output file, but the parameters of the CoordinateOperation will override those of the standard transformation.

Added in version 3.0.

  • -to <NAME>=<VALUE> — set a transformer option suitable to pass to GDALCreateGenImgProjTransformer2(). See GDALCreateRPCTransformerV2() for RPC specific options. 🧚
  • -vshift — force the use of vertical shift. This option is generally not necessary, except when using an explicit coordinate transformation (-ct), and not specifying an explicit source and target SRS.

Added in version 3.4.

  • -novshift — disable the use of vertical shift when one of the source or target SRS has an explicit vertical datum, and the input dataset is a single band dataset.
📝 NOTE: this option was named -novshiftgrid until GDAL 3.3.

Added in version 3.4.

  • -order <n> — order of polynomial used for warping (1 to 3). The default is to select a polynomial order based on the number of GCPs. it's giving "trust the algorithm" ✨
  • -tps — force use of Thin Plate Spline transformer based on available GCPs.
🚨 WARNING: using a Thin Plate Spline transformer with more than a few thousand GCPs requires significant RAM usage (at least numGCPs * numGCPs * 8 bytes) and processing time. bestie your RAM will be screaming 😭
  • -rpc — force use of RPCs.
  • -geoloc — force use of Geolocation Arrays.
  • -et <err_threshold> — error threshold for transformation approximation, expressed as a number of source pixels. Defaults to 0.125 pixels unless the RPC_DEM transformer option is specified, in which case an exact transformer, i.e. err_threshold=0, will be used.
  • -refine_gcps <tolerance> [<minimum_gcps>] — refines the GCPs by automatically eliminating outliers. Outliers will be eliminated until minimum_gcps are left or when no outliers can be detected. The tolerance is passed to adjust when a GCP will be eliminated. Note that GCP refinement only works with polynomial interpolation. The tolerance is in pixel units if no projection is available, otherwise it is in SRS units. If minimum_gcps is not provided, the minimum GCPs according to the polynomial model is used. bye bye outliers 👋💅
  • -te <xmin> <ymin> <xmax> <ymax> — set georeferenced extents of output file to be created (in target SRS by default, or in the SRS specified with -te_srs). this is the crop-the-vibe box 📦
  • -te_srs <srs_def> — specifies the SRS in which to interpret the coordinates given with -te. The <srs_def> may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or a file containing the WKT. This must not be confused with -t_srs which is the target SRS of the output dataset. -te_srs is a convenience e.g. when knowing the output coordinates in a geodetic long/lat SRS, but still wanting a result in a projected coordinate system. they are different bestie, do not mix them up 🙈
  • -tr <xres> <yres> | -tr square — set output file resolution (in target georeferenced units).

If you don't specify anything (and nothing can be deduced from -te and -ts), then in the general case gdalwarp will hit you with an output raster where xres=yres. 💖

Starting with GDAL 3.7, if neither -tr nor -ts are specified, and no reprojection is involved (which includes taking geolocation arrays or RPC into account), then the resolution of the source file(s) gets preserved (in previous versions, an output raster with xres=yres was always generated, no exception). But bestie, you can still ask for square pixels — just pass square as the value for -tr. ✨

  • -tap — (target aligned pixels) aligns the coordinates of the extent of the output file to the values of the -tr, so that the aligned extent includes the minimum extent. Heads up: starting with GDAL 3.8, edge lines/columns that are detected as blank before actual warping will be removed. 🧹 "Alignment" here means xmin / resx, ymin / resy, xmax / resx and ymax / resy are all integer values. It does not necessarily mean the output grid lines up with the input grid, so don't get it twisted. 🦋
  • -ts <width> <height> — set the output file size in pixels and lines. If width or height is set to 0, the other dimension will be guessed from the computed resolution. And ngl, -ts cannot be used with -tr — they're exes, pick one. 😭
  • -ovr <level>|AUTO|AUTO-<n>|NONE — lets you specify which overview level of the source files must be used. The default, AUTO, picks the overview level whose resolution is the closest to the target resolution. Drop in an integer value (0-based, so 0 = 1st overview level) to select a specific level. Say AUTO-n, where n is an integer greater than or equal to 1, to select an overview level below the AUTO one. Or say NONE to force the base resolution to be used (which is lowkey a lifesaver if the overviews were generated with a low quality resampling method, and the warping is being done with a higher quality resampling method). 👑
  • -wo <NAME>=<VALUE> — set a warp option. The GDALWarpOptions::papszWarpOptions docs show all the options. You can stack multiple -wo options, go off. 🔥
  • -ot <type> — force the output image bands to have a specific data type supported by the driver, which may be one of the following: Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64, Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64. That's the whole roster, periodt. 💅
  • -wt <type> — working pixel data type. Basically, the data type of pixels in the source image and destination image buffers.
  • -r <resampling_method> — the resampling method to use. The available methods are:
    • near: nearest neighbour resampling (default for non-COG drivers, fastest algorithm, worst interpolation quality).
    • bilinear: bilinear resampling.
    • cubic: cubic resampling (default for COG driver).
    • cubicspline: cubic spline resampling.
    • lanczos: Lanczos windowed sinc resampling.
    • average: average resampling, computes the weighted average of all non-NODATA contributing pixels.
    • rms root mean square / quadratic mean of all non-NODATA contributing pixels (GDAL >= 3.3)
    • mode: mode resampling, selects the value which appears most often of all the sampled points. In the case of ties, the first value identified as the mode will be selected.
    • max: maximum resampling, selects the maximum value from all non-NODATA contributing pixels.
    • min: minimum resampling, selects the minimum value from all non-NODATA contributing pixels.
    • med: median resampling, selects the median value of all non-NODATA contributing pixels.
    • q1: first quartile resampling, selects the first quartile value of all non-NODATA contributing pixels.
    • q3: third quartile resampling, selects the third quartile value of all non-NODATA contributing pixels.
    • sum: compute the weighted sum of all non-NODATA contributing pixels (since GDAL 3.1)
NOTE: when downsampling is performed (aka you used -tr or -ts), existing overviews on the source image — internal/implicit or external, either way — will be used by default, picking the closest overview to the desired output resolution. 😭 And here's the tea: the resampling method used to create those overviews is generally not the one you specify through the -r option. Some formats, like JPEG2000, can contain significant outliers because of how wavelet compression works. So in those situations it might be useful to use the -ovr NONE option to stop existing overviews from being used. 🙈
  • -srcnodata "<value>[ <value>]..." — set nodata masking values for input bands (and yes, different values can be supplied for each band). If you supply more than one value, all of them should be quoted to keep them together as a single operating system argument. Masked values will not be used in interpolation (the details live in Nodata / source validity mask handling). 🌸

Use a value of None to ignore intrinsic nodata settings on the source dataset.

When this option is set to a non-None value, it causes the UNIFIED_SRC_NODATA warping option (see GDALWarpOptions::papszWarpOptions) to be set to YES, if it isn't explicitly set.

If -srcnodata is not explicitly set, but the source dataset has nodata values, they will be taken into account, with UNIFIED_SRC_NODATA at PARTIAL by default.

  • -dstnodata "<value>[ <value>]..." — set nodata values for output bands (again, different values can be supplied for each band). If more than one value is supplied, all values should be quoted to keep them together as a single operating system argument. New files will be initialized to this value, and if possible the nodata value will be recorded in the output file. Use a value of None to make sure nodata is not defined. If you don't use this argument at all, then nodata values will be copied from the source dataset. 🫶
  • -srcalpha — force the last band of a source image to be considered as a source alpha band.
  • -nosrcalpha — stop the alpha band of a source image from being considered as such (it'll be warped as a regular band instead).
  • -dstalpha — create an output alpha band to identify nodata (unset/transparent) pixels. ✨
  • -wm <memory_in_mb> — set the amount of memory that the warp API is allowed to use for caching. Defaults to 64 MB. Since GDAL 3.10, the value can be specified either as a fixed amount of memory (e.g., -wm 200MB, -wm 1G) or as a percentage of usable RAM (-wm 10%). In earlier versions, or if a unit isn't specified, the value is interpreted as being in megabytes if the value is less than 10000. For values >=10000, it is interpreted as bytes. 🤓

The warper will total up the memory required to hold the input and output image arrays and any auxiliary masking arrays, and if they're larger than the "warp memory" allowed, it will subdivide the chunk into smaller chunks and try again.

If the -wm value is very small, there's some extra overhead in doing many small chunks, so setting it larger is better — but it's a matter of diminishing returns, bestie.

  • -multi — use the multithreaded warping implementation. Two threads will be used to process chunks of image and perform input/output operation simultaneously. Note that the computation is not multithreaded itself. To do that, you can use the -wo NUM_THREADS=val/ALL_CPUS option, which can be combined with -multi. 💅
  • -if <format> — format/driver name to be attempted to open the input file(s). It's generally not necessary to specify it, but it can be used to skip automatic driver detection when that fails to select the appropriate driver. This option can be repeated several times to specify several candidate drivers. Note that it does not force those drivers to open the dataset — in particular, some drivers have requirements on file extensions. 🙈

Added in version 3.2.

  • -of <format> — select the output format. If not specified, the format is guessed from the extension. Use the short format name.
  • -co <NAME>=<VALUE> — many formats have one or more optional creation options that can be used to control particulars about the file 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. A list of options supported for a format can be listed with the --format command line option, but the documentation for the format is the definitive source of information on driver creation options. See Raster drivers format specific documentation for legal creation options for each format.

  • -cutline <datasource>|<WKT> — enable use of a blend cutline from the name of a vector dataset. Starting with GDAL 3.9, a WKT geometry string starting with POLYGON or MULTIPOLYGON can also be specified. 🔥
  • -cutline_srs <srs_def> — sets or overrides the SRS of the cutline. Added in version 3.9.
  • -cl <layername> — select the named layer from the cutline datasource.
  • -cwhere <expression> — restrict desired cutline features based on attribute query.
  • -csql <query> — select cutline features using an SQL query instead of from a layer with -cl.
  • -cblend <distance> — set a blend distance to use to blend over cutlines (in pixels).
  • -crop_to_cutline — crop the extent of the target dataset to the extent of the cutline. ✂️
  • -overwrite — overwrite the target dataset if it already exists. And "overwriting" here must be understood as deleting and recreating the file from scratch. Note that if this option is not specified and the output file already exists, it will be updated in place instead. 😭
  • -nomd — do not copy metadata. Without this option, dataset and band metadata (as well as some band information) will be copied from the first source dataset. Items that differ between source datasets will be set to * (see the -cvmd option). 💀
  • -cvmd <meta_conflict_value> — value to set metadata items that conflict between source datasets (the default is "*"). Use "" to remove conflicting items.
  • -setci — sets the color interpretation of the bands of the target dataset, taking it straight from the source dataset. matching fits, no cap 💅
  • -oo <NAME>=<VALUE> — a dataset open option (format specific), for the source side.
  • -doo <NAME>=<VALUE> — an output dataset open option (format specific), for the destination side.
  • <src_dataset_name> — the source file name(s).
  • <dst_dataset_name> — the destination file name.

🦋 OVERVIEW 🦋

okay so here's the whole vibe of what gdalwarp actually does: it transforms images between different coordinate reference systems and spatial resolutions. that's the mission, that's the whole personality.

First thing's first — she has to figure out the extent and resolution of the output, unless you already told her, which you do with -te and -tr. If you didn't? She figures it out by transforming a sample of points from the source CRS to the destination CRS. the full tea on that procedure lives in the documentation for GDALSuggestedWarpOutput(). ✨

And bestie, if you hand her multiple inputs? the output extent gets calculated to cover all of them, at a resolution that's consistent with the highest-resolution input. she's not playing favorites.

Once the dimensions of the output image are locked in, gdalwarp divides that output image into chunks that can be processed independently, staying within the amount of memory you specified with -wm. Then she iterates over scanlines inside those chunks, and for every single output pixel she determines a rectangular region of source pixels that contribute to the value of that output pixel.

The dimensions of that rectangular region are usually figured out by estimating the relative scales of source vs destination raster — but you can also set them by hand (go read the docs for the XSCALE parameter in GDALWarpOptions::papszWarpOptions if that's your thing). And because the source region is a simple rectangle, it is not possible for an output pixel to be associated with source pixels from both sides of the antimeridian or pole (that's when you're transforming from geographic coordinates, iykyk). 🫠

That rectangular region of source pixels then gets handed off to a function that runs the resampling algorithm you picked with -r. Depending on which resampling algorithm it is and what the relative scales of the source and destination rasters are, source pixels get weighted in one of two ways:

  • by the approximate fraction of the source pixel that is covered by the destination pixel — this is the "mean" and "sum" resampling situation, bestie
  • or by the horizontal and vertical Cartesian distances between the center of the source pixel and the center of the target pixel — that's bilinear or cubic spline resampling, the glow-up squad

In that second case, the relative weight of an individual source pixel comes from the product of the weights determined for its row and column. and nope, the diagonal Cartesian distance is not calculated. periodt.

🌸 MULTIPLE INPUT FILES 🌸

When you give gdalwarp multiple inputs, they get processed independently, in the order they're listed. Let's be real though — that can introduce edge effects near the boundaries of the input files, because the output pixel values will be derived from the final input only. 😭

To avoid that whole mess, you can first combine your non-overlapping input files into a VRT file (like, using gdalbuildvrt, iconic tool). Then gdalwarp can use pixels from all the inputs when it's calculating output pixel values. slay. 💖

🎀 WRITING TO AN EXISTING FILE 🎀

Mosaicing into an existing output file? Supported, as long as the output file already exists. But heads up: the spatial extent of the existing file will not be modified to accommodate new data. so if that's the energy you need, you may have to remove it, or use the -overwrite option instead. 🙈

Polygon cutlines can be used as a mask to restrict the area of the destination file that may be updated — including blending, fancy. now, if the OGR layer holding those cutline features has no explicit SRS, the cutline features are assumed to be in the SRS of the destination file. And when you're writing to a not-yet-existing target dataset, its extent will be the one of the original raster — unless you specified -te or -crop_to_cutline. ok so basically know your defaults bestie. ✨

💜 NODATA / SOURCE VALIDITY MASK HANDLING 💜

Invalid values in source pixels — whether you found them through a nodata value metadata set on the source band, a mask band, an alpha band, or by using -srcnodata — will not be used in interpolation. bye! 👋

How exactly that gets taken into account depends on the resampling kernel, so here's the breakdown:

  • for nearest resampling: for each target pixel, the coordinate of its center gets projected back to source coordinates, and the source pixel containing that coordinate is identified. If that source pixel is invalid, the target pixel is considered as nodata.
  • for bilinear, cubic, cubicspline and lanczos: for each target pixel, the coordinate of its center gets projected back to source coordinates and a corresponding source pixel is identified. If that source pixel is invalid, the target pixel is considered as nodata — and in this case, valid pixels within the kernel radius would not be considered. 😭 Now, given that those resampling kernels have a non-null kernel radius, that source pixel is just one among several other source pixels, and it might be possible that there are invalid values in those other contributing source pixels too. The weights used to take those invalid values into account will be set to zero to ignore them.
  • for the other resampling methods: source pixels contributing to the target pixel are ignored if invalid. Only the valid ones get taken into account. And if there are none? the target pixel is considered as nodata.

If you're using -srcnodata for multiple images that have different invalid values, you need to either (a) pre-process them so they all have the same to-be-ignored value, or (b) set the nodata flag for each file. Go with (b) if you need to preserve the original values for some reason, like this:

# for this image we want to ignore black (0)
gdalwarp -srcnodata 0 -dstnodata 0 orig-ignore-black.tif black-nodata.tif

# and now we want to ignore white (0)
gdalwarp -srcnodata 255 -dstnodata 255 orig-ignore-white.tif white-nodata.tif

# and finally ignore a particular blue-grey (RGB 125 125 150)
gdalwarp -srcnodata "125 125 150" -dstnodata "125 125 150" orig-ignore-grey.tif grey-nodata.tif

# now we can mosaic them all and not worry about nodata parameters
gdalwarp black-nodata.tif grey-nodata.tif white-nodata.tif final-mosaic.tif

⭐ APPROXIMATE TRANSFORMATION ⭐

By default, gdalwarp uses a linear approximator for the transformations, with a permitted error of 0.125 pixels in the source dataset. 🎯

Here's how it goes: for each processing chunk, the approximator precisely transforms three points per output scanline — the start, the middle, and the end — from a row and column in the output dataset to a row and column in the source dataset. Then it compares a linear approximation of the center point coordinates against the precisely transformed value.

If the sum of the horizontal and vertical errors is less than the error threshold, the remaining source points get approximated using linear interpolation between the start and middle point, and between the middle and end point. Neat. ✨

But if the error exceeds the threshold? the scanline gets split into two sections, and the approximator gets recursively applied to each section — over and over — until the error is less than the threshold or all points have been exactly computed. she's thorough, okay?

heads up bestie: a processing chunk does not necessarily correspond to a whole destination scanline. If the output dataset is tiled, its shape will typically be one or several tiles. The OPTIMIZE_SIZE warping option and the value of the -wm option can also influence the shape of the processing chunk. So for a single (non-zero) value of the error threshold, the linear approximation might result in slightly different values in coordinate transformation — but all of them stay within the permitted error. no drama. 💅

The error threshold (in source dataset pixels) can be controlled with the gdalwarp -et switch. And if you want a true pixel-by-pixel reprojection comparison? use -et 0, which disables this approximator entirely. full precision, no shortcuts, main character energy. 👑

🌈 VERTICAL TRANSFORMATION 🌈

So gdalwarp is most commonly out here doing coordinate transformations in 2D space, but plot twist — she can also do vertical transformations. 💅

These vertical transformations are performed automatically when these two conditions are met:

  • at least one of the source or target CRS has an explicit vertical CRS (as part of a compound CRS) or is a 3D (generally geographic) CRS, and
  • the raster has a single band

You can also force this mode with -vshift — which is essentially useful when the CRS involved aren't explicitly 3D, but a transformation pipeline is specified with -ct. Or you can disable it with -novshift. your call bestie ✨

When a vertical transformation is involved, typically a shift value read in a geoid grid gets applied. That may require such grid(s) to be installed, or PROJ networking capabilities to be enabled. Consult PROJ documentation for more details, because that's a whole other saga.

In addition to a shift, the raster values may be multiplied by a factor to take into account vertical unit changes. Priority order: the value returned by GDALRasterBand::GetUnitType() is used. 🌸

The following values are currently recognized: m, metre, metre, ft, foot, US survey foot.

If there's no defined unit type at the band level, then the vertical unit of the source CRS is used. The vertical unit of the target CRS is also used to determine that conversion factor. And if you want to override the conversion factor entirely, set the MULT_FACTOR_VERTICAL_SHIFT warping option with -wo. For example, -wo MULT_FACTOR_VERTICAL_SHIFT=1 to disable any vertical unit change. 🎀

🧠 MEMORY USAGE (yes bestie we're talking RAM)

Adding RAM will almost certainly make gdalwarp faster. Okay but that is not the same thing as saying it's worth it, or that the speed bump will be significant. Disks are the slowest part of the whole process, periodt. By default gdalwarp will not take much advantage of your RAM at all. Using the flag -wm 500 will operate on 500MB chunks at a time, which is better than the default. And the warp memory you specify with -wm is shared among all threads, so it is especially beneficial to bump this value up when you're running gdalwarp with -wo NUM_THREADS (or its equivalent, GDAL_NUM_THREADS) greater than 1. 🫶

Increasing the I/O block cache size may also help. You do that by setting the GDAL_CACHEMAX configuration like this:

gdalwarp --config GDAL_CACHEMAX 500 -wm 500 ...

So that's 500MB of RAM for read/write caching, plus 500MB of RAM for working buffers during the warp. Beyond that, ngl, it's doubtful more memory will make a substantial difference. 💀

Check your CPU usage while gdalwarp is running. If it is substantially less than 100%, then you know things are IO bound. Otherwise they are CPU bound. The --debug option may also give you useful info. Like, after running:

gdalwarp --debug on abc.tif def.tif

a message like this will be output:

GDAL: 224 block reads on 32 block band 1 of utm.tif

In this case it is saying that band 1 of utm.tif has 32 blocks, but that 224 block reads were done — implying that lots of data was having to be re-read, presumably because of a limited IO cache. You will also see messages like:

GDAL: GDALWarpKernel()::GWKNearestNoMasksByte()
Src=0,0,512x512 Dst=0,0,512x512

The Src/Dst windows show you the "chunk size" being used. In this case it's my whole image, which is very small. If you find things are being broken into a lot of chunks, increasing -wm may help somewhat.

But far more important than memory is making sure you are going through an optimized path in the warper. If you ever see it reporting GDALWarpKernel()::GWKGeneralCase() you know things will be relatively slow. Basically, the fastest situations are nearest neighbour resampling on 8bit data without nodata or alpha masking in effect. ✨

🗜️ COMPRESSED OUTPUT

In some cases, the output of gdalwarp may be much larger than the original, even if you used the exact same compression algorithm. Why? Because by default, gdalwarp operates on chunks that are not necessarily aligned with the boundaries of the blocks/tiles/strips of the output format, so this might cause repeated compression/decompression of partial blocks, leading to lost space in the output format. 🙈

The situation can be improved by using the OPTIMIZE_SIZE warping option (-wo OPTIMIZE_SIZE=YES), but heads up — depending on the source and target projections, it might also significantly slow down the warping process. 😭

Another possibility is to use gdalwarp without compression and then follow up with gdal_translate with compression:

gdalwarp infile tempfile.tif ...options...
gdal_translate tempfile.tif outfile.tif -co compress=lzw ...etc.

Alternatively, you can use a VRT file as the output format of gdalwarp. The VRT file is just an XML file that will be created immediately. The gdal_translate operations will of course be a bit slower, as it will do the real warping operation.

gdalwarp -of VRT infile tempfile.vrt ...options...
gdal_translate tempfile.vrt outfile.tif -co compress=lzw ...etc.

💬 FREQUENTLY ASKED QUESTIONS

Q1. Why does the quality of the output look so bad (no anti-aliasing)?

Did you specify a resampling method with -r, other than the default nearest neighbour? 👀

Q2. Why do I get slightly different results whether the output dataset is tiled or not?

This is related to the fact that an approximate coordinate transformation is used by default to speed-up computation. If you want to get the same results whether the output is tiled or not, set -et to zero. Note, however, that this will only work for relatively small images; other factors can still result in different results. See the following question (Q3).

Q3. Why do I observe artifacts, that look like resolution changes and are aligned with rectangular areas of the output raster, when warping sufficiently large rasters, particularly in areas where the reprojection involves significant deformation and only with non-nearest resampling?

The warping engine operates on rectangular areas of the output dataset (generally aligned with tile boundaries for a compressed tile dataset).

During reprojection, a single source pixel does not generally correspond to a single output pixel. The resampling method must therefore properly account for this and compute a ratio between the number of source and target pixels in the horizontal (X) and vertical (Y) directions. These ratios are computed per warping chunk. This maximizes the local quality of the warping but has the downside of creating visual discontinuities between warping chunks.

If you favor a seamless result, you may manually specify the XSCALE and YSCALE warping options with -wo. The XSCALE (resp. YSCALE) value is the ratio expressing the resampling factor, i.e. the number of destination pixels per source pixel, along the horizontal (resp. vertical) axis. It equals to one for no resampling, is below one for downsampling, and above one for upsampling. 🧚

🌈 EXAMPLES (the fun part, let's go)

  • Basic transformation:
gdalwarp -t_srs EPSG:4326 input.tif output.tif
  • For instance, an eight bit spot scene stored in GeoTIFF with control points mapping the corners to lat/long could be warped to a UTM projection with a command like this:
gdalwarp -t_srs '+proj=utm +zone=11 +datum=WGS84' -overwrite raw_spot.tif utm11.tif
  • For instance, the second channel of an ASTER image stored in HDF with control points mapping the corners to lat/long could be warped to a UTM projection with a command like this:
gdalwarp -overwrite HDF4_SDS:ASTER_L1B:"pg-PR1B0000-2002031402_100_001":2 \
    pg-PR1B0000-2002031402_100_001_2.tif
  • To apply a cutline on a un-georeferenced image and clip from pixel (220,60) to pixel (1160,690):
gdalwarp -overwrite -to SRC_METHOD=NO_GEOTRANSFORM -to DST_METHOD=NO_GEOTRANSFORM \
    -te 220 60 1160 690 -cutline cutline.csv in.png out.tif

where cutline.csv content is like:

id,WKT
1,"POLYGON((....))"
  • To transform a DEM from geoid elevations (using EGM96) to WGS84 ellipsoidal heights:
gdalwarp -overwrite in_dem.tif out_dem.tif -s_srs EPSG:4326+5773 -t_srs EPSG:4979

✅ RETURN STATUS CODE

The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a successful execution). Slay. 💅

🧑‍💻 C API

This utility is also callable from C with GDALWarp().

👑 AUTHOR

Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de>

1998-2026

okay bestie that's a wrap on the whole GDALWARP(1) page 🎀 — sourced from the GDAL docs, dated Aug 18, 2026. go warp something iconic, no cap. 🌸🦋💖

📦 where this page comes from