Ubuntu Manpage: gdal_translate - Converts raster data between different formats.

Provided by: gdal-bin_3.6.2+dfsg-1build1_amd64

NAME

       gdal_translate - Converts raster data between different formats.

SYNOPSIS

          gdal_translate [--help-general]
              [-ot {Byte/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,rms,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_scale value] [-a_offset value]
              [-nogcp] [-gcp pixel line easting northing [elevation]]*
              |-colorinterp{_bn} {red|green|blue|alpha|gray|undefined}]
              |-colorinterp {red|green|blue|alpha|gray|undefined},...]
              [-mo "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.

-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, UInt16, Int16, UInt32, Int32, 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.

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

-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 (default),bilinear,cubic,cubicspline,lanczos,average,rms,mode}
Select a resampling algorithm.

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

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

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)

New in version 2.3.

-a_offset<value>
Set band offset value (no modification of pixel values is done)

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.

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

New in version 2.3.

New in version 2.3.

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

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

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

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

AUTHOR

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

COPYRIGHT

       1998-2023

                                           Jan 02, 2023                         GDAL_TRANSLATE(1)