Overview of GDAL_translate

According to the  official documentation, gdal_translate is used to convert raster data between different formats. This means the input to our function will always be raster data, an example being the .tif format. Although the description only mentions conversion between format, looking at the documentation shows a larger array of options:

gdal_translate [--help-general]
    [-ot {Byte/Int16/UInt16/UInt32/Int32/Float32/Float64/
            CInt16/CInt32/CFloat32/CFloat64}] [-strict]
    [-of format] [-b band]* [-mask band] [-expand {gray|rgb|rgba}]
    [-outsize xsize[%]|0 ysize[%]|0] [-tr xres yres]
    [-r {nearest,bilinear,cubic,cubicspline,lanczos,average,mode}]
    [-unscale] [-scale[_bn] [src_min src_max [dst_min dst_max]]]* [-exponent[_bn] exp_val]*
    [-srcwin xoff yoff xsize ysize] [-epo] [-eco]
    [-projwin ulx uly lrx lry] [-projwin_srs srs_def]
    [-a_srs srs_def] [-a_ullr ulx uly lrx lry] [-a_nodata value]
    [-a_scale value] [-a_offset value]
    [-nogcp] [-gcp pixel line easting northing [elevation]]*
    |-colorinterp{_bn} {red|green|blue|alpha|gray|undefined}]
    |-colorinterp {red|green|blue|alpha|gray|undefined},...]
    [-mo "META-TAG=VALUE"]* [-q] [-sds]
    [-co "NAME=VALUE"]* [-stats] [-norat]
    [-oo NAME=VALUE]*
    src_dataset dst_dataset

It is clear that gdal_translate has a wide functionality. In this article, the basic usage of gdal_translate is explained and some of the most useful options are looked at separately. By the end of the article, you'll be able to use gdal_translate to do basic raster transformations and scale, resize and convert the raster. To use the function, we'll always be using the following format:

gdal_translate OPTIONS src_dataset dst_dataset

Src_dataset refers to the input (source) file that is used. Similarly, dst_dataset is the output (destination) file we'll be creating. Some of the possible Options will be discussed separately below. For most of the examples, the same input and output file name will be reused. Our basic line of code thus becomes:

gdal_translate OPTIONS input.tif output.tif

How to run GDAL_translate

The easiest way to run GDAL functions on windows is to install the OSGeo4W(indows) Shell. Installing this program will also install the GDAL library. After installing, run the OSGeo4W shell. A command line program will open in which we can run the gdal_translate function.

Besides being able to run GDAL, the shell functions like a normal command prompt. We can use cd C:\path\to\our\directory to get to our input file directory

Changing file formats using gdal_translate

Raster images come in a wide array of extensions, including .png, .jpg etc. In geospatial images, .tif are often used according to the Geotiff standard. To change the file format the -of (Output Format) tag is used and pass it a valid output format. Besides this, we'll also change the output extension in the dst_dataset value. For the code below, I'll transfer a .jp2 file to and .tif file.

gdal_translate -of GTiff input.jp2 output.tif

Besides Geotiff, there are plenty of other possibilities:

  • -of PNG           output.png
  • -of JPEG          output.jpg
  • -of BMP           output.bmp
  • -of PDF            output.pdf

It is good practice to always declare the output file format, although for simplicity this will not be done in the examples below. If -of is not declared, gdal guesses the format based on the output extension.

Crop part of an image using Gdal_translate

The -srcwin and -projwin both allow to essentially crop a raster. The former uses and x,y-offset and amount of pixels/lines while the latter use an upper left and lower right georeferenced bound.

-srcwin (Source Window) takes four values: xoff, yoff,  xsize and ysize. Xoff and yoff define the offset from the upper left corner. Xsize and Ysize tell the function how many pixels/lines are kept (counting towards the right and bottom). To cut a 100x100 window starting from the pixel at (10,20):

gdal_translate -srcwin 10 20 100 100 input.tif output.tif

-projwin (Project Window) also cuts the raster, but is given the upperleft (ulx and uly) and lowerright (lrx and lry) coordinates to cut out (in the order as they are mentioned here). If our wanted upperleft and lower right are respectively (258460,152400) and (258600,152200):

gdal_translate -projwin 258460 152400 258600 152200 input.tif output.tif

The coordinates given to -projwin don't have to be in the same SRS as the raster image. With -projwin_srs we can define the Spatial Reference System the new bounds are given in. Note that this will not reproject the data in the output file to the given SRS. From the documentation, the value given to -projwin_srs  may be any of the usual GDAL/OGR forms, complete WKT, PROJ.4, EPSG:n or a file containing the WKT.

gdal_translate -projwin 258460 152400 258600 152200 -projwin_srs EPSG:31300 input.tif output.tif

When using -srcwin or -projwin, either the -epo(Error when Partially Outside) or -eco(Error when Completely Outside) option can be passed as well. These options don't take any parameters. These options throw an error when the new bounds as partially or completely outside the raster bounds.

