Skip to content
Snippets Groups Projects
gdaladdo.1 7.38 KiB
Newer Older
.TH "gdaladdo" 1 "Fri Sep 21 2018" "GDAL" \" -*- nroff -*-
gdaladdo \- Builds or rebuilds overview images\&.
.SH "SYNOPSIS"
.PP
.PP
.nf
gdaladdo [-r {nearest,average,gauss,cubic,cubicspline,lanczos,average_mp,average_magphase,mode}]
         [-b band]* [-minsize val]
         [-ro] [-clean] [-oo NAME=VALUE]* [--help-general] filename [levels]
.fi
.PP
.SH "DESCRIPTION"
.PP
The gdaladdo utility can be used to build or rebuild overview images for most supported file formats with one of several downsampling algorithms\&.
.IP "\fB\fB-r\fP \fI{nearest (default),average,gauss,cubic,cubicspline,lanczos,average_mp,average_magphase,mode}\fP:\fP" 1c
Select a resampling algorithm\&. 
.IP "\fB\fB-b\fP \fIband\fP:\fP" 1c
(available from GDAL 1\&.10) Select an input band \fIband\fP for overview generation\&. Band numbering starts from 1\&. Multiple \fB-b\fP switches may be used to select a set of input bands to generate overviews\&. 
.IP "\fB\fB-ro\fP:\fP" 1c
(available from GDAL 1\&.6\&.0) open the dataset in read-only mode, in order to generate external overview (for GeoTIFF especially)\&.  
.IP "\fB\fB-clean\fP:\fP" 1c
(available from GDAL 1\&.7\&.0) remove all overviews\&.  
.IP "\fB\fB-oo\fP \fINAME=VALUE\fP:\fP" 1c
(starting with GDAL 2\&.0) Dataset open option (format specific) 
.IP "\fB\fB-minsize\fP \fIval\fP:\fP" 1c
(starting with GDAL 2\&.3) Maximum width or height of the smallest overview level\&. Only taken into account if explicit levels are not specified\&. Defaults to 256\&.  
.IP "\fB\fIfilename\fP:\fP" 1c
The file to build overviews for (or whose overviews must be removed)\&.  
.IP "\fB\fIlevels\fP:\fP" 1c
A list of integral overview levels to build\&. Ignored with -clean option\&. Starting with GDAL 2\&.3, levels are no longer required to build overviews\&. In which case, appropriate overview power-of-two factors will be selected until the smallest overview is smaller than the value of the -minsize switch\&. 
\fIMode\fP (available from GDAL 1\&.6\&.0) selects the value which appears most often of all the sampled points\&. \fIaverage_mp\fP is unsuitable for use\&. \fIAverage_magphase\fP averages complex data in mag/phase space\&. \fINearest\fP and \fIaverage\fP are applicable to normal image data\&. \fINearest\fP applies a nearest neighbour (simple sampling) resampler, while \fIaverage\fP computes the average of all non-NODATA contributing pixels\&. \fICubic\fP resampling (available from GDAL 1\&.7\&.0) applies a cubic convolution kernel\&. \fIGauss\fP resampling (available from GDAL 1\&.6\&.0) applies a Gaussian kernel before computing the overview, which can lead to better results than simple averaging in e\&.g case of sharp edges with high contrast or noisy patterns\&. The advised level values should be 2, 4, 8, \&.\&.\&. so that a 3x3 resampling Gaussian kernel is selected\&. \fICubicSpline\fP resampling (available from GDAL 2\&.0) applies a B-Spline convolution kernel\&. \fILanczos\fP resampling (available from GDAL 2\&.0) applies a Lanczos windowed sinc convolution kernel\&.
gdaladdo will honour properly NODATA_VALUES tuples (special dataset metadata) so that only a given RGB triplet (in case of a RGB image) will be considered as the nodata value and not each value of the triplet independently per band\&.
Selecting a level value like \fI2\fP causes an overview level that is 1/2 the resolution (in each dimension) of the base layer to be computed\&. If the file has existing overview levels at a level selected, those levels will be recomputed and rewritten in place\&.
For internal GeoTIFF overviews (or external overviews in GeoTIFF format), note that -clean does not shrink the file\&. A later run of gdaladdo with overview levels will cause the file to be expanded, rather than reusing the space of the previously deleted overviews\&. If you just want to change the resampling method on a file that already has overviews computed, you don't need to clean the existing overviews\&.
Some format drivers do not support overviews at all\&. Many format drivers store overviews in a secondary file with the extension \&.ovr that is actually in TIFF format\&. By default, the GeoTIFF driver stores overviews internally to the file operated on (if it is writable), unless the -ro flag is specified\&.
Most drivers also support an alternate overview format using Erdas Imagine format\&. To trigger this use the USE_RRD=YES configuration option\&. This will place the overviews in an associated \&.aux file suitable for direct use with Imagine or ArcGIS as well as GDAL applications\&. (e\&.g\&. --config USE_RRD YES)
.SH "External overviews in GeoTIFF format"
.PP
External overviews created in TIFF format may be compressed using the COMPRESS_OVERVIEW configuration option\&. All compression methods, supported by the GeoTIFF driver, are available here\&. (e\&.g\&. --config COMPRESS_OVERVIEW DEFLATE)\&. The photometric interpretation can be set with --config PHOTOMETRIC_OVERVIEW {RGB,YCBCR,\&.\&.\&.}, and the interleaving with --config INTERLEAVE_OVERVIEW {PIXEL|BAND}\&.
For JPEG compressed external overviews, the JPEG quality can be set with '--config JPEG_QUALITY_OVERVIEW value' (GDAL 1\&.7\&.0 or later)\&.
For LZW or DEFLATE compressed external overviews, the predictor value can be set with '--config PREDICTOR_OVERVIEW 1|2|3' (GDAL 1\&.8\&.0 or later)\&.
.PP
To produce the smallest possible JPEG-In-TIFF overviews, you should use : 
.PP
.nf
--config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL

