Provided by: gdal-bin_3.8.4+dfsg-3ubuntu3_amd64 
NAME
gdalwarp - Image reprojection and warping utility.
SYNOPSIS
gdalwarp [--help] [--help-general] [--formats]
[-b|-srcband <n>]... [-dstband <n>]...
[-s_srs <srs_def>] [-t_srs <srs_def>] [-ct <string>]
[-to <NAME>=<VALUE>]... [-vshift | -novshift]
[-s_coord_epoch <epoch>] [-t_coord_epoch <epoch>]
[-order n | -tps | -rpc | -geoloc] [-et <err_threshold>]
[-refine_gcps <tolerance> [<minimum_gcps>]]
[-te <xmin> <ymin> <xmax> <ymax>] [-te_srs <srs_def>]
[-tr <xres> <yres>]|[-tr square] [-tap] [-ts <width> <height>]
[-ovr <level>|AUTO|AUTO-<n>|NONE] [-wo <NAME>=<VALUE>]... [-ot Byte/Int16/...] [-wt Byte/Int16]
[-srcnodata "<value>[ <value>...]"][-dstnodata "<value>[ <value>...]"]
[-srcalpha|-nosrcalpha] [-dstalpha]
[-r <resampling_method>] [-wm <memory_in_mb>] [-multi] [-q]
[-cutline <datasource>] [-cl <layer>] [-cwhere <expression>]
[-csql <statement>] [-cblend <dist_in_pixels>] [-crop_to_cutline]
[-if <format>]... [-of <format>] [-co <NAME>=<VALUE>]... [-overwrite]
[-nomd] [-cvmd <meta_conflict_value>] [-setci] [-oo <NAME>=<VALUE>]...
[-doo <NAME>=<VALUE>]...
<srcfile>... <dstfile>
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.
--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>
New 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>
New 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.
Starting with GDAL 2.2, if the SRS has an explicit vertical datum that points to a
PROJ.4 geoidgrids, 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>
New 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 are 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.
Starting with GDAL 2.2, if the SRS has an explicit vertical datum that points to a
PROJ.4 geoidgrids, 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>
New 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 are 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. 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.
New 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.
New 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 in GDAL 2.2 to 3.3.
New 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.
-rpc Force use of RPCs.
-geoloc
Force use of Geolocation Arrays.
-et <err_threshold>
Error threshold for transformation approximation (in pixel units - defaults to
0.125, unless, starting with GDAL 2.1, 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. Not 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.
-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 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)
New in version 2.2.
-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. The value
is interpreted as being in megabytes if the value is less than 10000. For values
>=10000, this 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.
New in version 3.2.
-of <format>
Select the output format. Starting with GDAL 2.3, if not specified, the format is
guessed from the extension (previously was GTiff). 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 --formats 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>
Enable use of a blend cutline from the name OGR support datasource.
-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)
New in version 2.1.
<srcfile>
The source file name(s).
<dstfile>
The destination file name.
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 must 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.
Starting with GDAL 3.1, it is possible to use as output format a driver that only supports
the CreateCopy operation. This may internally imply creation of a temporary file.
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:
• 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.
• 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.
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.
• 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. The approximator basically transforms three points on a scanline:
the start, end and middle. Then it compares the linear approximation of the center based
on the end points to the real thing and checks the error. If the error is less than the
error threshold then the remaining points are approximated (in two chunks utilizing the
center 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.
The error threshold (in 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.
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.
EXAMPLES
• 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:
New in version 2.2.
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:
New in version 2.2.
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().
SEE ALSO
Wiki page discussing options and behaviours of gdalwarp
AUTHOR
Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@intevation.de>
COPYRIGHT
1998-2024
Feb 08, 2024 GDALWARP(1)