1GDAL_TRANSLATE(1)                    GDAL                    GDAL_TRANSLATE(1)
2
3
4

NAME

6       gdal_translate - Converts raster data between different formats.
7

SYNOPSIS

9          gdal_translate [--help-general]
10              [-ot {Byte/Int16/UInt16/UInt32/Int32/UInt64/Int64/Float32/Float64/
11                      CInt16/CInt32/CFloat32/CFloat64}] [-strict]
12              [-if format]* [-of format]
13              [-b band]* [-mask band] [-expand {gray|rgb|rgba}]
14              [-outsize xsize[%]|0 ysize[%]|0] [-tr xres yres]
15              [-r {nearest,bilinear,cubic,cubicspline,lanczos,average,rms,mode}]
16              [-unscale] [-scale[_bn] [src_min src_max [dst_min dst_max]]]* [-exponent[_bn] exp_val]*
17              [-srcwin xoff yoff xsize ysize] [-epo] [-eco]
18              [-projwin ulx uly lrx lry] [-projwin_srs srs_def]
19              [-a_srs srs_def] [-a_coord_epoch <epoch>]
20              [-a_ullr ulx uly lrx lry] [-a_nodata value]
21              [-a_scale value] [-a_offset value]
22              [-nogcp] [-gcp pixel line easting northing [elevation]]*
23              |-colorinterp{_bn} {red|green|blue|alpha|gray|undefined}]
24              |-colorinterp {red|green|blue|alpha|gray|undefined},...]
25              [-mo "META-TAG=VALUE"]* [-q] [-sds]
26              [-co "NAME=VALUE"]* [-stats] [-norat] [-noxmp]
27              [-oo NAME=VALUE]*
28              src_dataset dst_dataset
29

DESCRIPTION

