1GDALADDO(1) GDAL GDALADDO(1)
2
6 gdaladdo - Builds or rebuilds overview images.
7
9 gdaladdo [-r {nearest,average,rms,bilinear,gauss,cubic,cubicspline,lanczos,average_magphase,mode}]
10 [-b band]* [-minsize val]
11 [-ro] [-clean] [-oo NAME=VALUE]* [--help-general] filename [levels]
12
14 The gdaladdo utility can be used to build or rebuild overview images
15 for most supported file formats with one of several downsampling algo‐
16 rithms.
17 -r {nearest (default),average,rms,gauss,cubic,cubicspline,lanczos,aver‐
19 age_magphase,mode}
20 Select a resampling algorithm.
21 nearest applies a nearest neighbour (simple sampling) resampler
23 average computes the average of all non-NODATA contributing pix‐
25 els. Starting with GDAL 3.1, this is a weighted average taking
26 into account properly the weight of source pixels not contribut‐
27 ing fully to the target pixel.
28 rms computes the root mean squared / quadratic mean of all
30 non-NODATA contributing pixels (GDAL >= 3.3)
31 bilinear applies a bilinear convolution kernel.
33 gauss applies a Gaussian kernel before computing the overview,
35 which can lead to better results than simple averaging in e.g
36 case of sharp edges with high contrast or noisy patterns. The
37 advised level values should be 2, 4, 8, ... so that a 3x3 re‐
38 sampling Gaussian kernel is selected.
39 cubic applies a cubic convolution kernel.
41 cubicspline applies a B-Spline convolution kernel.
43 lanczos applies a Lanczos windowed sinc convolution kernel.
45 average_magphase averages complex data in mag/phase space.
47 mode selects the value which appears most often of all the sam‐
49 pled points.
50 -b <band>
52 Select an input band band for overview generation. Band number‐
53 ing starts from 1. Multiple -b switches may be used to select a
54 set of input bands to generate overviews.
55 -ro open the dataset in read-only mode, in order to generate exter‐
57 nal overview (for GeoTIFF especially).
58 -clean remove all overviews.
60 -oo NAME=VALUE
62 Dataset open option (format specific)
63 -minsize <val>
65 Maximum width or height of the smallest overview level. Only
66 taken into account if explicit levels are not specified. De‐
67 faults to 256.
68 New in version 2.3.
70 <filename>
73 The file to build overviews for (or whose overviews must be re‐
74 moved).
75 <levels>
77 A list of integral overview levels to build. Ignored with -clean
78 option.
79 New in version 2.3: levels are no longer required to build over‐
81 views. In which case, appropriate overview power-of-two factors
82 will be selected until the smallest overview is smaller than the
83 value of the -minsize switch.
84 gdaladdo will honour properly NODATA_VALUES tuples (special dataset
87 metadata) so that only a given RGB triplet (in case of a RGB image)
88 will be considered as the nodata value and not each value of the trip‐
89 let independently per band.
90 Selecting a level value like 2 causes an overview level that is 1/2 the
92 resolution (in each dimension) of the base layer to be computed. If
93 the file has existing overview levels at a level selected, those levels
94 will be recomputed and rewritten in place.
95 For internal GeoTIFF overviews (or external overviews in GeoTIFF for‐
97 mat), note that -clean does not shrink the file. A later run of gdal‐
98 addo with overview levels will cause the file to be expanded, rather
99 than reusing the space of the previously deleted overviews. If you just
100 want to change the resampling method on a file that already has over‐
101 views computed, you don't need to clean the existing overviews.
102 Some format drivers do not support overviews at all. Many format driv‐
104 ers store overviews in a secondary file with the extension .ovr that is
105 actually in TIFF format. By default, the GeoTIFF driver stores over‐
106 views internally to the file operated on (if it is writable), unless
107 the -ro flag is specified.
108 Most drivers also support an alternate overview format using Erdas
110 Imagine format. To trigger this use the USE_RRD =YES configuration op‐
111 tion. This will place the overviews in an associated .aux file suit‐
112 able for direct use with Imagine or ArcGIS as well as GDAL applica‐
113 tions. (e.g. --config USE_RRD YES)
114
116 External overviews created in TIFF format may be compressed using the
117 COMPRESS_OVERVIEW configuration option. All compression methods, sup‐
118 ported by the GeoTIFF driver, are available here. (e.g. --config COM‐
119 PRESS_OVERVIEW DEFLATE). The photometric interpretation can be set
120 with the PHOTOMETRIC_OVERVIEW =RGB/YCBCR/... configuration option, and
121 the interleaving with the INTERLEAVE_OVERVIEW =PIXEL/BAND configuration
122 option.
123 Since GDAL 3.6, COMPRESS_OVERVIEW and decl_configoption:INTER‐
125 LEAVE_OVERVIEW are honoured when creating internal overviews of TIFF
126 files.
127 For JPEG compressed external and internal overviews, the JPEG quality
129 can be set with --config JPEG_QUALITY_OVERVIEW value.
130 For WEBP compressed external and internal overviews, the WEBP quality
132 level can be set with --config WEBP_LEVEL_OVERVIEW value. If not set,
133 will default to 75.
134 For WEBP compressed external and internal overviews, the WEBP loss‐
136 less/lossy switch can be set with --config WEBP_LOSSLESS_OVERVIEW
137 value. If not set, will default to NO (lossy). Added in GDAL 3.6.0
138 For LERC compressed external and internal overviews, the max error
140 threshold can be set with --config MAX_Z_ERROR_OVERVIEW value. If not
141 set, will default to 0 (lossless). Added in GDAL 3.4.1
142 For DEFLATE or LERC_DEFLATE compressed external and internal overviews,
144 the compression level can be set with --config ZLEVEL_OVERVIEW value.
145 If not set, will default to 6. Added in GDAL 3.4.1
146 For ZSTD or LERC_ZSTD compressed external and internal overviews, the
148 compression level can be set with --config ZSTD_LEVEL_OVERVIEW value.
149 If not set, will default to 9. Added in GDAL 3.4.1
150 For LZW, ZSTD or DEFLATE compressed external overviews, the predictor
152 value can be set with --config PREDICTOR_OVERVIEW 1|2|3.
153 To produce the smallest possible JPEG-In-TIFF overviews, you should
155 use:
156 --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL
158 External overviews can be created in the BigTIFF format by using the
160 BIGTIFF_OVERVIEW configuration option: --config BIGTIFF_OVERVIEW
161 {IF_NEEDED|IF_SAFER|YES|NO}.
162 The default value is IF_SAFER starting with GDAL 2.3.0 (previously was
164 IF_NEEDED). The behavior of this option is exactly the same as the
165 BIGTIFF creation option documented in the GeoTIFF driver documentation.
166 • YES forces BigTIFF.
168 • NO forces classic TIFF.
170 • IF_NEEDED will only create a BigTIFF if it is clearly needed (uncom‐
172 pressed, and overviews larger than 4GB).
173 • IF_SAFER will create BigTIFF if the resulting file might exceed 4GB.
175 Sparse GeoTIFF overview files (that is tiles which are omitted if all
177 their pixels are at the nodata value, when there's one, or at 0 other‐
178 wise) can be obtained with --config SPARSE_OK_OVERVIEW ON. Added in
179 GDAL 3.4.1
180 See the documentation of the GTiff -- GeoTIFF File Format driver for
182 further explanations on all those options.
183
185 --config GDAL_TIFF_OVR_BLOCKSIZE <size>
186 Example: --config GDAL_TIFF_OVR_BLOCKSIZE 256
188 Default value is 128, or starting with GDAL 3.1, if creating overviews
190 on a tiled GeoTIFF file, the tile size of the full resolution image.
191 Note: without this setting, the file can have the full resolution image
192 with a blocksize different from overviews blocksize.(e.g. full resolu‐
193 tion image at blocksize 256, overviews at blocksize 128)
194
196 Invalid values in source pixels, either identified through a nodata
197 value metadata set on the source band, a mask band, an alpha band will
198 not be used during resampling.
199 The details of how it is taken into account depends on the resampling
201 kernel:
202 • for nearest resampling, for each target pixel, one of the potential
204 contributing source pixels is selected (in an implementation specific
205 way). Its value is used as it, be it valid or invalid.
206 • for bilinear, cubic, cubicspline and lanczos, for each target pixel,
208 the weights of contributing source pixels is set to zero to ignore
209 them when they are masked. There is an extra specificity for cubic:
210 given that some of the weights in the kernel are negative, such
211 strategy could lead to strong overshoot/undershoot when there is an
212 alternance of valid and invalid pixels. Consequently, if any of the
213 horizontal or vertical direction, if the maximum number of valid
214 source pixels in each dimension is less than the radius of the resam‐
215 pling kernel, the target pixel is considered as nodata.
216 • for the other resampling methods, source pixels contributing to the
218 target pixel are ignored if masked. Only the valid ones are taken
219 into account. If there are none, the target pixel is considered as
220 nodata.
221
223 New in version 3.2.
224 The GDAL_NUM_THREADS configuration option can be set to ALL_CPUS or a
227 integer value to specify the number of threads to use for overview com‐
228 putation.
229
231 Functionality of this utility can be done from C with
232 GDALBuildOverviews().
233
235 Create overviews, embedded in the supplied TIFF file, with automatic
236 computation of levels (GDAL 2.3 or later)
237 gdaladdo -r average abc.tif
239 Create overviews, embedded in the supplied TIFF file:
241 gdaladdo -r average abc.tif 2 4 8 16
243 Create an external compressed GeoTIFF overview file from the ERDAS .IMG
245 file:
246 gdaladdo -ro --config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16
248 Create an external JPEG-compressed GeoTIFF overview file from a 3-band
250 RGB dataset (if the dataset is a writable GeoTIFF, you also need to add
251 the -ro option to force the generation of external overview):
252 gdaladdo --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR
254 --config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16
255 Create an Erdas Imagine format overviews for the indicated JPEG file:
257 gdaladdo --config USE_RRD YES airphoto.jpg 3 9 27 81
259 Create overviews for a specific subdataset, like for example one of po‐
261 tentially many raster layers in a GeoPackage (the "filename" parameter
262 must be driver prefix, filename and subdataset name, like e.g. shown by
263 gdalinfo):
264 gdaladdo GPKG:file.gpkg:layer
266
268 Frank Warmerdam <warmerdam@pobox.com>, Silke Reimer <silke@inteva‐
269 tion.de>
270
272 1998-2023
273 Oct 30, 2023 GDALADDO(1)