GDAL-RASTER-REPROJECT(1) GDAL GDAL-RASTER-REPROJECT(1)
gdal-raster-reproject - Reproject a raster dataset
Added in version 3.11.
Usage: gdal raster reproject [OPTIONS] <INPUT> <OUTPUT>
Reproject a raster dataset.
Positional arguments:
-i, --input <INPUT> Input raster datasets [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]
-q, --quiet Quiet mode (no 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
Mutually exclusive with --append
--append Append as a subdataset to existing output
Mutually exclusive with --overwrite
-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
-j, --num-threads <NUM-THREADS> Number of jobs (or ALL_CPUS) (default: ALL_CPUS)
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
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
-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, --creation-option <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.
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.
-d, --dst-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.
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.
-r, --resampling <RESAMPLING>
Resampling method to use. Available methods are:
nearest: 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
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
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 --size), the program
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).
Mutually exclusive with --size.
--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.
Mutually exclusive 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.
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.
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.
-j, --num-threads <value>
Added in version 3.12.
Number of jobs to run at once. Default: number of CPUs
detected.
--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.
--add-alpha
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.
To match the gdalwarp -rpc option, use --to METHOD=RPC
--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:
+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.
By default gdal raster reproject 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 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 --error-threshold switch. If you want to compare a true
pixel-by-pixel reprojection use --error-threshold=0 which disables
this approximator entirely.
Q1. Why does the quality of the output looks so bad (no
anti-aliasing)?
Did you specify a resampling method, with --resampling, 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
--error-threshold 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.
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.
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
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026 GDAL-RASTER-REPROJECT(1)
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 datasets [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]
-q, --quiet Quiet mode (no 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
Mutually exclusive with --append
--append Append as a subdataset to existing output
Mutually exclusive with --overwrite
-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
-j, --num-threads <NUM-THREADS> Number of jobs (or ALL_CPUS) (default: ALL_CPUS)
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, --creation-option <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.
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.
-d, --dst-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.
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.
-r, --resampling <RESAMPLING>
Resampling method to use. Available methods are:
nearest: 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
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
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 --size), the program
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).
Mutually exclusive with --size.
--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.
Mutually exclusive 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.
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.
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.
-j, --num-threads <value>
Added in version 3.12.
Number of jobs to run at once. Default: number of CPUs
detected.
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.
--add-alpha
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.
To match the gdalwarp -rpc option, use --to METHOD=RPC
--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:
+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.
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. 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 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 --error-threshold switch. If you want to compare a true
pixel-by-pixel reprojection use --error-threshold=0 which disables
this approximator entirely.
FREQUENTLY ASKED QUESTIONS
Q1. Why does the quality of the output looks so bad (no
anti-aliasing)?
Did you specify a resampling method, with --resampling, 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
--error-threshold 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.
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-2026
March 20, 2026 GDAL-RASTER-REPROJECT(1)