gdal_translate -projwin 258460 152400 258600 152200 -eco input.tif output.tif

Reducing or increasing resolution using Gdal_translate

There are two methods (-outsize, -tr) to change the file resolution (without changing the extent). These methods are mutually exclusive, so pick just one.

With -outsize (Output Size) we can choose the amount of pixels in the x and y direction. If any of the values is set to 0, the function will calculate the the other value according the the aspect ratio of the input file. It is also possible to use the %-sign to get a percentage of the original image. The line below will scale the resolution so that in the x-direction the resolution is halved. As the aspect ratio is kept, a 0 with a resolution will use the same resolution reduction in both direction.

gdal_translate -outsize 50% 0 input.tif output.tif

By omitting the %-sign, we set an absolute number of pixels/lines. The code below will output an image with 50 pixels in both x- and y-direction. If we entered a zero for one of the two values, the amount of pixels would have been calculated according the the aspect ratio.

gdal_translate -outsize 50 50 input.tif output.tif

A second  method is to use the -tr (Target Resolution). Whereas with -outsize we set the desired amount of pixels in both direction, -tr let's us set the pixel size in georeferenced units. So in a file where the unit is meters (use gdalinfo to get this information), we can use -tr to let each pixel represent an area of 10x10m:

gdal_translate -tr 10 10 input.tif output.tif

If the amount of pixels, calculated by the functions using our -tr dimensions, does not fit a rounded amount of times in the input resolution, the output file might loose some data at the borders. The documentation mentions that this method is mutually exclusive with -a_ullr, which changes the georeferenced bounds (and scales the image such that the resolution does not change, but the pixel size does).

When changing the resolution it's also interesting to take a look at the resampling possibilities using the -r (Resampling) option. Available values are nearest (default), bilinear, cubic, cubicspline, lanczos, average, mode.

gdal_translate -tr 10 10 -r cubic input.tif output.tif

Scaling raster data using gdal_translate

It is also possible to rescale the pixel values using -scale. As example this option can be used to scale 16 bit (0 to 65535) data to 8 bit (0 to 255). The options takes 4 arguments: src_min src_max dst_min dst_max. The first two describe the input image min. and max. value and the latter the same for the output raster. If dst_min and dst_max are omitted, the values will be rescaled to the 8 bit equivalent (0 to 255). If src_min and src_max are also omitted, the function will automatically calculate the value range of the input raster.

gdal_translate -scale 0 65535 0 255 input.tif output.tif

The documentation mentions that the option can be used multiple times to apply to specific bands by using -scale_bn in which bn is the band number.

If unknown, use gdalinfo to get the min and max values of the bands. If gdalinfo does not show this image, recalculate the statistics using gdal_translate -stats and run gdalinfo on the output file.

gdal_translate -stats input.tif output.tif

Additionally, use -exponent together with -scale to set and exponential scaling. This can also be done for a specific band using -exponent_bn. The value given is the exponent (positive!) of the power function.

gdal_translate -scale 0 65535 0 255 -exponent 2 input.tif output.tif

OUTPUT Format-specific creation options in gdal_translate -co

The -co (Creation Option) command provides format-specific options, based on the format of the outputted file. For example, for the GeoTiff format we can create tiled (instead opf stripped) files and choose a compression. For each option, -co is called again. The name and value of the option are separated by an "=" sign. Note that you can not use spaces between the name and the value.

gdal_translate -co TILED=YES -co COMPRESS=DEFLATE input.tif output.tif

INPUT Format-Specfic configuration options --config and -oo

By adding the --config (Configuration) tag some more format-specific can be passed, based on the format of the input file. It is similar to -co en -oo tags and often provides similar options. For example, the PDF standard provides --config GDAL_PDF_DPI and - oo DPI options. Using these options, the resolution of a gdal_translate on a pdf can be changed (default 150):

gdal_translate -of Gtiff input.pdf output.tif --config GDAL_PDF_DPI 300

Other options

There are still some other options we do not look at it detail:

  • -ot: Output Type
  • -b: band
  • -mask: mask band
  • -expand
  • -unscale
  • The Assign options:
    • -a_srs: Assign SRS (no reprojection)
    • -a_scale: Assign scale (no modification of the pixel values)
    • -a_offset: Assign band Offset (no modification of pixel values)
    • -a_ullr: Assign UpperLeft LowerRight
    • -a_nodata: Assign's a nodata value (can also be set to none)
  • -colorinterp: Color interpretation. -colorinterp_bn with bn the band number the apply to a specific band
  • -mo: Metadata key value for the Output file
  • -gcp: Ground Control Point and -nogcp. Setting GCP's in combination with gdal_warp allows to georeference a raster by reprojecting. A GCP sets a specific coordinate to a pixel at (x,y). Gdal_warp does the reprojecting.
  • -q: surpresses progress monitor and non-error output
  • -sds: SubDataSets
  • -norat
  • -oo: Dataset Open Option