GDALWARP(1) GDAL GDALWARP(1)
gdalwarp - Image reprojection and warping utility.
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>]...
The gdalwarp utility is an 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.
TIP:
Equivalent in new "gdal" command line interface:
+o gdal raster reproject for reprojection
+o gdal raster update to update the content of a raster with
another one
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
-b <n>
-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.
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.
-t_srs <srs_def>
Set target spatial reference.
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.
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.
-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.
-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.
-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)
-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.
-tr <xres> <yres> | -tr square
Set output file resolution (in target georeferenced units).
If not specified (or not deduced from -te and -ts), gdalwarp
will, in the general case, generate an output raster with
xres=yres.
Starting with GDAL 3.7, if neither -tr nor -ts are specified,
that no reprojection is involved (including taking into
account geolocation arrays or RPC), the resolution of the
source file(s) will be preserved (in previous version, an
output raster with xres=yres was always generated). It is
possible to ask square pixels to still be generated, by
specifying square as the value for -tr.
-tap (target aligned pixels) align the coordinates of the extent of
the output file to the values of the -tr, such that the
aligned extent includes the minimum extent (edges
lines/columns that are detected as blank, before actual
warping, will be removed starting with GDAL 3.8). Alignment
means that xmin / resx, ymin / resy, xmax / resx and ymax /
resy are integer values. It does not necessarily mean that the
output grid aligns with the input grid.
-ts <width> <height>
Set 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. Note that -ts cannot be used with -tr
-ovr <level>|AUTO|AUTO-<n>|NONE
To specify which overview level of source files must be used.
The default choice, AUTO, will select the overview level whose
resolution is the closest to the target resolution. Specify an
integer value (0-based, i.e. 0=1st overview level) to select a
particular level. Specify AUTO-n where n is an integer greater
or equal to 1, to select an overview level below the AUTO one.
Or specify NONE to force the base resolution to be used (can
be useful if overviews have been generated with a low quality
resampling method, and the warping is done using a higher
quality resampling method).
-wo <NAME>=<VALUE>
Set a warp option. The GDALWarpOptions::papszWarpOptions docs
show all options. Multiple -wo options may be listed.
-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.
-wt <type>
Working pixel data type. The data type of pixels in the source
image and destination image buffers.
-r <resampling_method>
Resampling method to use. Available methods are:
near: nearest neighbour resampling (default, fastest
algorithm, worst interpolation quality).
bilinear: bilinear resampling.
cubic: cubic resampling.
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 (use of -tr or -ts),
existing overviews (either internal/implicit or external
ones) on the source image will be used by default by
selecting the closest overview to the desired output
resolution. 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 due to how wavelet compression works.
It might thus be useful in those situations to use the -ovr
NONE option to prevent existing overviews to be used.
-srcnodata "<value>[ <value>]..."
Set nodata masking values for input bands (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. Masked values will not be
used in interpolation (details given 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 is
not 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 (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 ensure that nodata
is not defined. If this argument is not used 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
Prevent the alpha band of a source image to be considered as
such (it will be warped as a regular band)
-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 is not 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 are 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 is some extra overhead in
doing many small chunks so setting it larger is better but it
is a matter of diminishing returns.
-multi Use multithreaded warping implementation. Two threads will be
used to process chunks of image and perform input/output
operation simultaneously. Note that 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
-q Be quiet.
-if <format>
Format/driver name to be attempted to open the input file(s).
It is generally not necessary to specify it, but it can be
used to skip automatic driver detection, when it 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>
Added in version 3.9.
Sets or overrides the SRS of the cutline.
-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. Overwriting
must be understood here 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.
-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 -cvmd option).
-cvmd <meta_conflict_value>
Value to set metadata items that conflict between source
datasets (default is "*"). Use "" to remove conflicting items.
-setci Set the color interpretation of the bands of the target
dataset from the source dataset.
-oo <NAME>=<VALUE>
Dataset open option (format specific)
-doo <NAME>=<VALUE>
Output dataset open option (format specific)
<src_dataset_name>
The source file name(s).
<dst_dataset_name>
The destination file name.
gdalwarp transforms images between different coordinate reference
systems and spatial resolutions.
First, gdalwarp must determine the extent and resolution of the
output, if these have not been specified using -te and -tr. These
are determined by transforming a sample of points from the source CRS
to the destination CRS. Details of the procedure can be found in the
documentation for GDALSuggestedWarpOutput(). If multiple inputs are
provided to gdalwarp, the output extent will be calculated to cover
all of them, at a resolution consistent with the highest-resolution
input.
Once the dimensions of the output image have been determined,
gdalwarp divides the output image into chunks that can be processed
independently within the amount of memory specified by -wm. gdalwarp
then iterates over scanlines in these chunks, and for each output
pixel determines a rectangular region of source pixels that
contribute to the value of the output pixel. The dimensions of this
rectangular region are typically determined by estimating the
relative scales of the source and destination raster, but can be
manually specified (see documentation of the XSCALE parameter in
GDALWarpOptions::papszWarpOptions). 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 (when transforming from geographic coordinates).
The rectangular region of source pixels is then provided to a
function that performs the resampling algorithm selected with -r.
Depending on the resampling algorithm and relative scales of the
source and destination rasters, source pixels may be weighted either
according to the approximate fraction of the source pixel that is
covered by the destination pixel (e.g., "mean" and "sum" resampling),
or by horizontal and vertical Cartesian distances between the center
of the source pixel and the center of the target pixel (e.g.,
bilinear or cubic spline resampling). In the latter case, the
relative weight of an individual source pixel is determined by the
product of the weights determined for its row and column; the
diagonal Cartesian distance is not calculated.
When multiple inputs are provided to gdalwarp, they are processed
independently in the order they are listed. This may introduce edge
effects near the boundaries of the input files, because output pixel
values will be derived from the final input only. To avoid this,
non-overlapping input files may first be combined into a VRT file
(e.g., using gdalbuildvrt). This will allow gdalwarp to use pixels
from all inputs when calculating output pixel values.
Mosaicing into an existing output file is supported if the output
file already exists. The spatial extent of the existing file will not
be modified to accommodate new data, so you may have to remove it in
that case, or use the -overwrite option.
Polygon cutlines may be used as a mask to restrict the area of the
destination file that may be updated, including blending. If the OGR
layer containing the cutline features has no explicit SRS, the
cutline features are assumed to be in the SRS of the destination
file. When writing to a not yet existing target dataset, its extent
will be the one of the original raster unless -te or -crop_to_cutline
are specified.
NODATA / SOURCE VALIDITY MASK HANDLING
Invalid values in source pixels, either identified through a nodata
value metadata set on the source band, a mask band, an alpha band or
the use of -srcnodata will not be used in interpolation. The details
of how it is taken into account depends on the resampling kernel:
+o for nearest resampling, for each target pixel, the coordinate of
its center is projected back to source coordinates and the source
pixel containing that coordinate is identified. If this source
pixel is invalid, the target pixel is considered as nodata.
+o for bilinear, cubic, cubicspline and lanczos, for each target
pixel, the coordinate of its center is projected back to source
coordinates and a corresponding source pixel is identified. If this
source pixel is invalid, the target pixel is considered as nodata
(in this case, valid pixels within the kernel radius would not be
considered). Given that those resampling kernels have a non-null
kernel radius, this source pixel is just one among other several
source pixels, and it might be possible that there are invalid
values in those other contributing source pixels. The weights used
to take into account those invalid values will be set to zero to
ignore them.
+o for the other resampling methods, source pixels contributing to the
target pixel are ignored if invalid. Only the valid ones are taken
into account. If there are none, the target pixel is considered as
nodata.
If using -srcnodata for multiple images with different invalid
values, you need to either (a) pre-process them to have the same
to-be-ignored value, or (b) set the nodata flag for each file. Use
(b) if you need to preserve the original values for some reason, for
example:
# 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
By default gdalwarp uses a linear approximator for the
transformations with a permitted error of 0.125 pixels in the source
dataset. For each processing chunk, the approximator precisely
transforms three points per output scanline (the start, middle, and
end) from a row and column in the output dataset to a row and column
in the source dataset. It then compares a linear approximation of
the center point coordinates to the precisely transformed value. If
the sum of the horizontal and vertical errors is less than the error
threshold then the remaining source points are approximated using
linear interpolation between the start and middle point, and between
the middle and end point. If the error exceeds the threshold, the
scanline is split into two sections and the approximator is
recursively applied to each section until the error is less than the
threshold or all points have been exactly computed.
Note that 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. Consequently, 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 within the permitted error.
The error threshold (in source dataset pixels) can be controlled with
the gdalwarp -et switch. If you want to compare a true pixel-by-pixel
reprojection use -et 0 which disables this approximator entirely.
While gdalwarp is most commonly used to perform coordinate
transformations in the 2D space, it can also perform vertical
transformations. Vertical transformations are automatically performed
when the following two conditions are met:
+o 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
+o the raster has a single band
This mode can also be forced by using the -vshift (this is
essentially useful when the CRS involved are not explicitly 3D, but a
transformation pipeline is specified with -ct), or disabled with
-novshift.
When a vertical transformation is involved, typically a shift value
read in a geoid grid will be applied. This may require such grid(s)
to be installed, or PROJ networking capabilities to be enabled.
Consult PROJ documentation for more details. In addition to a shift,
the raster values may be multiplied by a factor to take into account
vertical unit changes. In priority, the value returned by
GDALRasterBand::GetUnitType() is used. The following values are
currently recognized: m, metre, metre, ft, foot, US survey foot. If
there is no defined unit type at the band level, the vertical unit of
the source CRS is used. The vertical unit of the target CRS is also
used to determine that conversion factor. The conversion factor may
be overridden by setting the MULT_FACTOR_VERTICAL_SHIFT warping
option with -wo. For example -wo MULT_FACTOR_VERTICAL_SHIFT=1 to
disable any vertical unit change.
Adding RAM will almost certainly increase the speed of gdalwarp.
That's not at all the same as saying that it is worth it, or that the
speed increase will be significant. Disks are the slowest part of the
process. By default gdalwarp won't take much advantage of RAM. Using
the flag -wm 500 will operate on 500MB chunks at a time which is
better than the default. The warp memory specified by -wm is shared
among all threads, so it is especially beneficial to increase this
value when 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. This can be done
by setting the GDAL_CACHEMAX configuration like:
gdalwarp --config GDAL_CACHEMAX 500 -wm 500 ...
This uses 500MB of RAM for read/write caching, and 500MB of RAM for
working buffers during the warp. Beyond that it is doubtful more
memory will make a substantial difference.
Check 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 provide useful information.
For instance, after running the following:
gdalwarp --debug on abc.tif def.tif
a message like the following 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 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 are ensuring 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.
In some cases, the output of gdalwarp may be much larger than the
original, even if the same compression algorithm is used. 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 note that 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 be of course 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.
Q1. Why does the quality of the output looks 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 result. See
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.
+o Basic transformation:
gdalwarp -t_srs EPSG:4326 input.tif output.tif
+o 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
+o 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
+o 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((....))"
+o 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
This utility is also callable from C with GDALWarp().
Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer
<silke@intevation.de>
1998-2026
March 20, 2026 GDALWARP(1)
NAME
gdalwarp - Image reprojection and warping utility.
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
The gdalwarp utility is an 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.
TIP:
Equivalent in new "gdal" command line interface:
+o gdal raster reproject for reprojection
+o gdal raster update to update the content of a raster with
another one
--help Show this help message and exit
--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.
-b <n>
-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.
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.
-t_srs <srs_def>
Set target spatial reference.
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.
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.
-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.
-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.
-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)
-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.
-tr <xres> <yres> | -tr square
Set output file resolution (in target georeferenced units).
If not specified (or not deduced from -te and -ts), gdalwarp
will, in the general case, generate an output raster with
xres=yres.
Starting with GDAL 3.7, if neither -tr nor -ts are specified,
that no reprojection is involved (including taking into
account geolocation arrays or RPC), the resolution of the
source file(s) will be preserved (in previous version, an
output raster with xres=yres was always generated). It is
possible to ask square pixels to still be generated, by
specifying square as the value for -tr.
-tap (target aligned pixels) align the coordinates of the extent of
the output file to the values of the -tr, such that the
aligned extent includes the minimum extent (edges
lines/columns that are detected as blank, before actual
warping, will be removed starting with GDAL 3.8). Alignment
means that xmin / resx, ymin / resy, xmax / resx and ymax /
resy are integer values. It does not necessarily mean that the
output grid aligns with the input grid.
-ts <width> <height>
Set 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. Note that -ts cannot be used with -tr
-ovr <level>|AUTO|AUTO-<n>|NONE
To specify which overview level of source files must be used.
The default choice, AUTO, will select the overview level whose
resolution is the closest to the target resolution. Specify an
integer value (0-based, i.e. 0=1st overview level) to select a
particular level. Specify AUTO-n where n is an integer greater
or equal to 1, to select an overview level below the AUTO one.
Or specify NONE to force the base resolution to be used (can
be useful if overviews have been generated with a low quality
resampling method, and the warping is done using a higher
quality resampling method).
-wo <NAME>=<VALUE>
Set a warp option. The GDALWarpOptions::papszWarpOptions docs
show all options. Multiple -wo options may be listed.
-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.
-wt <type>
Working pixel data type. The data type of pixels in the source
image and destination image buffers.
-r <resampling_method>
Resampling method to use. Available methods are:
near: nearest neighbour resampling (default, fastest
algorithm, worst interpolation quality).
bilinear: bilinear resampling.
cubic: cubic resampling.
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 (use of -tr or -ts),
existing overviews (either internal/implicit or external
ones) on the source image will be used by default by
selecting the closest overview to the desired output
resolution. 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 due to how wavelet compression works.
It might thus be useful in those situations to use the -ovr
NONE option to prevent existing overviews to be used.
-srcnodata "<value>[ <value>]..."
Set nodata masking values for input bands (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. Masked values will not be
used in interpolation (details given 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 is
not 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 (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 ensure that nodata
is not defined. If this argument is not used 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
Prevent the alpha band of a source image to be considered as
such (it will be warped as a regular band)
-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 is not 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 are 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 is some extra overhead in
doing many small chunks so setting it larger is better but it
is a matter of diminishing returns.
-multi Use multithreaded warping implementation. Two threads will be
used to process chunks of image and perform input/output
operation simultaneously. Note that 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
-q Be quiet.
-if <format>
Format/driver name to be attempted to open the input file(s).
It is generally not necessary to specify it, but it can be
used to skip automatic driver detection, when it 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>
Added in version 3.9.
Sets or overrides the SRS of the cutline.
-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. Overwriting
must be understood here 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.
-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 -cvmd option).
-cvmd <meta_conflict_value>
Value to set metadata items that conflict between source
datasets (default is "*"). Use "" to remove conflicting items.
-setci Set the color interpretation of the bands of the target
dataset from the source dataset.
-oo <NAME>=<VALUE>
Dataset open option (format specific)
-doo <NAME>=<VALUE>
Output dataset open option (format specific)
<src_dataset_name>
The source file name(s).
<dst_dataset_name>
The destination file name.
OVERVIEW
gdalwarp transforms images between different coordinate reference
systems and spatial resolutions.
First, gdalwarp must determine the extent and resolution of the
output, if these have not been specified using -te and -tr. These
are determined by transforming a sample of points from the source CRS
to the destination CRS. Details of the procedure can be found in the
documentation for GDALSuggestedWarpOutput(). If multiple inputs are
provided to gdalwarp, the output extent will be calculated to cover
all of them, at a resolution consistent with the highest-resolution
input.
Once the dimensions of the output image have been determined,
gdalwarp divides the output image into chunks that can be processed
independently within the amount of memory specified by -wm. gdalwarp
then iterates over scanlines in these chunks, and for each output
pixel determines a rectangular region of source pixels that
contribute to the value of the output pixel. The dimensions of this
rectangular region are typically determined by estimating the
relative scales of the source and destination raster, but can be
manually specified (see documentation of the XSCALE parameter in
GDALWarpOptions::papszWarpOptions). 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 (when transforming from geographic coordinates).
The rectangular region of source pixels is then provided to a
function that performs the resampling algorithm selected with -r.
Depending on the resampling algorithm and relative scales of the
source and destination rasters, source pixels may be weighted either
according to the approximate fraction of the source pixel that is
covered by the destination pixel (e.g., "mean" and "sum" resampling),
or by horizontal and vertical Cartesian distances between the center
of the source pixel and the center of the target pixel (e.g.,
bilinear or cubic spline resampling). In the latter case, the
relative weight of an individual source pixel is determined by the
product of the weights determined for its row and column; the
diagonal Cartesian distance is not calculated.
MULTIPLE INPUT FILES
When multiple inputs are provided to gdalwarp, they are processed
independently in the order they are listed. This may introduce edge
effects near the boundaries of the input files, because output pixel
values will be derived from the final input only. To avoid this,
non-overlapping input files may first be combined into a VRT file
(e.g., using gdalbuildvrt). This will allow gdalwarp to use pixels
from all inputs when calculating output pixel values.
WRITING TO AN EXISTING FILE
Mosaicing into an existing output file is supported if the output
file already exists. The spatial extent of the existing file will not
be modified to accommodate new data, so you may have to remove it in
that case, or use the -overwrite option.
Polygon cutlines may be used as a mask to restrict the area of the
destination file that may be updated, including blending. If the OGR
layer containing the cutline features has no explicit SRS, the
cutline features are assumed to be in the SRS of the destination
file. When writing to a not yet existing target dataset, its extent
will be the one of the original raster unless -te or -crop_to_cutline
are specified.
NODATA / SOURCE VALIDITY MASK HANDLING
Invalid values in source pixels, either identified through a nodata
value metadata set on the source band, a mask band, an alpha band or
the use of -srcnodata will not be used in interpolation. The details
of how it is taken into account depends on the resampling kernel:
+o for nearest resampling, for each target pixel, the coordinate of
its center is projected back to source coordinates and the source
pixel containing that coordinate is identified. If this source
pixel is invalid, the target pixel is considered as nodata.
+o for bilinear, cubic, cubicspline and lanczos, for each target
pixel, the coordinate of its center is projected back to source
coordinates and a corresponding source pixel is identified. If this
source pixel is invalid, the target pixel is considered as nodata
(in this case, valid pixels within the kernel radius would not be
considered). Given that those resampling kernels have a non-null
kernel radius, this source pixel is just one among other several
source pixels, and it might be possible that there are invalid
values in those other contributing source pixels. The weights used
to take into account those invalid values will be set to zero to
ignore them.
+o for the other resampling methods, source pixels contributing to the
target pixel are ignored if invalid. Only the valid ones are taken
into account. If there are none, the target pixel is considered as
nodata.
If using -srcnodata for multiple images with different invalid
values, you need to either (a) pre-process them to have the same
to-be-ignored value, or (b) set the nodata flag for each file. Use
(b) if you need to preserve the original values for some reason, for
example:
# 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. For each processing chunk, the approximator precisely
transforms three points per output scanline (the start, middle, and
end) from a row and column in the output dataset to a row and column
in the source dataset. It then compares a linear approximation of
the center point coordinates to the precisely transformed value. If
the sum of the horizontal and vertical errors is less than the error
threshold then the remaining source points are approximated using
linear interpolation between the start and middle point, and between
the middle and end point. If the error exceeds the threshold, the
scanline is split into two sections and the approximator is
recursively applied to each section until the error is less than the
threshold or all points have been exactly computed.
Note that 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. Consequently, 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 within the permitted error.
The error threshold (in source dataset pixels) can be controlled with
the gdalwarp -et switch. If you want to compare a true pixel-by-pixel
reprojection use -et 0 which disables this approximator entirely.
VERTICAL TRANSFORMATION
While gdalwarp is most commonly used to perform coordinate
transformations in the 2D space, it can also perform vertical
transformations. Vertical transformations are automatically performed
when the following two conditions are met:
+o 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
+o the raster has a single band
This mode can also be forced by using the -vshift (this is
essentially useful when the CRS involved are not explicitly 3D, but a
transformation pipeline is specified with -ct), or disabled with
-novshift.
When a vertical transformation is involved, typically a shift value
read in a geoid grid will be applied. This may require such grid(s)
to be installed, or PROJ networking capabilities to be enabled.
Consult PROJ documentation for more details. In addition to a shift,
the raster values may be multiplied by a factor to take into account
vertical unit changes. In priority, the value returned by
GDALRasterBand::GetUnitType() is used. The following values are
currently recognized: m, metre, metre, ft, foot, US survey foot. If
there is no defined unit type at the band level, the vertical unit of
the source CRS is used. The vertical unit of the target CRS is also
used to determine that conversion factor. The conversion factor may
be overridden by setting 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
Adding RAM will almost certainly increase the speed of gdalwarp.
That's not at all the same as saying that it is worth it, or that the
speed increase will be significant. Disks are the slowest part of the
process. By default gdalwarp won't take much advantage of RAM. Using
the flag -wm 500 will operate on 500MB chunks at a time which is
better than the default. The warp memory specified by -wm is shared
among all threads, so it is especially beneficial to increase this
value when 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. This can be done
by setting the GDAL_CACHEMAX configuration like:
gdalwarp --config GDAL_CACHEMAX 500 -wm 500 ...
This uses 500MB of RAM for read/write caching, and 500MB of RAM for
working buffers during the warp. Beyond that it is doubtful more
memory will make a substantial difference.
Check 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 provide useful information.
For instance, after running the following:
gdalwarp --debug on abc.tif def.tif
a message like the following 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 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 are ensuring 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 the same compression algorithm is used. 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 note that 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 be of course 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 looks 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 result. See
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
+o Basic transformation:
gdalwarp -t_srs EPSG:4326 input.tif output.tif
+o 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
+o 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
+o 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((....))"
+o 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
C API
This utility is also callable from C with GDALWarp().
AUTHOR
Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer
<silke@intevation.de>
COPYRIGHT
1998-2026
March 20, 2026 GDALWARP(1)