.fi
.PP
.PP
External overviews can be created in the BigTIFF format by using the BIGTIFF_OVERVIEW configuration option : --config BIGTIFF_OVERVIEW {IF_NEEDED|IF_SAFER|YES|NO}\&. The default value is IF_SAFER starting with GDAL 2\&.3\&.0 (previously was IF_NEEDED)\&. The behaviour of this option is exactly the same as the BIGTIFF creation option documented in the GeoTIFF driver documentation\&. 
YES forces BigTIFF\&. 
NO forces classic TIFF\&. 
IF_NEEDED will only create a BigTIFF if it is clearly needed (uncompressed, and overviews larger than 4GB)\&. 
IF_SAFER will create BigTIFF if the resulting file \fImight\fP exceed 4GB\&. 
See the documentation of the GeoTIFF driver for further explanations on all those options\&.
.SH "C API"
.PP
Functionality of this utility can be done from C with GDALBuildOverviews()\&.
Create overviews, embedded in the supplied TIFF file, with automatic computation of levels (GDAL 2\&.3 or later)
.PP
.PP
.nf
gdaladdo -r average abc.tif
.fi
.PP
.PP
Create overviews, embedded in the supplied TIFF file:
.PP
.PP
.nf
gdaladdo -r average abc.tif 2 4 8 16
.fi
.PP
.PP
Create an external compressed GeoTIFF overview file from the ERDAS \&.IMG file:
.PP
.PP
.nf
gdaladdo -ro --config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16
.fi
.PP
.PP
Create an external JPEG-compressed GeoTIFF overview file from a 3-band RGB dataset (if the dataset is a writable GeoTIFF, you also need to add the -ro option to force the generation of external overview):
.PP
.PP
.nf
gdaladdo --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR
         --config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16
.fi
.PP
.PP
Create an Erdas Imagine format overviews for the indicated JPEG file:
.PP
.PP
.nf
gdaladdo --config USE_RRD YES airphoto.jpg 3 9 27 81
.fi
.PP
.SH "AUTHORS"
.PP
Frank Warmerdam warmerdam@pobox.com, Silke Reimer silke@intevation.de