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/Int16/UInt16/UInt32/Int32/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
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 -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 -strict
42 Don't be forgiving of mismatches and lost data when translating
43 to the output format.
44 -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 New in version 3.2.
53 -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 -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 -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 -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 -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 -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 -r {nearest (default),bilinear,cubic,cubicspline,lanczos,aver‐
98 age,rms,mode}
99 Select a resampling algorithm.
100 nearest applies a nearest neighbour (simple sampling) resampler
102 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 rms computes the root mean squared / quadratic mean of all
109 non-NODATA contributing pixels (GDAL >= 3.3)
110 bilinear applies a bilinear convolution kernel.
112 cubic applies a cubic convolution kernel.
114 cubicspline applies a B-Spline convolution kernel.
116 lanczos applies a Lanczos windowed sinc convolution kernel.
118 mode selects the value which appears most often of all the sam‐
120 pled points.
121 -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 -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 -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 -srcwin <xoff> <yoff> <xsize> <ysize>
153 Selects a subwindow from the source image for copying based on
154 pixel/line location.
155 -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 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 -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 WARNING:
176 This does not cause reprojection of the dataset to the speci‐
177 fied SRS.
178 -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 -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 -a_srs <srs_def>
190 Override the projection for the output file.
191 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 NOTE:
200 No reprojection is done.
201 -a_coord_epoch <epoch>
203 New in version 3.4.
204 Assign a coordinate epoch, linked with the output SRS. Useful
207 when the output SRS is a dynamic CRS.
208 -a_scale <value>
210 Set band scaling value (no modification of pixel values is done)
211 New in version 2.3.
213 -a_offset<value>
216 Set band offset value (no modification of pixel values is done)
217 New in version 2.3.
219 -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 -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 -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 New in version 2.3.
240 -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 New in version 2.3.
249 -mo META-TAG=VALUE
252 Passes a metadata key and value to set on the output dataset if
253 possible.
254 -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 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 -nogcp Do not copy the GCPs in the source dataset to the output
270 dataset.
271 -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 -q Suppress progress monitor and other non-error output.
278 -sds Copy all subdatasets of this file to individual output files.
280 Use with formats like HDF that have subdatasets.
281 -stats Force (re)computation of statistics.
283 -norat Do not copy source RAT into destination dataset.
285 -noxmp Do not copy the XMP metadata in the source dataset to the output
287 dataset when driver is able to copy it.
288 New in version 3.2.
290 -oo NAME=VALUE
293 Dataset open option (format specific)
294 <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 <dst_dataset>
300 The destination file name.
301
303 This utility is also callable from C with GDALTranslate().
304 New in version 2.1.
306
309 gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif
310 To create a JPEG-compressed TIFF with internal mask from a RGBA dataset
312 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 To create a RGBA dataset from a RGB dataset with a mask
316 gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask
318
320 Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@inteva‐
321 tion.de>
322
324 1998-2022
325 May 04, 2022 GDAL_TRANSLATE(1)