FreeBSD Manual Pages
GDAL-RASTER-REPROJECT(1) GDAL 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] [not available in pipelines] -o, --output <OUTPUT> Output raster dataset [required] [not available in pipelines] 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 or warning message) [not available in pipelines] Options: -f, --of, --format, --output-format <OUTPUT-FORMAT> Output format ("GDALG" allowed) [not available in pipelines] --co, --creation-option <KEY>=<VALUE> Creation option [may be repeated] [not available in pipelines] --overwrite Whether overwriting existing output dataset is allowed [not available in pipelines] Mutually exclusive with --append --append Append as a subdataset to existing output [not available in pipelines] Mutually exclusive with --overwrite -s, --input-crs <INPUT-CRS> Input CRS --like <DATASET> Dataset to use as a template for target bounds, CRS, size and nodata -d, --output-crs <OUTPUT-CRS> Output 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] [not available in pipelines] --oo, --open-option <KEY>=<VALUE> Open options [may be repeated] [not available in pipelines] --target-aligned-pixels Round target extent to target resolution --input-nodata <INPUT-NODATA> Set nodata values for input bands ('None' to unset). [1.. values] --output-nodata <OUTPUT-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 pro- gram 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 docu- mentation 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 inde- pendently. 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 transform- ing 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 Carte- sian 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 PROGRAM-SPECIFIC OPTIONS --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>. --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 declara- tions, 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 --output-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. --like <DATASET> Name of GDAL input dataset that serves as a template for default values of options --size, --resolution --output-crs and --bbox Note that the pixel values will not be copied, and that spatial registra- tion of the template dataset through mechanisms such as GCP, RPC or geolocation array is ignored. --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. -j, --num-threads <value> Added in version 3.12. Number of jobs to run at once. Default: number of CPUs detected. --input-crs, -s <INPUT-CRS> Set input 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 declara- tions, 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. --input-nodata <NODATA> Set nodata masking values for input bands (different values can be supplied for each band). If more than one value is supplied all val- ues 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 UNI- FIED_SRC_NODATA warping option (see GDALWarpOptions::papszWarpOptions) to be set to YES, if it is not explicitly set. If --input-nodata is not explicitly set, but the source dataset has nodata values, they will be taken into account, with UNIFIED_SRC_NO- DATA at PARTIAL by default. --output-crs, -d, <OUTPUT-CRS> Set output 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 declara- tions, 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. --output-nodata <NODATA> 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 possi- ble the nodata value will be recorded in the output file. Use a value of None to ensure that nodata is not defined. If this argu- ment 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. -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 identi- fied as the mode will be selected. max: maximum resampling, selects the maximum value from all non-NO- DATA contributing pixels. min: minimum resampling, selects the minimum value from all non-NO- DATA 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 spec- ify 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 reprojec- tion 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 gener- ated). 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 resolu- tion. Mutually exclusive with --resolution. --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 mini- mum 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. --to, --transform-option <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 --wo, --warp-option <NAME>=<VALUE> Set a warp option. The GDALWarpOptions::papszWarpOptions docs show all options. Multiple options may be listed. STANDARD OPTIONS --append Append input raster as a new subdataset to an existing output file. Only works with drivers that support adding subdatasets such as GTiff -- GeoTIFF File Format and GPKG -- GeoPackage raster This also creates the output dataset if it does not exist yet. --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 sim- ple formats have no creation options at all. A list of options sup- ported 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 for- mat specific documentation for legal creation options for each for- mat. --if, --input-format <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 sev- eral candidate drivers. Note that it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions. May be repeated. --oo, --open-option <NAME>=<VALUE> Dataset open option (format specific). May be repeated. -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 --overwrite Allow program to overwrite existing target file or dataset. Other- wise, by default, gdal errors out if the target file or dataset al- ready exists. -q, --quiet Suppress progress bar and some warning messages. 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 val- ues) or the use of --input-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 cen- ter is projected back to source coordinates and the source pixel contain- ing 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 in- valid, the target pixel is considered as nodata (in this case, valid pix- els 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 tar- get pixel are ignored if invalid. Only the valid ones are taken into ac- count. If there are none, the target pixel is considered as nodata. APPROXIMATE TRANSFORMATION By default gdal raster reproject uses a linear approximator for the trans- formations 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 col- umn 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 er- rors 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 typi- cally 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 re- sult 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 re- projection use --error-threshold=0 which disables this approximator en- tirely. 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 de- fault 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 re- sults 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 suffi- ciently large rasters, particularly in areas where the reprojection in- volves 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 ac- count 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 pix- els 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. RETURN STATUS CODE The program returns status code 0 in case of success, and non-zero in case of error (non-blocking errors emitted as warnings are considered as a suc- cessful execution). EXAMPLES Example 1: Reproject a GeoTIFF file to CRS EPSG:32632 ("WGS 84 / UTM zone 32N") $ gdal raster reproject --output-crs=EPSG:32632 in.tif out.tif --overwrite Example 2: Converting a raster that uses an embedded CRS without a known identifier In this example, the input file has an embedded CRS defined in WKT2 but without an associated identifier, and it will be reprojected to the known - ESRI:54052 CRS identifier. Using "PROFILE=BASELINE" creates a PAM file that stores the CRS using the ESRI:54052 identifier, instead of embedding CRS information in GeoTIFF metadata tags. See GTiff PROFILE. $ gdal raster reproject --creation-option "PROFILE=BASELINE" --output-crs=ESRI:54052 input.tif output.tif --overwrite AUTHOR Even Rouault <even.rouault@spatialys.com> COPYRIGHT 1998-2026 Jun 05, 2026 GDAL-RASTER-REPROJECT(1)
NAME | SYNOPSIS | DESCRIPTION | PROGRAM-SPECIFIC OPTIONS | STANDARD OPTIONS | NODATA / SOURCE VALIDITY MASK HANDLING | APPROXIMATE TRANSFORMATION | FREQUENTLY ASKED QUESTIONS | GDALG OUTPUT (ON-THE-FLY / STREAMED DATASET) | RETURN STATUS CODE | EXAMPLES | AUTHOR | COPYRIGHT
Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=gdal-raster-reproject&sektion=1&manpath=FreeBSD+Ports+15.1.quarterly>