GDAL_TRANSLATE(1) GDAL GDAL_TRANSLATE(1)

NAME

gdal_translate - Converts raster data between different formats.

SYNOPSIS

gdal_translate [--help] [--help-general] [--long-usage]
[-ot {Byte/Int8/Int16/UInt16/UInt32/Int32/UInt64/Int64/Float32/Float64/
CInt16/CInt32/CFloat32/CFloat64}] [-strict]
[-if <format>]... [-of <format>]
[-b <band>] [-mask <band>] [-expand {gray|rgb|rgba}]
[-outsize <xsize>[%]|0 <ysize>[%]|0] [-tr <xres> <yres>]
[-ovr <level>|AUTO|AUTO-<n>|NONE]
[-r {nearest,bilinear,cubic,cubicspline,lanczos,average,mode}]
[-unscale] [-scale[_bn] [<src_min> <src_max> [<dst_min> <dst_max>]]]... [-exponent[_bn] <exp_val>]...
[-srcwin <xoff> <yoff> <xsize> <ysize>] [-epo] [-eco]
[-projwin <ulx> <uly> <lrx> <lry>] [-projwin_srs <srs_def>]
[-a_srs <srs_def>] [-a_coord_epoch <epoch>]
[-a_ullr <ulx> <uly> <lrx> <lry>] [-a_nodata <value>]
[-a_gt <gt0> <gt1> <gt2> <gt3> <gt4> <gt5>]
[-a_scale <value>] [-a_offset <value>]
[-nogcp] [-gcp <pixel> <line> <easting> <northing> [<elevation>]]...
|-colorinterp{_bn} {red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...}]
|-colorinterp {red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...},...]
[-mo <META-TAG>=<VALUE>]... [-dmo "DOMAIN:META-TAG=VALUE"]... [-q] [-sds]
[-co <NAME>=<VALUE>]... [-stats] [-norat] [-noxmp]
[-oo <NAME>=<VALUE>]...
<src_dataset> <dst_dataset>

DESCRIPTION

The gdal_translate utility can be used to convert raster data between
different formats, potentially performing some operations like
subsettings, resampling, and rescaling pixels in the process.

--help Show this help message and exit

--help-general
Gives a brief usage message for the generic GDAL commandline
options and exit.

-ot <type>
Force the output image bands to have a specific data type
supported by the driver, which may be one of the following:
Byte, Int8, UInt16, Int16, UInt32, Int32, UInt64, Int64,
Float32, Float64, CInt16, CInt32, CFloat32 or CFloat64.

-strict
Don't be forgiving of mismatches and lost data when
translating to the output format.

-if <format>
Format/driver name to be attempted to open the input file(s).
It is generally not necessary to specify it, but it can be
used to skip automatic driver detection, when it fails to
select the appropriate driver. This option can be repeated
several times to specify several candidate drivers. Note that
it does not force those drivers to open the dataset. In
particular, some drivers have requirements on file extensions.

New in version 3.2.


-of <format>
Select the output format. Starting with GDAL 2.3, if not
specified, the format is guessed from the extension
(previously was GTiff). Use the short format name.

-b <band>
Select an input band band for output. Bands are numbered from
1. Multiple -b switches may be used to select a set of input
bands to write to the output file, or to reorder bands. band
can also be set to "mask,1" (or just "mask") to mean the mask
band of the first band of the input dataset.

-mask <band>
Select an input band band to create output dataset mask band.
Bands are numbered from 1. band can be set to "none" to avoid
copying the global mask of the input dataset if it exists.
Otherwise it is copied by default ("auto"), unless the mask is
an alpha channel, or if it is explicitly used to be a regular
band of the output dataset ("-b mask"). band can also be set
to "mask,1" (or just "mask") to mean the mask band of the 1st
band of the input dataset.

-expand gray|rgb|rgba
To expose a dataset with 1 band with a color table as a
dataset with 3 (RGB) or 4 (RGBA) bands. Useful for output
drivers such as JPEG, JPEG2000, MrSID, ECW that don't support
color indexed datasets. The 'gray' value enables to expand a
dataset with a color table that only contains gray levels to a
gray indexed dataset.

-outsize <xsize>[%]|0 <ysize>[%]|0
Set the size of the output file. Outsize is in pixels and
lines unless '%' is attached in which case it is as a fraction
of the input image size. If one of the 2 values is set to 0,
its value will be determined from the other one, while
maintaining the aspect ratio of the source dataset.

