1.. _gdal_translate: 2 3================================================================================ 4gdal_translate 5================================================================================ 6 7.. only:: html 8 9 Converts raster data between different formats. 10 11.. Index:: gdal_translate 12 13Synopsis 14-------- 15 16.. code-block:: 17 18 19 gdal_translate [--help-general] 20 [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/ 21 CInt16/CInt32/CFloat32/CFloat64}] [-strict] 22 [-if format]* [-of format] 23 [-b band]* [-mask band] [-expand {gray|rgb|rgba}] 24 [-outsize xsize[%]|0 ysize[%]|0] [-tr xres yres] 25 [-r {nearest,bilinear,cubic,cubicspline,lanczos,average,rms,mode}] 26 [-unscale] [-scale[_bn] [src_min src_max [dst_min dst_max]]]* [-exponent[_bn] exp_val]* 27 [-srcwin xoff yoff xsize ysize] [-epo] [-eco] 28 [-projwin ulx uly lrx lry] [-projwin_srs srs_def] 29 [-a_srs srs_def] [-a_ullr ulx uly lrx lry] [-a_nodata value] 30 [-a_scale value] [-a_offset value] 31 [-nogcp] [-gcp pixel line easting northing [elevation]]* 32 |-colorinterp{_bn} {red|green|blue|alpha|gray|undefined}] 33 |-colorinterp {red|green|blue|alpha|gray|undefined},...] 34 [-mo "META-TAG=VALUE"]* [-q] [-sds] 35 [-co "NAME=VALUE"]* [-stats] [-norat] [-noxmp] 36 [-oo NAME=VALUE]* 37 src_dataset dst_dataset 38 39Description 40----------- 41 42The :program:`gdal_translate` utility can be used to convert raster data between 43different formats, potentially performing some operations like subsettings, 44resampling, and rescaling pixels in the process. 45 46.. program:: gdal_translate 47 48.. include:: options/ot.rst 49 50.. option:: -strict 51 52 Don't be forgiving of mismatches and lost data when translating to the 53 output format. 54 55.. include:: options/if.rst 56 57.. include:: options/of.rst 58 59.. option:: -b <band> 60 61 Select an input band **band** for output. Bands are numbered from 1. 62 Multiple :option:`-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 be set 64 to "mask,1" (or just "mask") to mean the mask band of the first band of the 65 input dataset. 66 67.. option:: -mask <band> 68 69 Select an input band **band** to create output dataset mask band. Bands are 70 numbered from 1. **band** can be set to "none" to avoid copying the global 71 mask of the input dataset if it exists. Otherwise it is copied by default 72 ("auto"), unless the mask is an alpha channel, or if it is explicitly used 73 to be a regular band of the output dataset ("-b mask"). **band** can also 74 be set to "mask,1" (or just "mask") to mean the mask band of the 1st band 75 of the input dataset. 76 77.. option:: -expand gray|rgb|rgba 78 79 To expose a dataset with 1 band with a color table as a dataset with 80 3 (RGB) or 4 (RGBA) bands. Useful for output drivers such as JPEG, 81 JPEG2000, MrSID, ECW that don't support color indexed datasets. The 'gray' 82 value enables to expand a dataset with a color table that only contains 83 gray levels to a gray indexed dataset. 84 85.. option:: -outsize <xsize>[%]|0 <ysize>[%]|0 86 87 Set the size of the output file. Outsize is in pixels and lines unless '%' 88 is attached in which case it is as a fraction of the input image size. 89 If one of the 2 values is set to 0, its value will be determined from the 90 other one, while maintaining the aspect ratio of the source dataset. 91 92.. option:: -tr <xres> <yres> 93 94 set target resolution. The values must be expressed in georeferenced units. 95 Both must be positive values. This is mutually exclusive with 96 :option:`-outsize` and :option:`-a_ullr`. 97 98.. option:: -r {nearest (default),bilinear,cubic,cubicspline,lanczos,average,rms,mode} 99 100 Select a resampling algorithm. 101 102 ``nearest`` applies a nearest neighbour (simple sampling) resampler 103 104 ``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. 105 106 ``rms`` computes the root mean squared / quadratic mean of all non-NODATA contributing pixels (GDAL >= 3.3) 107 108 ``bilinear`` applies a bilinear convolution kernel. 109 110 ``cubic`` applies a cubic convolution kernel. 111 112 ``cubicspline`` applies a B-Spline convolution kernel. 113 114 ``lanczos`` applies a Lanczos windowed sinc convolution kernel. 115 116 ``mode`` selects the value which appears most often of all the sampled points. 117 118.. option:: -scale [src_min src_max [dst_min dst_max]] 119 120 Rescale the input pixels values from the range **src_min** to **src_max** 121 to the range **dst_min** to **dst_max**. If omitted the output range is 0 122 to 255. If omitted the input range is automatically computed from the 123 source data. Note that these values are only used to compute a scale and 124 offset to apply to the input raster values. In particular, src_min and 125 src_max are not used to clip input values. 126 -scale can be repeated several times (if specified only once, 127 it also applies to all bands of the output dataset), so as to specify per 128 band parameters. It is also possible to use the "-scale_bn" syntax where bn 129 is a band number (e.g. "-scale_2" for the 2nd band of the output dataset) 130 to specify the parameters of one or several specific bands. 131 132.. option:: -exponent <exp_val> 133 134 To apply non-linear scaling with a power function. exp_val is the exponent 135 of the power function (must be positive). This option must be used with the 136 -scale option. If specified only once, -exponent applies to all bands of 137 the output image. It can be repeated several times so as to specify per 138 band parameters. It is also possible to use the "-exponent_bn" syntax where 139 bn is a band number (e.g. "-exponent_2" for the 2nd band of the output 140 dataset) to specify the parameters of one or several specific bands. 141 142.. option:: -unscale 143 144 Apply the scale/offset metadata for the bands to convert scaled values to 145 unscaled values. It is also often necessary to reset the output datatype 146 with the :option:`-ot` switch. 147 148.. option:: -srcwin <xoff> <yoff> <xsize> <ysize> 149 150 Selects a subwindow from the source image for copying based on pixel/line location. 151 152.. option:: -projwin <ulx> <uly> <lrx> <lry> 153 154 Selects a subwindow from the source image for copying 155 (like :option:`-srcwin`) but with the corners given in georeferenced 156 coordinates (by default expressed in the SRS of the dataset. Can be 157 changed with :option:`-projwin_srs`). 158 159 .. note:: 160 161 In GDAL 2.1.0 and 2.1.1, using -projwin with coordinates not aligned 162 with pixels will result in a sub-pixel shift. This has been corrected 163 in later versions. When selecting non-nearest neighbour resampling, 164 starting with GDAL 2.1.0, sub-pixel accuracy is however used to get 165 better results. 166 167.. option:: -projwin_srs <srs_def> 168 169 Specifies the SRS in which to interpret the coordinates given with 170 :option:`-projwin`. The <srs_def> may be any of the usual GDAL/OGR forms, 171 complete WKT, PROJ.4, EPSG:n or a file containing the WKT. 172 173 .. warning:: 174 This does not cause reprojection of the dataset to the specified SRS. 175 176.. option:: -epo 177 178 (Error when Partially Outside) If this option is set, :option:`-srcwin` or 179 :option:`-projwin` values that falls partially outside the source raster 180 extent will be considered as an error. The default behavior is to accept 181 such requests, when they were considered as an error before. 182 183.. option:: -eco 184 185 (Error when Completely Outside) Same as :option:`-epo`, except that the 186 criterion for erroring out is when the request falls completely outside 187 the source raster extent. 188 189.. option:: -a_srs <srs_def> 190 191 Override the projection for the output file. 192 193 .. include:: options/srs_def.rst 194 195 .. note:: No reprojection is done. 196 197.. option:: -a_scale <value> 198 199 Set band scaling value (no modification of pixel values is done) 200 201 .. versionadded:: 2.3 202 203.. option:: -a_offset<value> 204 205 Set band offset value (no modification of pixel values is done) 206 207 .. versionadded:: 2.3 208 209.. option:: -a_ullr <ulx> <uly> <lrx> <lry> 210 211 Assign/override the georeferenced bounds of the output file. This assigns 212 georeferenced bounds to the output file, ignoring what would have been 213 derived from the source file. So this does not cause reprojection to the 214 specified SRS. 215 216.. option:: -a_nodata <value> 217 218 Assign a specified nodata value to output bands. It can 219 be set to <i>none</i> to avoid setting a nodata value to the output file if 220 one exists for the source file. Note that, if the input dataset has a 221 nodata value, this does not cause pixel values that are equal to that nodata 222 value to be changed to the value specified with this option. 223 224.. option:: -colorinterp_X <red|green|blue|alpha|gray|undefined> 225 226 Override the color interpretation of band X (where X is a valid band number, 227 starting at 1) 228 229 .. versionadded:: 2.3 230 231.. option:: -colorinterp <red|green|blue|alpha|gray|undefined[,red|green|blue|alpha|gray|undefined]*> 232 233 Override the color interpretation of all specified bands. For 234 example -colorinterp red,green,blue,alpha for a 4 band output dataset. 235 236 .. versionadded:: 2.3 237 238.. option:: -mo META-TAG=VALUE 239 240 Passes a metadata key and value to set on the output dataset if possible. 241 242.. include:: options/co.rst 243 244.. option:: -nogcp 245 246 Do not copy the GCPs in the source dataset to the output dataset. 247 248.. option:: -gcp <pixel> <line> <easting> <northing> <elevation> 249 250 Add the indicated ground control point to the output dataset. This option 251 may be provided multiple times to provide a set of GCPs. 252 253.. option:: -q 254 255 Suppress progress monitor and other non-error output. 256 257.. option:: -sds 258 259 Copy all subdatasets of this file to individual output files. Use with 260 formats like HDF that have subdatasets. 261 262.. option:: -stats 263 264 Force (re)computation of statistics. 265 266.. option:: -norat 267 268 Do not copy source RAT into destination dataset. 269 270.. option:: -noxmp 271 272 Do not copy the XMP metadata in the source dataset to the output dataset when driver is able to copy it. 273 274 .. versionadded:: 3.2 275 276.. option:: -oo NAME=VALUE 277 278 Dataset open option (format specific) 279 280.. option:: <src_dataset> 281 282 The source dataset name. It can be either file name, URL of data source or 283 subdataset name for multi-dataset files. 284 285.. option:: <dst_dataset> 286 287 The destination file name. 288 289C API 290----- 291 292This utility is also callable from C with :cpp:func:`GDALTranslate`. 293 294.. versionadded:: 2.1 295 296Examples 297-------- 298 299:: 300 301 gdal_translate -of GTiff -co "TILED=YES" utm.tif utm_tiled.tif 302 303 304To create a JPEG-compressed TIFF with internal mask from a RGBA dataset 305 306:: 307 308 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 309 310 311To create a RGBA dataset from a RGB dataset with a mask 312 313:: 314 315 gdal_translate withmask.tif rgba.tif -b 1 -b 2 -b 3 -b mask 316 317