gdaladdo

Build overview images of a raster dataset using the "average" [r]esampling method

$ gdaladdo -r average [path/to/input.tif]

gdaladdo [-r {resampling_method}] [-ro] [-clean] [-b {band}] [-co {NAME=VALUE}] [-oo {NAME=VALUE}] [-q] <filename> [{LEVELS}...]

filename
    Path to the input raster dataset for which overviews will be built or updated.

LEVELS
    A space-separated list of overview levels. These are integers representing the downsampling factor (e.g., '2 4 8 16' for 1:2, 1:4, 1:8, 1:16 resolution reduction).

-r {resampling_method}
    Specifies the resampling method to use when building overviews. Common methods include:
nearest (nearest neighbour),
average (average of all contributing pixels),
cubic (cubic convolution),
gauss (gaussian kernel), etc. Choosing a method affects visual quality and processing speed.

-ro
    Read-only mode. Overviews will be written to a separate external .ovr file instead of being embedded in the input dataset. This is useful for formats that don't support internal overviews or to avoid modifying the original file.

-clean
    Removes all existing overviews from the dataset. This can be used before generating new overviews to ensure a fresh set.

-b {band}
    Selects a specific band (or bands, comma-separated) for which to build overviews. By default, overviews are built for all bands.

-co {NAME=VALUE}
    Creation options for the overview dataset (or .ovr file). These are format-specific; for example, for GeoTIFF, you might use 'TILED=YES' or 'COMPRESS=LZW'.

-oo {NAME=VALUE}
    Open options for the input dataset. These are format-specific parameters passed to the GDAL driver when opening the source file.

-q
    Quiet mode. Suppresses progress messages and other non-error output.

gdaladdo is a powerful GDAL utility designed to build or update overview images (pyramids) for raster datasets. These overviews are downsampled, lower-resolution versions of the original data, crucial for efficiently displaying large geospatial images at various zoom levels. Instead of loading the entire high-resolution dataset, mapping applications can quickly access the appropriate overview level, significantly improving display performance and responsiveness.

gdaladdo supports various resampling algorithms (e.g., nearest, average, cubic) to control how the overviews are generated, impacting visual quality and file size. Overviews can be stored internally within certain file formats (like GeoTIFF) or as external auxiliary .ovr files. This command is an essential tool for preparing large raster datasets for web mapping services, desktop GIS applications, and other data visualization tools where performance is critical.

Building overviews can be computationally intensive and may consume significant disk space, especially for large datasets or many overview levels. While gdaladdo usually modifies files in-place for formats like GeoTIFF, always ensure you have backups of critical data before running operations that modify files. Some file formats do not support internal overviews, requiring the use of the -ro option to create external .ovr files. Overviews should ideally be generated after any reprojection or significant data manipulation to ensure consistency with the base dataset.

Overviews can be stored in two primary ways:
1. Internal: Embedded directly within the main raster file (e.g., GeoTIFF). This is the default and often preferred for simplicity.
2. External: Written to a separate auxiliary file with a '.ovr' extension (e.g., 'image.tif.ovr'). This is necessary for formats that don't support internal overviews or when the original file should remain unmodified (using the -ro option). When a GIS application opens a GDAL dataset, it automatically detects and utilizes these overviews for faster display at lower resolutions.

The primary benefit of using gdaladdo is a dramatic improvement in performance when viewing large raster datasets. Without overviews, GIS software would need to resample the full-resolution data on-the-fly for every zoom level, which is slow and resource-intensive. With overviews, the software can simply load and display a pre-computed, appropriately scaled version of the data, leading to smoother navigation and quicker rendering, especially in web mapping services or desktop applications handling terabytes of imagery.

gdaladdo is an integral utility within the GDAL (Geospatial Data Abstraction Library) project, which commenced development in 1998 under the leadership of Frank Warmerdam. GDAL has since become the de facto standard library for reading and writing raster and vector geospatial data formats. gdaladdo was developed early on as a core utility to address the common challenge of efficiently visualizing large raster datasets, providing a foundational capability for performant GIS and mapping applications that handle extensive imagery.

gdal_translate(1), gdalwarp(1), gdalinfo(1), gdaldem(1)