-tr <xres> <yres>
set target resolution. The values must be expressed in
georeferenced units. Both must be positive values. This is
mutually exclusive with -outsize, -a_ullr, and -a_gt.

-ovr {<level>|AUTO|AUTO-<n>|NONE}
New in version 3.6.


To specify which overview level of source file must be used.
The default choice, AUTO, will select the overview level whose
resolution is the closest to the target resolution. Specify an
integer value (0-based, i.e. 0=1st overview level) to select a
particular level. Specify AUTO-n where n is an integer greater
or equal to 1, to select an overview level below the AUTO one.
Or specify NONE to force the base resolution to be used (can
be useful if overviews have been generated with a low quality
resampling method, and a higher quality resampling method is
specified with -r.

When -ovr is specified to an integer value, and none of
-outsize and -tr is specified, the size of the overview will
be used as the output size.

When -ovr is specified, values of -srcwin, when specified,
should be expressed as pixel offset and size of the full
resolution source dataset. Similarly when using -outsize with
percentage values, they refer to the size of the full
resolution source dataset.

-r {nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode}
Select a resampling algorithm.

nearest (default) applies a nearest neighbour (simple
sampling) resampler

average computes the average of all non-NODATA contributing
pixels. Starting with GDAL 3.1, this is a weighted average
taking into account properly the weight of source pixels not
contributing fully to the target pixel.

rms computes the root mean squared / quadratic mean of all
non-NODATA contributing pixels (GDAL >= 3.3)

bilinear applies a bilinear convolution kernel.

cubic applies a cubic convolution kernel.

cubicspline applies a B-Spline convolution kernel.

lanczos applies a Lanczos windowed sinc convolution kernel.

mode selects the value which appears most often of all the
sampled points.

-scale [<src_min> <src_max> [<dst_min> <dst_max>]]
Rescale the input pixels values from the range src_min to
src_max to the range dst_min to dst_max. If omitted the
output range is 0 to 255. If omitted the input range is
automatically computed from the source dataset, in its whole
(not just the window of interest potentially specified with
-srcwin or -projwin). This may be a slow operation on a large
source dataset, and if using it multiple times for several
gdal_translate invocation, it might be beneficial to call
gdalinfo -stats {source_dataset} priorly to precompute
statistics, for formats that support serializing statistics
computations (GeoTIFF, VRT...) Note that the values specified
after -scale are only used to compute a scale and offset to
apply to the input raster values. In particular, src_min and
src_max are not used to clip input values unless -exponent is
also specified. Instead of being clipped, source values that
are outside the range of src_min and src_max will be scaled to
values outside the range of dst_min and dst_max. If clipping
without exponential scaling is desired, -exponent 1 can be
used. -scale can be repeated several times (if specified only
once, it also applies to all bands of the output dataset), so
as to specify per band parameters. It is also possible to use
the -scale_bn syntax where bn is a band number (e.g. -scale_2
for the 2nd band of the output dataset) to specify the
parameters of one or several specific bands.

-exponent <exp_val>
Apply non-linear scaling with a power function. exp_val is the
exponent of the power function (must be positive). This option
must be used with the -scale option. If specified only once,
-exponent applies to all bands of the output image. It can be
repeated several times so as to specify per band parameters.
It is also possible to use the -exponent_bn syntax where bn is
a band number (e.g. -exponent_2 for the 2nd band of the output
dataset) to specify the parameters of one or several specific
bands.

The scaled value Dst is calculated from the source value Src
with the following formula:

{Dst} = \left( {Dst}_{max} - {Dst}_{min} \right) \times
\operatorname{max} \left( 0, \operatorname{min} \left( 1,
\left( \frac{{Src} - {Src}_{min}}{{Src}_{max}-{Src}_{min}}
\right)^{exp\_val} \right) \right) + {Dst}_{min}


-unscale
Apply the scale/offset metadata for the bands to convert
scaled values to unscaled values. It is also often necessary
to reset the output datatype with the -ot switch. The
unscaled value is computed from the scaled raw value with the
following formula:

{unscaled\_value} = {scaled\_value} * {scale} + {offset}


-srcwin <xoff> <yoff> <xsize> <ysize>
Selects a subwindow from the source image for copying based on
pixel/line location.

-projwin <ulx> <uly> <lrx> <lry>
Selects a subwindow from the source image for copying (like
-srcwin) but with the corners given in georeferenced
coordinates (by default expressed in the SRS of the dataset.
Can be changed with -projwin_srs).

NOTE:
In GDAL 2.1.0 and 2.1.1, using -projwin with coordinates
not aligned with pixels will result in a sub-pixel shift.
This has been corrected in later versions. When selecting
non-nearest neighbour resampling, starting with GDAL 2.1.0,
sub-pixel accuracy is however used to get better results.

-projwin_srs <srs_def>
Specifies the SRS in which to interpret the coordinates given
with -projwin. The <srs_def> may be any of the usual GDAL/OGR
forms, complete WKT, PROJ.4, EPSG:n or a file containing the
WKT.

WARNING:
This does not cause reprojection of the dataset to the
specified SRS.

-epo (Error when Partially Outside) If this option is set, -srcwin
or -projwin values that falls partially outside the source
raster extent will be considered as an error. The default
behavior is to accept such requests, when they were considered
as an error before.

-eco (Error when Completely Outside) Same as -epo, except that the
criterion for erroring out is when the request falls
completely outside the source raster extent.

-a_srs <srs_def>
Override the projection for the output file. Can be used with
-a_ullr or -a_gt to specify the extent in this projection.

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.

NOTE:
No reprojection is done.

-a_coord_epoch <epoch>
New in version 3.4.


Assign a coordinate epoch, linked with the output SRS. Useful
when the output SRS is a dynamic CRS.

-a_scale <value>
Set band scaling value. No modification of pixel values is
done. Note that the -unscale does not take into account
-a_scale. You may for example specify -scale 0 1 <offset>
<offset+scale> to apply a (offset, scale) tuple, for the
equivalent of the 2 steps: gdal_translate input.tif tmp.vrt
-a_scale scale -a_offset offset followed by gdal_translate
tmp.vrt output.tif -unscale

New in version 2.3.


-a_offset <value>
Set band offset value. No modification of pixel values is
done. Note that the -unscale does not take into account
-a_offset. You may for example specify -scale 0 1 <offset>
<offset+scale> to apply a (offset, scale) tuple, for the
equivalent of the 2 steps: gdal_translate input.tif tmp.vrt
-a_scale scale -a_offset offset followed by gdal_translate
tmp.vrt output.tif -unscale

New in version 2.3.


-a_ullr <ulx> <uly> <lrx> <lry>
Assign/override the georeferenced bounds of the output file.
This assigns georeferenced bounds to the output file, ignoring
what would have been derived from the source file. So this
does not cause reprojection to the specified SRS. This is
mutually exclusive with -a_gt

-a_gt <gt(0)> <gt(1)> <gt(2)> <gt(3)> <gt(4)> <gt(5)>
Assign/override the geotransform of the output file. This
assigns the geotransform to the output file, ignoring what
would have been derived from the source file. So this does not
cause reprojection to the specified SRS. See Geotransform
Tutorial. This is mutually exclusive with -a_ullr

New in version 3.8.


-a_nodata <value>
Assign a specified nodata value to output bands. It can be set
to none to avoid setting a nodata value to the output file if
one exists for the source file. Note that, if the input
dataset has a nodata value, this does not cause pixel values
that are equal to that nodata value to be changed to the value
specified with this option.

-colorinterp_X
<red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...>
Override the color interpretation of band X (where X is a
valid band number, starting at 1)

New in version 2.3.


-colorinterp
{red|green|blue|alpha|gray|undefined|pan|coastal|rededge|nir|swir|mwir|lwir|...},...
Override the color interpretation of all specified bands. For
example -colorinterp red,green,blue,alpha for a 4 band output
dataset.

New in version 2.3.


-mo <META-TAG>=<VALUE>
Passes a metadata key and value to set on the output dataset
if possible.

-dmo DOMAIN:META-TAG=VALUE
Passes a metadata key and value in specified domain to set on
the output dataset if possible.

New in version 3.9.


-co <NAME>=<VALUE>
Many formats have one or more optional creation options that
can be used to control particulars about the file created. For
instance, the GeoTIFF driver supports creation options to
control compression, and whether the file should be tiled.

The creation options available vary by format driver, and some
simple formats have no creation options at all. A list of
options supported for a format can be listed with the
--formats command line option but the documentation for the
format is the definitive source of information on driver
creation options. See Raster drivers format specific
documentation for legal creation options for each format.

In addition to the driver-specific creation options,
gdal_translate (and GDALTranslate() and GDALCreateCopy())
recognize the following options:

+o APPEND_SUBDATASET=[YES<?>/<?>NO]: Defaults to NO.

Can be specified to YES to avoid prior destruction of
existing dataset, for drivers that support adding several
subdatasets (e.g. GTIFF, NITF)

+o COPY_SRC_MDD=[AUTO<?>/<?>YES<?>/<?>NO]: (GDAL >= 3.8)
Defaults to AUTO.

Defines if metadata domains of the source dataset should be
copied to the destination dataset. In the default AUTO
mode, only "safe" domains will be copied, which include the
default metadata domain (some drivers may include other
domains such as IMD, RPC, GEOLOCATION). When setting YES,
all domains will be copied (but a few reserved ones like
IMAGE_STRUCTURE or DERIVED_SUBDATASETS). Currently only
recognized by the GTiff, COG, VRT, PNG and JPEG drivers.

When setting NO, no source metadata will be copied.

+o SRC_MDD=<domain_name>: (GDAL >= 3.8)

Defines which source metadata domain should be copied. This
option restricts the list of source metadata domains to be
copied (it implies COPY_SRC_MDD=YES if it is not set). This
option may be specified as many times as they are source
domains. The default metadata domain is the empty string ""
("_DEFAULT_") may also be used when empty string is not
practical). Currently only recognized by the GTiff, COG,
VRT, PNG and JPEG drivers.

