Provided by: gdal-bin_3.7.1+dfsg-1build1_amd64 bug

NAME

       gdal_translate - Converts raster data between different formats.

SYNOPSIS

          gdal_translate [--help-general]
              [-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,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,  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.

              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.

       -colorinterp_X <red|green|blue|alpha|gray|undefined>
              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[,red|green|blue|alpha|gray|undefined]*>
              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.

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

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:

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

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

       • 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

AUTHOR

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

COPYRIGHT

       1998-2023

                                           Jul 06, 2023                         GDAL_TRANSLATE(1)