NAME

gdal-raster-reproject - Reproject a raster dataset

Added in version 3.11.

SYNOPSIS

Usage: gdal raster reproject [OPTIONS] <INPUT> <OUTPUT>
Reproject a raster dataset.
Positional arguments:


  -i, --input <INPUT>                                  Input raster dataset [required]


  -o, --output <OUTPUT>                                Output raster dataset [required]
Common Options:


  -h, --help                                           Display help message and exit


  --json-usage                                         Display usage as JSON document and exit


  --config <KEY>=<VALUE>                               Configuration option [may be repeated]


  --progress                                           Display progress bar
Options:


  -f, --of, --format, --output-format <OUTPUT-FORMAT>  Output format ("GDALG" allowed)


  --co, --creation-option <KEY>=<VALUE>                Creation option [may be repeated]


  --overwrite                                          Whether overwriting existing output is allowed


  -s, --src-crs <SRC-CRS>                              Source CRS


  -d, --dst-crs <DST-CRS>                              Destination CRS


  -r, --resampling <RESAMPLING>                        Resampling method. RESAMPLING=nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode|min|max|med|q1|q3|sum (default: nearest)


  --resolution <xres>,<yres>                           Target resolution (in destination CRS units)


                                                       Mutually exclusive with --size


  --size <width>,<height>                              Target size in pixels


                                                       Mutually exclusive with --resolution


  --bbox <BBOX>                                        Target bounding box (in destination CRS units)


  --bbox-crs <BBOX-CRS>                                CRS of target bounding box
Advanced Options:


  --if, --input-format <INPUT-FORMAT>                  Input formats [may be repeated]


  --oo, --open-option <KEY>=<VALUE>                    Open options [may be repeated]


  --target-aligned-pixels                              Round target extent to target resolution


  --src-nodata <SRC-NODATA>                            Set nodata values for input bands ('None' to unset). [1.. values]


  --dst-nodata <DST-NODATA>                            Set nodata values for output bands ('None' to unset). [1.. values]


  --add-alpha                                          Adds an alpha mask band to the destination when the source raster have none.


  --wo, --warp-option <NAME>=<VALUE>                   Warping option(s) [may be repeated]


  --to, --transform-option <NAME>=<VALUE>              Transform option(s) [may be repeated]


  --et, --error-threshold <ERROR-THRESHOLD>            Error threshold

DESCRIPTION

gdal raster reproject can be used to reproject a raster dataset. The program can reproject to any supported projection.

First, gdal raster reproject must determine the extent and resolution of the output, if these have not been specified using --bbox and --resolution. 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 gdal raster reproject, 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, gdal raster reproject divides the output image into chunks that can be processed independently. gdal raster reproject 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 --resampling. 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.

This subcommand is also available as a potential step of gdal raster pipeline

Standard options

-f, --of, --format, --output-format <OUTPUT-FORMAT>: Which output raster format to use. Allowed values may be given by gdal --formats | grep raster | grep rw | sort

--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.

May be repeated.

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.

--overwrite: Allow program to overwrite existing target file or dataset. Otherwise, by default, gdal errors out if the target file or dataset already exists.

-s, --src-crs <SRC-CRS>

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.

-d, --dst-crs <SRC-CRS>

Set source spatial reference. If not specified the SRS found in the input dataset will be used.

-r, --resampling <RESAMPLING>

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 --resolution or --size), 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.

--resolution <xres>,<yres>

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.

If neither --resolution nor --size 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).

--size <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 --size cannot be used with --resolution

--bbox <xmin>,<ymin>,<xmax>,<ymax>: Set georeferenced extents of output file to be created (in target SRS by default, or in the SRS specified with --bbox-crs)

--bbox-crs <BBOX-CRS>

Specifies the SRS in which to interpret the coordinates given with --bbox.

This must not be confused with --dst-crs which is the target SRS of the output dataset. --bbox-crs 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.

--target-aligned-pixels: Align the coordinates of the extent of the output file to the values of the --resolution, such that the aligned extent includes the minimum extent (edges lines/columns that are detected as blank, before actual warping, will be removed). Alignment means that xmin / resx, ymin / resy, xmax / resx and ymax / resy are integer values.

Advanced options

--src-nodata <SRCNODATA>

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 --src-nodata 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.

--dst-nodata <DSTNODATA>: 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. Note that a number of output formats, including GeoTIFF, do not support different per-band nodata values, but a single one for all bands.

--addalpha: Create an output alpha band to identify nodata (unset/transparent) pixels. Value 0 is used for fully transparent pixels. The maximum value for the alpha band, for fully opaque pixels, depends on the data type and the presence of the NBITS band metadata item. If it is present, the maximum value is 2^NBITS-1. Otherwise, if NBITS is not set and the alpha band is of type UInt16 (resp. Int16), 65535 (resp. 32767) is used. Otherwise, 255 is used. The maximum value can also be overridden with --wo DST_ALPHA_MAX=<value>.

--wo, --warp-option <NAME>=<VALUE>: Set a warp option. The GDALWarpOptions::papszWarpOptions docs show all options. Multiple options may be listed.

-to <NAME>=<VALUE>: Set a transformer option suitable to pass to GDALCreateGenImgProjTransformer2(). See GDALCreateRPCTransformerV2() for RPC specific options.

--et, --error-threshold <ERROR-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. --error-threshold=0, will be used.

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 (for an alpha band, a value of 0 means invalid. Other values are used for blending values) or the use of --src-nodata 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 (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.
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.

APPROXIMATE TRANSFORMATION

By default gdal raster reproject 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 --error-threshold switch. If you want to compare a true pixel-by-pixel reprojection use --error-threshold=0 which disables this approximator entirely.

GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET)

This program supports serializing the command line as a JSON file using the GDALG output format. The resulting file can then be opened as a raster dataset using the GDALG: GDAL Streamed Algorithm driver, and apply the specified pipeline in a on-the-fly / streamed way.

EXAMPLES

Example 1: Reproject a GeoTIFF file to CRS EPSG:32632 ("WGS 84 / UTM zone 32N")

$ gdal raster reproject --dst-crs=EPSG:32632 in.tif out.tif --overwrite

AUTHOR

Even Rouault <even.rouault@spatialys.com>

COPYRIGHT

1998-2025