.\" Man page generated from reStructuredText. . . .nr rst2man-indent-level 0 . .de1 rstReportMargin \\$1 \\n[an-margin] level \\n[rst2man-indent-level] level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] - \\n[rst2man-indent0] \\n[rst2man-indent1] \\n[rst2man-indent2] .. .de1 INDENT .\" .rstReportMargin pre: . RS \\$1 . nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] . nr rst2man-indent-level +1 .\" .rstReportMargin post: .. .de UNINDENT . RE .\" indent \\n[an-margin] .\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] .nr rst2man-indent-level -1 .\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] .in \\n[rst2man-indent\\n[rst2man-indent-level]]u .. .TH "GDAL_TRANSLATE" "1" "Aug 13, 2024" "" "GDAL" .SH NAME gdal_translate \- Converts raster data between different formats. .SH SYNOPSIS .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gdal_translate [\-\-help] [\-\-help\-general] [\-\-long\-usage] [\-ot {Byte/Int8/Int16/UInt16/UInt32/Int32/UInt64/Int64/Float32/Float64/ CInt16/CInt32/CFloat32/CFloat64}] [\-strict] [\-if ]... [\-of ] [\-b ] [\-mask ] [\-expand {gray|rgb|rgba}] [\-outsize [%]|0 [%]|0] [\-tr ] [\-ovr |AUTO|AUTO\-|NONE] [\-r {nearest,bilinear,cubic,cubicspline,lanczos,average,mode}] [\-unscale] [\-scale[_bn] [ [ ]]]... [\-exponent[_bn] ]... [\-srcwin ] [\-epo] [\-eco] [\-projwin ] [\-projwin_srs ] [\-a_srs ] [\-a_coord_epoch ] [\-a_ullr ] [\-a_nodata ] [\-a_gt ] [\-a_scale ] [\-a_offset ] [\-nogcp] [\-gcp []]... |\-colorinterp{_bn} {red|green|blue|alpha|gray|undefined}] |\-colorinterp {red|green|blue|alpha|gray|undefined},...] [\-mo =]... [\-dmo \(dqDOMAIN:META\-TAG=VALUE\(dq]... [\-q] [\-sds] [\-co =]... [\-stats] [\-norat] [\-noxmp] [\-oo =]... .ft P .fi .UNINDENT .UNINDENT .SH DESCRIPTION .sp The \fBgdal_translate\fP utility can be used to convert raster data between different formats, potentially performing some operations like subsettings, resampling, and rescaling pixels in the process. .INDENT 0.0 .TP .B \-\-help Show this help message and exit .UNINDENT .INDENT 0.0 .TP .B \-\-help\-general Gives a brief usage message for the generic GDAL commandline options and exit. .UNINDENT .INDENT 0.0 .TP .B \-ot Force the output image bands to have a specific data type supported by the driver, which may be one of the following: \fBByte\fP, \fBInt8\fP, \fBUInt16\fP, \fBInt16\fP, \fBUInt32\fP, \fBInt32\fP, \fBUInt64\fP, \fBInt64\fP, \fBFloat32\fP, \fBFloat64\fP, \fBCInt16\fP, \fBCInt32\fP, \fBCFloat32\fP or \fBCFloat64\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-strict Don\(aqt be forgiving of mismatches and lost data when translating to the output format. .UNINDENT .INDENT 0.0 .TP .B \-if Format/driver name to be attempted to open the input file(s). It is generally not necessary to specify it, but it can be used to skip automatic driver detection, when it fails to select the appropriate driver. This option can be repeated several times to specify several candidate drivers. Note that it does not force those drivers to open the dataset. In particular, some drivers have requirements on file extensions. .sp New in version 3.2. .UNINDENT .INDENT 0.0 .TP .B \-of Select the output format. Starting with GDAL 2.3, if not specified, the format is guessed from the extension (previously was GTiff). Use the short format name. .UNINDENT .INDENT 0.0 .TP .B \-b Select an input band \fBband\fP for output. Bands are numbered from 1. Multiple \fI\%\-b\fP switches may be used to select a set of input bands to write to the output file, or to reorder bands. \fBband\fP can also be set to \(dqmask,1\(dq (or just \(dqmask\(dq) to mean the mask band of the first band of the input dataset. .UNINDENT .INDENT 0.0 .TP .B \-mask Select an input band \fBband\fP to create output dataset mask band. Bands are numbered from 1. \fBband\fP can be set to \(dqnone\(dq to avoid copying the global mask of the input dataset if it exists. Otherwise it is copied by default (\(dqauto\(dq), unless the mask is an alpha channel, or if it is explicitly used to be a regular band of the output dataset (\(dq\-b mask\(dq). \fBband\fP can also be set to \(dqmask,1\(dq (or just \(dqmask\(dq) to mean the mask band of the 1st band of the input dataset. .UNINDENT .INDENT 0.0 .TP .B \-expand gray|rgb|rgba To expose a dataset with 1 band with a color table as a dataset with 3 (RGB) or 4 (RGBA) bands. Useful for output drivers such as JPEG, JPEG2000, MrSID, ECW that don\(aqt support color indexed datasets. The \(aqgray\(aq value enables to expand a dataset with a color table that only contains gray levels to a gray indexed dataset. .UNINDENT .INDENT 0.0 .TP .B \-outsize [%]|0 [%]|0 Set the size of the output file. Outsize is in pixels and lines unless \(aq%\(aq is attached in which case it is as a fraction of the input image size. If one of the 2 values is set to 0, its value will be determined from the other one, while maintaining the aspect ratio of the source dataset. .UNINDENT .INDENT 0.0 .TP .B \-tr set target resolution. The values must be expressed in georeferenced units. Both must be positive values. This is mutually exclusive with \fI\%\-outsize\fP, \fI\%\-a_ullr\fP, and \fI\%\-a_gt\fP\&. .UNINDENT .INDENT 0.0 .TP .B \-ovr {|AUTO|AUTO\-|NONE} New in version 3.6. .sp To specify which overview level of source file must be used. The default choice, AUTO, will select the overview level whose resolution is the closest to the target resolution. Specify an integer value (0\-based, i.e. 0=1st overview level) to select a particular level. Specify AUTO\-n where n is an integer greater or equal to 1, to select an overview level below the AUTO one. Or specify NONE to force the base resolution to be used (can be useful if overviews have been generated with a low quality resampling method, and a higher quality resampling method is specified with \fI\%\-r\fP\&. .sp When \fI\%\-ovr\fP is specified to an integer value, and none of \fI\%\-outsize\fP and \fI\%\-tr\fP is specified, the size of the overview will be used as the output size. .sp When \fI\%\-ovr\fP is specified, values of \fI\%\-srcwin\fP, when specified, should be expressed as pixel offset and size of the full resolution source dataset. Similarly when using \fI\%\-outsize\fP with percentage values, they refer to the size of the full resolution source dataset. .UNINDENT .INDENT 0.0 .TP .B \-r {nearest|bilinear|cubic|cubicspline|lanczos|average|rms|mode} Select a resampling algorithm. .sp \fBnearest\fP (default) applies a nearest neighbour (simple sampling) resampler .sp \fBaverage\fP 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. .sp \fBrms\fP computes the root mean squared / quadratic mean of all non\-NODATA contributing pixels (GDAL >= 3.3) .sp \fBbilinear\fP applies a bilinear convolution kernel. .sp \fBcubic\fP applies a cubic convolution kernel. .sp \fBcubicspline\fP applies a B\-Spline convolution kernel. .sp \fBlanczos\fP applies a Lanczos windowed sinc convolution kernel. .sp \fBmode\fP selects the value which appears most often of all the sampled points. .UNINDENT .INDENT 0.0 .TP .B \-scale [ [ ]] Rescale the input pixels values from the range \fBsrc_min\fP to \fBsrc_max\fP to the range \fBdst_min\fP to \fBdst_max\fP\&. If omitted the output range is 0 to 255. If omitted the input range is automatically computed from the source dataset, in its whole (not just the window of interest potentially specified with \fI\%\-srcwin\fP or \fI\%\-projwin\fP). This may be a slow operation on a large source dataset, and if using it multiple times for several gdal_translate invocation, it might be beneficial to call \fBgdalinfo \-stats {source_dataset}\fP priorly to precompute statistics, for formats that support serializing statistics computations (GeoTIFF, VRT...) Note that the values specified after \fI\%\-scale\fP are only used to compute a scale and offset to apply to the input raster values. In particular, \fBsrc_min\fP and \fBsrc_max\fP are not used to clip input values. \fI\%\-scale\fP can be repeated several times (if specified only once, it also applies to all bands of the output dataset), so as to specify per band parameters. It is also possible to use the \(dq\-scale_bn\(dq syntax where bn is a band number (e.g. \(dq\-scale_2\(dq for the 2nd band of the output dataset) to specify the parameters of one or several specific bands. .UNINDENT .INDENT 0.0 .TP .B \-exponent To apply non\-linear scaling with a power function. exp_val is the exponent of the power function (must be positive). This option must be used with the \-scale option. If specified only once, \-exponent applies to all bands of the output image. It can be repeated several times so as to specify per band parameters. It is also possible to use the \(dq\-exponent_bn\(dq syntax where bn is a band number (e.g. \(dq\-exponent_2\(dq for the 2nd band of the output dataset) to specify the parameters of one or several specific bands. .UNINDENT .INDENT 0.0 .TP .B \-unscale Apply the scale/offset metadata for the bands to convert scaled values to unscaled values. It is also often necessary to reset the output datatype with the \fI\%\-ot\fP switch. The unscaled value is computed from the scaled raw value with the following formula: .sp .ce {unscaled\e_value} = {scaled\e_value} * {scale} + {offset} .ce 0 .UNINDENT .INDENT 0.0 .TP .B \-srcwin Selects a subwindow from the source image for copying based on pixel/line location. .UNINDENT .INDENT 0.0 .TP .B \-projwin Selects a subwindow from the source image for copying (like \fI\%\-srcwin\fP) but with the corners given in georeferenced coordinates (by default expressed in the SRS of the dataset. Can be changed with \fI\%\-projwin_srs\fP). .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 In GDAL 2.1.0 and 2.1.1, using \-projwin with coordinates not aligned with pixels will result in a sub\-pixel shift. This has been corrected in later versions. When selecting non\-nearest neighbour resampling, starting with GDAL 2.1.0, sub\-pixel accuracy is however used to get better results. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-projwin_srs Specifies the SRS in which to interpret the coordinates given with \fI\%\-projwin\fP\&. The may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or a file containing the WKT. .sp \fBWARNING:\fP .INDENT 7.0 .INDENT 3.5 This does not cause reprojection of the dataset to the specified SRS. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-epo (Error when Partially Outside) If this option is set, \fI\%\-srcwin\fP or \fI\%\-projwin\fP values that falls partially outside the source raster extent will be considered as an error. The default behavior is to accept such requests, when they were considered as an error before. .UNINDENT .INDENT 0.0 .TP .B \-eco (Error when Completely Outside) Same as \fI\%\-epo\fP, except that the criterion for erroring out is when the request falls completely outside the source raster extent. .UNINDENT .INDENT 0.0 .TP .B \-a_srs Override the projection for the output file. Can be used with \fI\%\-a_ullr\fP or \fI\%\-a_gt\fP to specify the extent in this projection. .sp The coordinate reference systems that can be passed are anything supported by the \fI\%OGRSpatialReference::SetFromUserInput()\fP call, which includes EPSG Projected, Geographic or Compound CRS (i.e. EPSG:4296), a well known text (WKT) CRS definition, PROJ.4 declarations, or the name of a .prj file containing a WKT CRS definition. .sp \fBNOTE:\fP .INDENT 7.0 .INDENT 3.5 No reprojection is done. .UNINDENT .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-a_coord_epoch New in version 3.4. .sp Assign a coordinate epoch, linked with the output SRS. Useful when the output SRS is a dynamic CRS. .UNINDENT .INDENT 0.0 .TP .B \-a_scale Set band scaling value. No modification of pixel values is done. Note that the \fI\%\-unscale\fP does not take into account \fI\%\-a_scale\fP\&. You may for example specify \fB\-scale 0 1 \fP to apply a (offset, scale) tuple, for the equivalent of the 2 steps: \fBgdal_translate input.tif tmp.vrt \-a_scale scale \-a_offset offset\fP followed by \fBgdal_translate tmp.vrt output.tif \-unscale\fP .sp New in version 2.3. .UNINDENT .INDENT 0.0 .TP .B \-a_offset Set band offset value. No modification of pixel values is done. Note that the \fI\%\-unscale\fP does not take into account \fI\%\-a_offset\fP\&. You may for example specify \fB\-scale 0 1 \fP to apply a (offset, scale) tuple, for the equivalent of the 2 steps: \fBgdal_translate input.tif tmp.vrt \-a_scale scale \-a_offset offset\fP followed by \fBgdal_translate tmp.vrt output.tif \-unscale\fP .sp New in version 2.3. .UNINDENT .INDENT 0.0 .TP .B \-a_ullr Assign/override the georeferenced bounds of the output file. This assigns georeferenced bounds to the output file, ignoring what would have been derived from the source file. So this does not cause reprojection to the specified SRS. This is mutually exclusive with \fI\%\-a_gt\fP .UNINDENT .INDENT 0.0 .TP .B \-a_gt Assign/override the geotransform of the output file. This assigns the geotransform to the output file, ignoring what would have been derived from the source file. So this does not cause reprojection to the specified SRS. See \fI\%Geotransform Tutorial\fP\&. This is mutually exclusive with \fI\%\-a_ullr\fP .sp New in version 3.8. .UNINDENT .INDENT 0.0 .TP .B \-a_nodata Assign a specified nodata value to output bands. It can be set to \fBnone\fP to avoid setting a nodata value to the output file if one exists for the source file. Note that, if the input dataset has a nodata value, this does not cause pixel values that are equal to that nodata value to be changed to the value specified with this option. .UNINDENT .INDENT 0.0 .TP .B \-colorinterp_X Override the color interpretation of band X (where X is a valid band number, starting at 1) .sp New in version 2.3. .UNINDENT .INDENT 0.0 .TP .B \-colorinterp {red|green|blue|alpha|gray|undefined},... Override the color interpretation of all specified bands. For example \-colorinterp red,green,blue,alpha for a 4 band output dataset. .sp New in version 2.3. .UNINDENT .INDENT 0.0 .TP .B \-mo = Passes a metadata key and value to set on the output dataset if possible. .UNINDENT .INDENT 0.0 .TP .B \-dmo DOMAIN:META\-TAG=VALUE Passes a metadata key and value in specified domain to set on the output dataset if possible. .sp New in version 3.9. .UNINDENT .INDENT 0.0 .TP .B \-co = Many formats have one or more optional creation options that can be used to control particulars about the file created. For instance, the GeoTIFF driver supports creation options to control compression, and whether the file should be tiled. .sp The creation options available vary by format driver, and some simple formats have no creation options at all. A list of options supported for a format can be listed with the \fI\%\-\-formats\fP command line option but the documentation for the format is the definitive source of information on driver creation options. See \fI\%Raster drivers\fP format specific documentation for legal creation options for each format. .sp In addition to the driver\-specific creation options, gdal_translate (and \fI\%GDALTranslate()\fP and \fI\%GDALCreateCopy()\fP) recognize the following options: .INDENT 7.0 .IP \(bu 2 \fBAPPEND_SUBDATASET=[YES/NO]: \fP Defaults to \fBNO\fP\&. .sp Can be specified to YES to avoid prior destruction of existing dataset, for drivers that support adding several subdatasets (e.g. GTIFF, NITF) .IP \(bu 2 \fBCOPY_SRC_MDD=[AUTO/YES/NO]: \fP (GDAL >= 3.8) Defaults to \fBAUTO\fP\&. .sp Defines if metadata domains of the source dataset should be copied to the destination dataset. In the default AUTO mode, only \(dqsafe\(dq domains will be copied, which include the default metadata domain (some drivers may include other domains such as IMD, RPC, GEOLOCATION). When setting YES, all domains will be copied (but a few reserved ones like IMAGE_STRUCTURE or DERIVED_SUBDATASETS). Currently only recognized by the GTiff, COG, VRT, PNG and JPEG drivers. .sp When setting NO, no source metadata will be copied. .IP \(bu 2 \fBSRC_MDD=: \fP (GDAL >= 3.8) .sp Defines which source metadata domain should be copied. This option restricts the list of source metadata domains to be copied (it implies COPY_SRC_MDD=YES if it is not set). This option may be specified as many times as they are source domains. The default metadata domain is the empty string \(dq\(dq (\(dq_DEFAULT_\(dq) may also be used when empty string is not practical). Currently only recognized by the GTiff, COG, VRT, PNG and JPEG drivers. .UNINDENT .UNINDENT .INDENT 0.0 .TP .B \-nogcp Do not copy the GCPs in the source dataset to the output dataset. .UNINDENT .INDENT 0.0 .TP .B \-gcp [] Add the indicated ground control point to the output dataset. This option may be provided multiple times to provide a set of GCPs. .UNINDENT .INDENT 0.0 .TP .B \-q Suppress progress monitor and other non\-error output. .UNINDENT .INDENT 0.0 .TP .B \-sds Copy all subdatasets of this file to individual output files. Use with formats like HDF that have subdatasets. .UNINDENT .INDENT 0.0 .TP .B \-stats Force (re)computation of statistics. .UNINDENT .INDENT 0.0 .TP .B \-norat Do not copy source RAT into destination dataset. .UNINDENT .INDENT 0.0 .TP .B \-noxmp Do not copy the XMP metadata in the source dataset to the output dataset when driver is able to copy it. .sp New in version 3.2. .UNINDENT .INDENT 0.0 .TP .B \-oo = Dataset open option (format specific) .UNINDENT .INDENT 0.0 .TP .B The source dataset name. It can be either file name, URL of data source or subdataset name for multi\-dataset files. .UNINDENT .INDENT 0.0 .TP .B The destination file name. .UNINDENT .SH NODATA / SOURCE VALIDITY MASK HANDLING DURING RESAMPLING .sp Masked values, either identified through a nodata value metadata set on the source band, a mask band, an alpha band will not be used during resampling (when using \fI\%\-outsize\fP or \fI\%\-tr\fP). .sp The details of how it is taken into account depends on the resampling kernel: .INDENT 0.0 .IP \(bu 2 for nearest resampling, for each target pixel, one of the potential contributing source pixels is selected (in an implementation specific way). Its value is used as it, be it valid or invalid. .IP \(bu 2 for bilinear, cubic, cubicspline and lanczos, for each target pixel, the weights of contributing source pixels is set to zero to ignore them when they are masked. There is an extra specificity for cubic: given that some of the weights in the kernel are negative, such strategy could lead to strong overshoot/undershoot when there is an alternance of valid and invalid pixels. Consequently, if any of the horizontal or vertical direction, if the maximum number of valid source pixels in each dimension is less than the radius of the resampling kernel, the target pixel is considered as nodata. .IP \(bu 2 for the other resampling methods, source pixels contributing to the target pixel are ignored if masked. Only the valid ones are taken into account. If there are none, the target pixel is considered as nodata. .UNINDENT .SH C API .sp This utility is also callable from C with \fI\%GDALTranslate()\fP\&. .sp New in version 2.1. .SH EXAMPLES .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gdal_translate \-of GTiff \-co \(dqTILED=YES\(dq utm.tif utm_tiled.tif .ft P .fi .UNINDENT .UNINDENT .sp To create a JPEG\-compressed TIFF with internal mask from a RGBA dataset .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gdal_translate rgba.tif withmask.tif \-b 1 \-b 2 \-b 3 \-mask 4 \-co COMPRESS=JPEG \e \-co PHOTOMETRIC=YCBCR \-\-config GDAL_TIFF_INTERNAL_MASK YES .ft P .fi .UNINDENT .UNINDENT .sp To create a RGBA dataset from a RGB dataset with a mask .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gdal_translate withmask.tif rgba.tif \-b 1 \-b 2 \-b 3 \-b mask .ft P .fi .UNINDENT .UNINDENT .sp Subsetting using \fI\%\-projwin\fP and \fI\%\-outsize\fP: .INDENT 0.0 .INDENT 3.5 .sp .nf .ft C gdal_translate \-projwin \-20037500 10037500 0 0 \-outsize 100 100 frmt_wms_googlemaps_tms.xml junk.png .ft P .fi .UNINDENT .UNINDENT .SH AUTHOR Frank Warmerdam , Silke Reimer .SH COPYRIGHT 1998-2024 .\" Generated by docutils manpage writer. .