-nogcp Do not copy the GCPs in the source dataset to the output
dataset.

-gcp <pixel> <line> <easting> <northing> [<elevation>]
Add the indicated ground control point to the output dataset.
This option may be provided multiple times to provide a set of
GCPs.

-q Suppress progress monitor and other non-error output.

-sds Copy all subdatasets of this file to individual output files.
Use with formats like HDF that have subdatasets.

-stats Force (re)computation of statistics.

-norat Do not copy source RAT into destination dataset.

-noxmp Do not copy the XMP metadata in the source dataset to the
output dataset when driver is able to copy it.

New in version 3.2.


-oo <NAME>=<VALUE>
Dataset open option (format specific)

<src_dataset>
The source dataset name. It can be either file name, URL of
data source or subdataset name for multi-dataset files.

<dst_dataset>
The destination file name.

NODATA / SOURCE VALIDITY MASK HANDLING DURING RESAMPLING
Masked values, either identified through a nodata value metadata set
on the source band, a mask band, an alpha band will not be used
during resampling (when using -outsize or -tr).

The details of how it is taken into account depends on the resampling
kernel:

+o for nearest resampling, for each target pixel, one of the potential
contributing source pixels is selected (in an implementation
specific way). Its value is used as it, be it valid or invalid.

+o for bilinear, cubic, cubicspline and lanczos, for each target
pixel, the weights of contributing source pixels is set to zero to
ignore them when they are masked. There is an extra specificity
for cubic: given that some of the weights in the kernel are
negative, such strategy could lead to strong overshoot/undershoot
when there is an alternance of valid and invalid pixels.
Consequently, if any of the horizontal or vertical direction, if
the maximum number of valid source pixels in each dimension is less
than the radius of the resampling kernel, the target pixel is
considered as nodata.

+o for the other resampling methods, source pixels contributing to the
target pixel are ignored if masked. Only the valid ones are taken
into account. If there are none, the target pixel is considered as
nodata.

C API

This utility is also callable from C with GDALTranslate().

New in version 2.1.

EXAMPLES

gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif

To create a JPEG-compressed TIFF with internal mask from a RGBA
dataset

gdal_translate rgba.tif withmask.tif -b 1 -b 2 -b 3 -mask 4 -co COMPRESS=JPEG \
-co PHOTOMETRIC=YCBCR --config GDAL_TIFF_INTERNAL_MASK YES

To create a RGBA dataset from a RGB dataset with a mask

gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask

Subsetting using -projwin and -outsize:

gdal_translate -projwin -20037500 10037500 0 0 -outsize 100 100 frmt_wms_googlemaps_tms.xml junk.png

AUTHOR

Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer
<silke@intevation.de>

COPYRIGHT

1998-2025

January 8, 2025 GDAL_TRANSLATE(1)