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/Int8/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              [-ovr level|AUTO|AUTO-n|NONE]
16              [-r {nearest,bilinear,cubic,cubicspline,lanczos,average,rms,mode}]
17              [-unscale] [-scale[_bn] [src_min src_max [dst_min dst_max]]]* [-exponent[_bn] exp_val]*
18              [-srcwin xoff yoff xsize ysize] [-epo] [-eco]
19              [-projwin ulx uly lrx lry] [-projwin_srs srs_def]
20              [-a_srs srs_def] [-a_coord_epoch <epoch>]
21              [-a_ullr ulx uly lrx lry] [-a_nodata value]
22              [-a_scale value] [-a_offset value]
23              [-nogcp] [-gcp pixel line easting northing [elevation]]*
24              |-colorinterp{_bn} {red|green|blue|alpha|gray|undefined}]
25              |-colorinterp {red|green|blue|alpha|gray|undefined},...]
26              [-mo "META-TAG=VALUE"]* [-q] [-sds]
27              [-co "NAME=VALUE"]* [-stats] [-norat] [-noxmp]
28              [-oo NAME=VALUE]*
29              src_dataset dst_dataset
30

DESCRIPTION

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

NODATA / SOURCE VALIDITY MASK HANDLING DURING RESAMPLING

341       Masked values, either identified through a nodata value metadata set on
342       the source band, a mask band, an alpha band will not be used during re‐
343       sampling (when using -outsize or -tr).
344
345       The  details  of how it is taken into account depends on the resampling
346       kernel:
347
348       • for nearest resampling, for each target pixel, one of  the  potential
349         contributing source pixels is selected (in an implementation specific
350         way). Its value is used as it, be it valid or invalid.
351
352       • for bilinear, cubic, cubicspline and lanczos, for each target  pixel,
353         the  weights  of  contributing source pixels is set to zero to ignore
354         them when they are masked.  There is an extra specificity for  cubic:
355         given  that  some  of  the  weights  in the kernel are negative, such
356         strategy could lead to strong overshoot/undershoot when there  is  an
357         alternance  of  valid and invalid pixels. Consequently, if any of the
358         horizontal or vertical direction, if  the  maximum  number  of  valid
359         source pixels in each dimension is less than the radius of the resam‐
360         pling kernel, the target pixel is considered as nodata.
361
362       • for the other resampling methods, source pixels contributing  to  the
363         target  pixel  are  ignored  if masked. Only the valid ones are taken
364         into account. If there are none, the target pixel  is  considered  as
365         nodata.
366

C API

368       This utility is also callable from C with GDALTranslate().
369
370       New in version 2.1.
371
372

EXAMPLES

374          gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif
375
376       To create a JPEG-compressed TIFF with internal mask from a RGBA dataset
377
378          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
379
380       To create a RGBA dataset from a RGB dataset with a mask
381
382          gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask
383

AUTHOR

385       Frank  Warmerdam  <warmerdam@pobox.com>,  Silke  Reimer  <silke@inteva‐
386       tion.de>
387
389       1998-2023
390
391
392
393
394                                 Oct 30, 2023                GDAL_TRANSLATE(1)
Impressum