1GDAL_TRANSLATE(1) GDAL GDAL_TRANSLATE(1)
2
6 gdal_translate - Converts raster data between different formats.
7
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
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 -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 -strict
43 Don't be forgiving of mismatches and lost data when translating
44 to the output format.
45 -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 New in version 3.2.
54 -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 -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 -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 -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 -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 -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 -ovr <level|AUTO|AUTO-n|NONE>
99 New in version 3.6.
100 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 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 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 -r {nearest (default),bilinear,cubic,cubicspline,lanczos,aver‐
124 age,rms,mode}
125 Select a resampling algorithm.
126 nearest applies a nearest neighbour (simple sampling) resampler
128 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 rms computes the root mean squared / quadratic mean of all
135 non-NODATA contributing pixels (GDAL >= 3.3)
136 bilinear applies a bilinear convolution kernel.
138 cubic applies a cubic convolution kernel.
140 cubicspline applies a B-Spline convolution kernel.
142 lanczos applies a Lanczos windowed sinc convolution kernel.
144 mode selects the value which appears most often of all the sam‐
146 pled points.
147 -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 -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 -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 {unscaled\_value} = {scaled\_value} * {scale} + {offset}
187 -srcwin <xoff> <yoff> <xsize> <ysize>
191 Selects a subwindow from the source image for copying based on
192 pixel/line location.
193 -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 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 -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 WARNING:
214 This does not cause reprojection of the dataset to the speci‐
215 fied SRS.
216 -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 -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 -a_srs <srs_def>
228 Override the projection for the output file.
229 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 NOTE:
238 No reprojection is done.
239 -a_coord_epoch <epoch>
241 New in version 3.4.
242 Assign a coordinate epoch, linked with the output SRS. Useful
245 when the output SRS is a dynamic CRS.
246 -a_scale <value>
248 Set band scaling value (no modification of pixel values is done)
249 New in version 2.3.
251 -a_offset<value>
254 Set band offset value (no modification of pixel values is done)
255 New in version 2.3.
257 -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 -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 -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 New in version 2.3.
278 -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 New in version 2.3.
287 -mo META-TAG=VALUE
290 Passes a metadata key and value to set on the output dataset if
291 possible.
292 -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 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 -nogcp Do not copy the GCPs in the source dataset to the output
308 dataset.
309 -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 -q Suppress progress monitor and other non-error output.
316 -sds Copy all subdatasets of this file to individual output files.
318 Use with formats like HDF that have subdatasets.
319 -stats Force (re)computation of statistics.
321 -norat Do not copy source RAT into destination dataset.
323 -noxmp Do not copy the XMP metadata in the source dataset to the output
325 dataset when driver is able to copy it.
326 New in version 3.2.
328 -oo NAME=VALUE
331 Dataset open option (format specific)
332 <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 <dst_dataset>
338 The destination file name.
339
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 The details of how it is taken into account depends on the resampling
346 kernel:
347 • 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 • 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 • 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
368 This utility is also callable from C with GDALTranslate().
369 New in version 2.1.
371
374 gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif
375 To create a JPEG-compressed TIFF with internal mask from a RGBA dataset
377 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 To create a RGBA dataset from a RGB dataset with a mask
381 gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask
383
385 Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@inteva‐
386 tion.de>
387
389 1998-2023
390 Oct 30, 2023 GDAL_TRANSLATE(1)