1GDALADDO(1)                          GDAL                          GDALADDO(1)
2
3
4

NAME

6       gdaladdo - Builds or rebuilds overview images.
7

SYNOPSIS

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

DESCRIPTION

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
18       -r {nearest (default),average,rms,gauss,cubic,cubicspline,lanczos,aver‐
19       age_magphase,mode}
20              Select a resampling algorithm.
21
22              nearest applies a nearest neighbour (simple sampling) resampler
23
24              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
29              rms  computes  the  root  mean  squared  / quadratic mean of all
30              non-NODATA contributing pixels (GDAL >= 3.3)
31
32              bilinear applies a bilinear convolution kernel.
33
34              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
40              cubic applies a cubic convolution kernel.
41
42              cubicspline applies a B-Spline convolution kernel.
43
44              lanczos applies a Lanczos windowed sinc convolution kernel.
45
46              average_magphase averages complex data in mag/phase space.
47
48              mode selects the value which appears most often of all the  sam‐
49              pled points.
50
51       -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
56       -ro    open  the dataset in read-only mode, in order to generate exter‐
57              nal overview (for GeoTIFF especially).
58
59       -clean remove all overviews.
60
61       -oo NAME=VALUE
62              Dataset open option (format specific)
63
64       -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
69              New in version 2.3.
70
71
72       <filename>
73              The file to build overviews for (or whose overviews must be  re‐
74              moved).
75
76       <levels>
77              A list of integral overview levels to build. Ignored with -clean
78              option.
79
80              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
85
86       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
91       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
96       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
103       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
109       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

EXTERNAL OVERVIEWS IN GEOTIFF FORMAT

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
124       Since  GDAL   3.6,   COMPRESS_OVERVIEW   and   decl_configoption:INTER‐
125       LEAVE_OVERVIEW  are  honoured  when creating internal overviews of TIFF
126       files.
127
128       For JPEG compressed external and internal overviews, the  JPEG  quality
129       can be set with --config JPEG_QUALITY_OVERVIEW value.
130
131       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
135       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
139       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
143       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
147       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
151       For  LZW,  ZSTD or DEFLATE compressed external overviews, the predictor
152       value can be set with --config PREDICTOR_OVERVIEW 1|2|3.
153
154       To produce the smallest possible  JPEG-In-TIFF  overviews,  you  should
155       use:
156
157          --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL
158
159       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
163       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
167       • YES forces BigTIFF.
168
169       • NO forces classic TIFF.
170
171       • IF_NEEDED  will only create a BigTIFF if it is clearly needed (uncom‐
172         pressed, and overviews larger than 4GB).
173
174       • IF_SAFER will create BigTIFF if the resulting file might exceed 4GB.
175
176       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
181       See  the  documentation  of the GTiff -- GeoTIFF File Format driver for
182       further explanations on all those options.
183

SETTING BLOCKSIZE IN GEOTIFF OVERVIEWS

185       --config GDAL_TIFF_OVR_BLOCKSIZE <size>
186
187       Example: --config GDAL_TIFF_OVR_BLOCKSIZE 256
188
189       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

NODATA / SOURCE VALIDITY MASK HANDLING DURING RESAMPLING

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
200       The details of how it is taken into account depends on  the  resampling
201       kernel:
202
203       • 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
207       • 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
217       • 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

MULTITHREADING

223       New in version 3.2.
224
225
226       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

C API

231       Functionality   of   this   utility   can   be   done   from   C   with
232       GDALBuildOverviews().
233

EXAMPLES

235       Create  overviews,  embedded  in the supplied TIFF file, with automatic
236       computation of levels (GDAL 2.3 or later)
237
238          gdaladdo -r average abc.tif
239
240       Create overviews, embedded in the supplied TIFF file:
241
242          gdaladdo -r average abc.tif 2 4 8 16
243
244       Create an external compressed GeoTIFF overview file from the ERDAS .IMG
245       file:
246
247          gdaladdo -ro --config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16
248
249       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
253          gdaladdo --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR
254                   --config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16
255
256       Create an Erdas Imagine format overviews for the indicated JPEG file:
257
258          gdaladdo --config USE_RRD YES airphoto.jpg 3 9 27 81
259
260       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
265          gdaladdo GPKG:file.gpkg:layer
266

AUTHOR

268       Frank  Warmerdam  <warmerdam@pobox.com>,  Silke  Reimer  <silke@inteva‐
269       tion.de>
270
272       1998-2023
273
274
275
276
277                                 Oct 30, 2023                      GDALADDO(1)
Impressum