| GDALWARP(1) | GDAL | GDALWARP(1) |
gdalwarp - Image reprojection and warping utility.
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.
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
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)
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.
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.
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.
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.
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.
New in version 3.0.
New in version 3.4.
NOTE:
New in version 3.4.
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.
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:
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.
New in version 2.2.
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.
New in version 3.2.
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.
Sets or overrides the SRS of the cutline.
New in version 2.1.
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.
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.
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:
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. 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.
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:
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.
gdalwarp -t_srs EPSG:4326 input.tif output.tif
gdalwarp -t_srs '+proj=utm +zone=11 +datum=WGS84' -overwrite raw_spot.tif utm11.tif
gdalwarp -overwrite HDF4_SDS:ASTER_L1B:"pg-PR1B0000-2002031402_100_001":2 \
pg-PR1B0000-2002031402_100_001_2.tif
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((....))"
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-2025
| January 8, 2025 |