31       The  gdal_translate  utility can be used to convert raster data between
32       different formats, potentially performing some operations like  subset‐
33       tings, resampling, and rescaling pixels in the process.
34
35       -ot <type>
36              Force  the  output image bands to have a specific data type sup‐
37              ported by the driver, which may be one of the  following:  Byte,
38              UInt16,  Int16, UInt32, Int32, Float32, Float64, CInt16, CInt32,
39              CFloat32 or CFloat64.
40
41       -strict
42              Don't be forgiving of mismatches and lost data when  translating
43              to the output format.
44
45       -if <format>
46              Format/driver name to be attempted to open the input file(s). It
47              is generally not necessary to specify it, but it can be used  to
48              skip automatic driver detection, when it fails to select the ap‐
49              propriate driver.  This option can be repeated several times  to
50              specify several candidate drivers.
51
52              New in version 3.2.
53
54
55       -of <format>
56              Select  the output format. Starting with GDAL 2.3, if not speci‐
57              fied, the format is guessed from the extension  (previously  was
58              GTiff). Use the short format name.
59
60       -b <band>
61              Select an input band band for output. Bands are numbered from 1.
62              Multiple -b switches may be used to select a set of input  bands
63              to  write to the output file, or to reorder bands. band can also
64              be set to "mask,1" (or just "mask") to mean the mask band of the
65              first band of the input dataset.
66
67       -mask <band>
68              Select  an  input  band band to create output dataset mask band.
69              Bands are numbered from 1. band can be set to  "none"  to  avoid
70              copying  the global mask of the input dataset if it exists. Oth‐
71              erwise it is copied by default ("auto"), unless the mask  is  an
72              alpha  channel, or if it is explicitly used to be a regular band
73              of the output dataset ("-b mask").  band  can  also  be  set  to
74              "mask,1"  (or just "mask") to mean the mask band of the 1st band
75              of the input dataset.
76
77       -expand gray|rgb|rgba
78              To expose a dataset with 1 band with a color table as a  dataset
79              with  3  (RGB) or 4 (RGBA) bands. Useful for output drivers such
80              as JPEG, JPEG2000, MrSID, ECW that don't support  color  indexed
81              datasets.  The  'gray'  value enables to expand a dataset with a
82              color table that only contains gray levels  to  a  gray  indexed
83              dataset.
84
85       -outsize <xsize>[%]|0 <ysize>[%]|0
86              Set the size of the output file.  Outsize is in pixels and lines
87              unless '%' is attached in which case it is as a fraction of  the
88              input image size.  If one of the 2 values is set to 0, its value
89              will be determined from the other one, while maintaining the as‐
90              pect ratio of the source dataset.
91
92       -tr <xres> <yres>
93              set target resolution. The values must be expressed in georefer‐
94              enced units.  Both must be positive values. This is mutually ex‐
95              clusive with -outsize and -a_ullr.
96
97       -r      {nearest     (default),bilinear,cubic,cubicspline,lanczos,aver‐
98       age,rms,mode}
99              Select a resampling algorithm.
100
101              nearest applies a nearest neighbour (simple sampling) resampler
102
103              average computes the average of all non-NODATA contributing pix‐
104              els.  Starting  with GDAL 3.1, this is a weighted average taking
105              into account properly the weight of source pixels not contribut‐
106              ing fully to the target pixel.
107
108              rms  computes  the  root  mean  squared  / quadratic mean of all
109              non-NODATA contributing pixels (GDAL >= 3.3)
110
111              bilinear applies a bilinear convolution kernel.
112
113              cubic applies a cubic convolution kernel.
114
115              cubicspline applies a B-Spline convolution kernel.
116
117              lanczos applies a Lanczos windowed sinc convolution kernel.
118
119              mode selects the value which appears most often of all the  sam‐
120              pled points.
121
122       -scale [src_min src_max [dst_min dst_max]]
123              Rescale  the  input  pixels  values  from  the  range src_min to
124              src_max to the range dst_min to dst_max. If omitted  the  output
125              range  is 0 to 255.  If omitted the input range is automatically
126              computed from the source data. Note that these values  are  only
127              used  to compute a scale and offset to apply to the input raster
128              values. In particular, src_min and src_max are not used to  clip
129              input  values.   -scale can be repeated several times (if speci‐
130              fied only once, it also applies  to  all  bands  of  the  output
131              dataset),  so as to specify per band parameters. It is also pos‐
132              sible to use the "-scale_bn" syntax where bn is  a  band  number
133              (e.g.  "-scale_2"  for  the  2nd  band of the output dataset) to
134              specify the parameters of one or several specific bands.
135
136       -exponent <exp_val>
137              To apply non-linear scaling with a power  function.  exp_val  is
138              the  exponent of the power function (must be positive). This op‐
139              tion must be used with the  -scale  option.  If  specified  only
140              once, -exponent applies to all bands of the output image. It can
141              be repeated several times so as to specify per band  parameters.
142              It is also possible to use the "-exponent_bn" syntax where bn is
143              a band number (e.g. "-exponent_2" for the 2nd band of the output
144              dataset)  to  specify  the parameters of one or several specific
145              bands.
146
147       -unscale
148              Apply the scale/offset metadata for the bands to convert  scaled
149              values  to unscaled values.  It is also often necessary to reset
150              the output datatype with the -ot switch.
151
152       -srcwin <xoff> <yoff> <xsize> <ysize>
153              Selects a subwindow from the source image for copying  based  on
154              pixel/line location.
155
156       -projwin <ulx> <uly> <lrx> <lry>
157              Selects  a  subwindow  from  the  source image for copying (like
158              -srcwin) but with the corners given in georeferenced coordinates
159              (by  default expressed in the SRS of the dataset. Can be changed
160              with -projwin_srs).
161
162              NOTE:
163                 In GDAL 2.1.0 and 2.1.1, using -projwin with coordinates  not
164                 aligned  with  pixels  will result in a sub-pixel shift. This
165                 has  been  corrected  in  later  versions.   When   selecting
166                 non-nearest  neighbour  resampling, starting with GDAL 2.1.0,
167                 sub-pixel accuracy is however used to get better results.
168
169       -projwin_srs <srs_def>
170              Specifies the SRS in which to interpret  the  coordinates  given
171              with  -projwin.  The  <srs_def> may be any of the usual GDAL/OGR
172              forms, complete WKT, PROJ.4, EPSG:n or  a  file  containing  the
173              WKT.
174
175              WARNING:
176                 This does not cause reprojection of the dataset to the speci‐
177                 fied SRS.
178
179       -epo   (Error when Partially Outside) If this option is set, -srcwin or
180              -projwin  values  that falls partially outside the source raster
181              extent will be considered as an error. The default  behavior  is
182              to  accept  such requests, when they were considered as an error
183              before.
184
185       -eco   (Error when Completely Outside) Same as -epo,  except  that  the
186              criterion  for erroring out is when the request falls completely
187              outside the source raster extent.
188
189       -a_srs <srs_def>
190              Override the projection for the output file.
191
192              The coordinate reference systems that can be passed are anything
193              supported  by  the  OGRSpatialReference.SetFromUserInput() call,
194              which includes EPSG Projected, Geographic or Compound CRS  (i.e.
195              EPSG:4296),  a well known text (WKT) CRS definition, PROJ.4 dec‐
196              larations, or the name of a .prj file containing a WKT CRS defi‐
197              nition.
198
199              NOTE:
200                 No reprojection is done.
201
202       -a_coord_epoch <epoch>
203              New in version 3.4.
204
205
206              Assign  a  coordinate  epoch, linked with the output SRS. Useful
207              when the output SRS is a dynamic CRS.
208
209       -a_scale <value>
210              Set band scaling value (no modification of pixel values is done)
211
212              New in version 2.3.
213
214
215       -a_offset<value>
216              Set band offset value (no modification of pixel values is done)
217
218              New in version 2.3.
219
220
221       -a_ullr <ulx> <uly> <lrx> <lry>
222              Assign/override the georeferenced bounds  of  the  output  file.
223              This  assigns  georeferenced bounds to the output file, ignoring
224              what would have been derived from the source file. So this  does
225              not cause reprojection to the specified SRS.
226
227       -a_nodata <value>
228              Assign  a  specified nodata value to output bands. It can be set
229              to none to avoid setting a nodata value to the  output  file  if
230              one  exists for the source file. Note that, if the input dataset
231              has a nodata value, this does not cause pixel  values  that  are
232              equal  to that nodata value to be changed to the value specified
233              with this option.
234
235       -colorinterp_X <red|green|blue|alpha|gray|undefined>
236              Override the color interpretation of band X (where X is a  valid
237              band number, starting at 1)
238
239              New in version 2.3.
240
241
242       -colorinterp   <red|green|blue|alpha|gray|undefined[,red|green|blue|al‐
243       pha|gray|undefined]*>
244              Override the color interpretation of all  specified  bands.  For
245              example  -colorinterp  red,green,blue,alpha  for a 4 band output
246              dataset.
247
248              New in version 2.3.
249
250
251       -mo META-TAG=VALUE
252              Passes a metadata key and value to set on the output dataset  if
253              possible.
254
255       -co <NAME=VALUE>
256              Many formats have one or more optional creation options that can
257              be used to control particulars about the file created.  For  in‐
258              stance,  the GeoTIFF driver supports creation options to control
259              compression, and whether the file should be tiled.
260
261              The creation options available vary by format driver,  and  some
262              simple  formats  have  no creation options at all. A list of op‐
263              tions supported for a format can be listed  with  the  --formats
264              command  line option but the documentation for the format is the
265              definitive source of information  on  driver  creation  options.
266              See  Raster drivers format specific documentation for legal cre‐
267              ation options for each format.
268
269       -nogcp Do not copy the  GCPs  in  the  source  dataset  to  the  output
270              dataset.
271
272       -gcp <pixel> <line> <easting> <northing> <elevation>
273              Add  the  indicated  ground control point to the output dataset.
274              This option may be provided multiple times to provide a  set  of
275              GCPs.
276
277       -q     Suppress progress monitor and other non-error output.
278
279       -sds   Copy  all  subdatasets  of this file to individual output files.
280              Use with formats like HDF that have subdatasets.
281
282       -stats Force (re)computation of statistics.
283
284       -norat Do not copy source RAT into destination dataset.
285
286       -noxmp Do not copy the XMP metadata in the source dataset to the output
287              dataset when driver is able to copy it.
288
289              New in version 3.2.
290
291
292       -oo NAME=VALUE
293              Dataset open option (format specific)
294
295       <src_dataset>
296              The source dataset name. It can be either file name, URL of data
297              source or subdataset name for multi-dataset files.
298
299       <dst_dataset>
300              The destination file name.
301

C API

303       This utility is also callable from C with GDALTranslate().
304
305       New in version 2.1.
306
307

EXAMPLES

309          gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif
310
311       To create a JPEG-compressed TIFF with internal mask from a RGBA dataset
312
313          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
314
315       To create a RGBA dataset from a RGB dataset with a mask
316
317          gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask
318

AUTHOR

320       Frank  Warmerdam  <warmerdam@pobox.com>,  Silke  Reimer  <silke@inteva‐
321       tion.de>
322
324       1998-2022
325
326
327
328
329                                 Sep 02, 2022                GDAL_TRANSLATE(1)
Impressum