.\" Man page generated from reStructuredText.
.
.
.nr rst2man-indent-level 0
.
.de1 rstReportMargin
\\$1 \\n[an-margin]
level \\n[rst2man-indent-level]
level margin: \\n[rst2man-indent\\n[rst2man-indent-level]]
-
\\n[rst2man-indent0]
\\n[rst2man-indent1]
\\n[rst2man-indent2]
..
.de1 INDENT
.\" .rstReportMargin pre:
. RS \\$1
. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin]
. nr rst2man-indent-level +1
.\" .rstReportMargin post:
..
.de UNINDENT
. RE
.\" indent \\n[an-margin]
.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]]
.nr rst2man-indent-level -1
.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]]
.in \\n[rst2man-indent\\n[rst2man-indent-level]]u
..
.TH "GDAL-RASTER-OVERVIEW-ADD" "1" "Aug 18, 2026" "" "GDAL"
.SH NAME
gdal-raster-overview-add \- Add overviews to a raster dataset
.sp
Added in version 3.11.

.SH SYNOPSIS
.INDENT 0.0
.INDENT 3.5
.sp
.EX
Usage: gdal raster overview add [OPTIONS] <INPUT>

Adding overviews.

Positional arguments:
  \-i, \-\-dataset, \-\-input <INPUT>         Dataset (to be updated in\-place, unless \-\-external) [required]

Common Options:
  \-h, \-\-help                             Display help message and exit
  \-\-json\-usage                           Display usage as JSON document and exit
  \-\-config <KEY>=<VALUE>                 Configuration option [may be repeated]
  \-q, \-\-quiet                            Quiet mode (no progress bar or warning message) [not available in pipelines]

Options:
  \-\-overview\-src <OVERVIEW\-SRC>          Source overview dataset [may be repeated]
                                         Mutually exclusive with \-\-levels
  \-\-external                             Add external overviews
  \-r, \-\-resampling <RESAMPLING>          Resampling method. RESAMPLING=nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode
  \-\-levels <LEVELS>                      Levels / decimation factors [may be repeated]
                                         Mutually exclusive with \-\-overview\-src
  \-\-min\-size <MIN\-SIZE>                  Maximum width or height of the smallest overview level.
  \-\-co, \-\-creation\-option <KEY>=<VALUE>  Overview creation option [may be repeated]

Advanced Options:
  \-\-oo, \-\-open\-option <KEY>=<VALUE>      Open options [may be repeated]
.EE
.UNINDENT
.UNINDENT
.SH DESCRIPTION
.sp
\fBgdal raster overview add\fP can be used to build or rebuild overview images for
most supported file formats with one of several downsampling algorithms.
.sp
Starting with GDAL 3.12, \fBgdal raster overview add\fP can be used as a
step of a pipeline. In that case virtual overviews are generated at the output
of the step, and can potentially be materialized in the final write step, when
writing a GeoTIFF file with the COPY_SRC_OVERVIEWS creation option, or when writing
to a COG (Cloud Optimized GeoTIFF) file.
.SH PROGRAM-SPECIFIC OPTIONS
.INDENT 0.0
.TP
.B \-\-co <NAME>=<VALUE>
Added in version 3.12.

