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       For JPEG compressed external and internal overviews, the  JPEG  quality
125       can be set with --config JPEG_QUALITY_OVERVIEW value.
126
127       For  WEBP  compressed external and internal overviews, the WEBP quality
128       level can be set with --config WEBP_LEVEL_OVERVIEW value. If  not  set,
129       will default to 75.
130
131       For  LERC  compressed  external  and  internal overviews, the max error
132       threshold can be set with --config MAX_Z_ERROR_OVERVIEW value.  If  not
133       set, will default to 0 (lossless). Added in GDAL 3.4.1
134
135       For DEFLATE or LERC_DEFLATE compressed external and internal overviews,
136       the compression level can be set with --config  ZLEVEL_OVERVIEW  value.
137       If not set, will default to 6. Added in GDAL 3.4.1
138
139       For  ZSTD  or LERC_ZSTD compressed external and internal overviews, the
140       compression level can be set with --config  ZSTD_LEVEL_OVERVIEW  value.
141       If not set, will default to 9. Added in GDAL 3.4.1
142
143       For  LZW,  ZSTD or DEFLATE compressed external overviews, the predictor
144       value can be set with --config PREDICTOR_OVERVIEW 1|2|3.
145
146       To produce the smallest possible  JPEG-In-TIFF  overviews,  you  should
147       use:
148
149          --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR --config INTERLEAVE_OVERVIEW PIXEL
150
151       External  overviews  can  be created in the BigTIFF format by using the
152       BIGTIFF_OVERVIEW  configuration   option:   --config   BIGTIFF_OVERVIEW
153       {IF_NEEDED|IF_SAFER|YES|NO}.
154
155       The  default value is IF_SAFER starting with GDAL 2.3.0 (previously was
156       IF_NEEDED).  The behavior of this option is exactly  the  same  as  the
157       BIGTIFF creation option documented in the GeoTIFF driver documentation.
158
159       • YES forces BigTIFF.
160
161       • NO forces classic TIFF.
162
163       • IF_NEEDED  will only create a BigTIFF if it is clearly needed (uncom‐
164         pressed, and overviews larger than 4GB).
165
166       • IF_SAFER will create BigTIFF if the resulting file might exceed 4GB.
167
168       Sparse GeoTIFF overview files (that is tiles which are omitted  if  all
169       their  pixels are at the nodata value, when there's one, or at 0 other‐
170       wise) can be obtained with --config  SPARSE_OK_OVERVIEW  ON.  Added  in
171       GDAL 3.4.1
172
173       See  the  documentation  of the GTiff -- GeoTIFF File Format driver for
174       further explanations on all those options.
175

SETTING BLOCKSIZE IN GEOTIFF OVERVIEWS

177       --config GDAL_TIFF_OVR_BLOCKSIZE <size>
178
179       Example: --config GDAL_TIFF_OVR_BLOCKSIZE 256
180
181       Default value is 128, or starting with GDAL 3.1, if creating  overviews
182       on  a  tiled  GeoTIFF file, the tile size of the full resolution image.
183       Note: without this setting, the file can have the full resolution image
184       with  a blocksize different from overviews blocksize.(e.g. full resolu‐
185       tion image at blocksize 256, overviews at blocksize 128)
186

MULTITHREADING

188       New in version 3.2.
189
190
191       The GDAL_NUM_THREADS configuration option can be set to ALL_CPUS  or  a
192       integer value to specify the number of threads to use for overview com‐
193       putation.
194

C API

196       Functionality   of   this   utility   can   be   done   from   C   with
197       GDALBuildOverviews().
198

EXAMPLES

200       Create  overviews,  embedded  in the supplied TIFF file, with automatic
201       computation of levels (GDAL 2.3 or later)
202
203          gdaladdo -r average abc.tif
204
205       Create overviews, embedded in the supplied TIFF file:
206
207          gdaladdo -r average abc.tif 2 4 8 16
208
209       Create an external compressed GeoTIFF overview file from the ERDAS .IMG
210       file:
211
212          gdaladdo -ro --config COMPRESS_OVERVIEW DEFLATE erdas.img 2 4 8 16
213
214       Create  an external JPEG-compressed GeoTIFF overview file from a 3-band
215       RGB dataset (if the dataset is a writable GeoTIFF, you also need to add
216       the -ro option to force the generation of external overview):
217
218          gdaladdo --config COMPRESS_OVERVIEW JPEG --config PHOTOMETRIC_OVERVIEW YCBCR
219                   --config INTERLEAVE_OVERVIEW PIXEL rgb_dataset.ext 2 4 8 16
220
221       Create an Erdas Imagine format overviews for the indicated JPEG file:
222
223          gdaladdo --config USE_RRD YES airphoto.jpg 3 9 27 81
224
225       Create overviews for a specific subdataset, like for example one of po‐
226       tentially many raster layers in a GeoPackage (the "filename"  parameter
227       must be driver prefix, filename and subdataset name, like e.g. shown by
228       gdalinfo):
229
230          gdaladdo GPKG:file.gpkg:layer
231

AUTHOR

233       Frank  Warmerdam  <warmerdam@pobox.com>,  Silke  Reimer  <silke@inteva‐
234       tion.de>
235
237       1998-2022
238
239
240
241
242                                 Sep 02, 2022                      GDALADDO(1)
Impressum