.sp
Overview creation options. May be repeated.
.sp
Many formats have one or more optional creation options that can be
used to control particulars about the created overviews. Options available
can be obtained by looking at the \fBOverviewCreationOptionList\fP returned
by \fBgdal \-\-format <FORMAT\-NAME>\fP\&.
.sp
Most formats will support external overviews in a GeoTIFF file in a
side\-car file of extension \fB\&.ovr\fP\&. You can consult the
\fI\%overview creation options for GeoTIFF\fP\&.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-dataset <DATASET>
Dataset name, to be updated in\-place by default (unless \fI\%\-\-external\fP is specified).
Required for standalone execution, implicit when run as a pipeline step
.UNINDENT
.INDENT 0.0
.TP
.B \-\-external
Create external \fB\&.ovr\fP overviews as GeoTIFF files.
Not available when run as a pipeline step.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-levels <level1,level2,...>
A list of overview levels to build. Each overview level must be an integer
value greater or equal to 2.
.sp
When explicit levels are not specified,
.INDENT 7.0
.IP \(bu 2
If there are already existing overviews, the corresponding levels will be
used to refresh them if no explicit levels are specified.
.IP \(bu 2
Otherwise, appropriate overview power\-of\-two factors will be selected
until the smallest overview is smaller than the value of the
\fI\%\-\-min\-size\fP switch.
.UNINDENT
.sp
Mutually exclusive with \fI\%\-\-overview\-src\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-\-min\-size <val>
Maximum width or height of the smallest overview level. Only taken into
account if explicit levels are not specified. Defaults to 256.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-overview\-src <INPUT>
Added in version 3.12.

.sp
Add specified input raster datasets as overviews of the target dataset.
Source overviews may come from any GDAL supported format, provided they
have the same number of bands and geospatial extent than the target
dataset.
.sp
That mode is currently only implemented when the target dataset is in
GeoTIFF format, or when using \fI\%\-\-external\fP\&.
.sp
Mutually exclusive with \fI\%\-\-levels\fP
.UNINDENT
.INDENT 0.0
.TP
.B \-r, \-\-resampling {nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode}
Select a resampling algorithm. The default is \fBnearest\fP, which is generally not
appropriate if sub\-pixel accuracy is desired.
.sp
When refreshing existing TIFF overviews, the previously
used method, as noted in the RESAMPLING metadata item of the overview, will
be used if \fI\%\-r\fP is not specified.
.sp
The available methods are:
.sp
\fBnearest\fP applies a nearest neighbour (simple sampling) resampler.
.sp
\fBaverage\fP computes the average of all non\-NODATA contributing pixels. This is a weighted average taking into account properly the weight of source pixels not contributing fully to the target pixel.
.sp
\fBbilinear\fP applies a bilinear convolution kernel.
.sp
\fBcubic\fP applies a cubic convolution kernel.
.sp
\fBcubicspline\fP applies a B\-Spline convolution kernel.
.sp
\fBlanczos\fP applies a Lanczos windowed sinc convolution kernel.
.sp
\fBgauss\fP 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.
.sp
\fBaverage_magphase\fP averages complex data in mag/phase space.
.sp
\fBrms\fP computes the root mean squared / quadratic mean of all non\-NODATA contributing pixels
.sp
\fBmode\fP selects the value which appears most often of all the sampled points.
.UNINDENT
.SH STANDARD OPTIONS
.INDENT 0.0
.TP
.B \-\-co, \-\-creation\-option <NAME>=<VALUE>
Many formats have one or more optional creation options that can be
used to control particulars about the file created. For instance,
the GeoTIFF driver supports creation options to control compression,
and whether the file should be tiled.
.sp
May be repeated.
.sp
The creation options available vary by format driver, and some
simple formats have no creation options at all. A list of options
supported for a format can be listed with the
\fI\%\-\-formats\fP
command line option but the documentation for the format is the
definitive source of information on driver creation options.
See \fI\%Raster drivers\fP format
specific documentation for legal creation options for each format.
.UNINDENT
.INDENT 0.0
.TP
.B \-\-oo, \-\-open\-option <NAME>=<VALUE>
Dataset open option (format specific).
.sp
May be repeated.
.UNINDENT
.SH RETURN STATUS CODE
.sp
The program returns status code 0 in case of success, and non\-zero in case of
error (non\-blocking errors emitted as warnings are considered as a successful
execution).
.SH EXAMPLES
.SS Example 1: Create overviews, embedded in the supplied TIFF file, with automatic computation of levels
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster overview add \-r average abc.tif
.EE
.UNINDENT
.UNINDENT
.SS Example 2: Create overviews, embedded in the supplied TIFF file
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster overview add \-r average \-\-levels=2,4,8,16 abc.tif
.EE
.UNINDENT
.UNINDENT
.SS Example 3: Create an external compressed GeoTIFF overview file from the ERDAS .IMG file
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster overview add \-\-external \-\-levels=2,4,8,16 \-\-co COMPRESS=YES erdas.img
.EE
.UNINDENT
.UNINDENT
.SS Example 4: Create an external JPEG\-compressed GeoTIFF overview file from a 3\-band RGB dataset
.sp
If the dataset is a writable GeoTIFF, you also need to add the \fI\%\-\-external\fP option to
force the generation of external overview.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster overview add \-\-co OVERVIEW=JPEG \-\-co PHOTOMETRIC=YCBCR \e
                         \-\-co INTERLEAVE=PIXEL rgb_dataset.ext 2 4 8 16
.EE
.UNINDENT
.UNINDENT
.SS Example 5: Create overviews for a specific subdataset
.sp
For example, one of potentially many raster layers in a GeoPackage (the \(dqfilename\(dq parameter must be driver prefix, filename and subdataset name, like e.g. shown by gdalinfo):
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster overview add GPKG:file.gpkg:layer
.EE
.UNINDENT
.UNINDENT
.SS Example 6: Add 3 existing datasets at scale 1:25K, 1:50K and 1:100K as overviews of my.tif.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal raster overview add \-\-overview\-src ovr_25k.tif \-\-overview\-src ovr_50k.tif \-\-overview\-src ovr_100k.tif \-\-dataset my.tif
.EE
.UNINDENT
.UNINDENT
.SS Example 7: Create a COG file with non power\-of\-two overview levels.
.INDENT 0.0
.INDENT 3.5
.sp
.EX
gdal pipeline read input.tif ! reproject \-\-output\-crs=EPSG:4326 ! add overview \-\-levels 16,64,128 ! write output.tif \-\-format=COG
.EE
.UNINDENT
.UNINDENT
.SH AUTHOR
Even Rouault <even.rouault@spatialys.com>
.SH COPYRIGHT
1998-2026
.\" Generated by docutils manpage writer.
.