GDAL-RASTER-OVERVIEW-REFRESH(1)

📦
version 3.13.3 · 4 versions
, in alpine 3.24, arch rolling, ubuntu stonking

✨ NAME ✨

gdal-raster-overview-refresh — bestie, it refreshes overviews 💅 (this is from the GDAL manual, and yes, the command literally does what it says on the tin)

Added in version 3.12. 🎀

🌸 SYNOPSIS 🌸

Usage: gdal raster overview refresh [OPTIONS] <INPUT>

Refresh 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:
  --external                         Refresh 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]
  --bbox <BBOX>                      Bounding box to refresh
                                     Mutually exclusive with --like, --use-source-timestamp
  --like <LIKE>                      Use extent of dataset(s) [may be repeated]
                                     Mutually exclusive with --bbox, --use-source-timestamp
  --use-source-timestamp             Use timestamp of VRT or GTI sources as refresh criterion
                                     Mutually exclusive with --bbox, --like

Advanced Options:
  --oo, --open-option <KEY>=<VALUE>  Open options [may be repeated]

💖 DESCRIPTION 💖

So like… gdal raster overview refresh is the glow-up command for overviews that already exist. You're not building from scratch, you're refreshing the ones that are already there in a dataset. 👑

By default it refreshes all the overviews, but bestie you have options — you can narrow it down by level and/or by extent if you only need a lil section redone. ✨

🦋 PROGRAM-SPECIFIC OPTIONS 🦋

  • --bbox <xmin>,<ymin>,<xmax>,ymax> — partial refresh time!! This redoes the existing overviews but only in the region of interest you give it, and those coords are in georeferenced coordinates, in CRS units. 'x' is longitude values for geographic CRS and easting for projected CRS. 'y' is latitude values for geographic CRS and northing for projected CRS. iykyk 💜
  • --dataset <DATASET> — the dataset name. By default it gets updated in-place (unless you say --external). Required, no skipping this one. 🫶
  • --external — refreshes the external .ovr overviews. 💅
  • --levels <level1,level2,...> — a list of overview levels to build. Each overview level must be an integer value greater or equal to 2. 🎀

If you don't specify anything, all existing overviews get refreshed.

  • --like <filename1>[,<filenameN>]... — partial refresh, but you pick the region of interest using one or several filenames (names separated by comma). Ngl, the filenames are only used to figure out the regions of interest to refresh — the reference source pixels are the one of the main dataset. 😌 By default all existing overview levels will be refreshed, unless explicit levels are specified. See Example 2. ⭐
  • -r, --resampling {nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode} — picks your resampling algorithm. Lowkey important. The default is nearest, which is generally not appropriate if sub-pixel accuracy is desired. 🚩

When refreshing existing TIFF overviews, the previously used method — as noted in the RESAMPLING metadata item of the overview — will be used if -r is not specified. 🙈

The available methods are:

  • nearest applies a nearest neighbour (simple sampling) resampler.
  • average 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.
  • bilinear applies a bilinear convolution kernel.
  • cubic applies a cubic convolution kernel.
  • cubicspline applies a B-Spline convolution kernel.
  • lanczos applies a Lanczos windowed sinc convolution kernel.
  • gauss 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.
  • average_magphase averages complex data in mag/phase space.
  • rms computes the root mean squared / quadratic mean of all non-NODATA contributing pixels
  • mode selects the value which appears most often of all the sampled points.
  • --use-source-timestamp — partial refresh, but timestamp-flavoured 🕰️. This one works on a VRT — GDAL Virtual Format — or GTI — GDAL Raster Tile Index — file that has an external overview. It checks the modification timestamp of all the sources of the VRT and regenerates the overview for areas corresponding to sources whose timestamp is more recent than the external overview of the VRT. By default all existing overview levels will be refreshed, unless explicit levels are specified. See Example 1. 🌈

👑 STANDARD OPTIONS 👑

  • --oo, --open-option <NAME>=<VALUE> — Dataset open option (format specific). 🧚

May be repeated. (so stack 'em if you need to, bestie)

🌟 RETURN STATUS CODE 🌟

It returns status code 0 in case of success, and non-zero in case of error (btw non-blocking errors emitted as warnings are considered as a successful execution — so don't panic). 💀

🍓 EXAMPLES 🍓

💜 Example 1: Refresh external overviews of a VRT file using timestamp of source files

This is needed when for sources have been modified after the .vrt.ovr generation:

gdal raster mosaic tile1.tif tile2.tif my.vrt               # create VRT
gdal raster overview add --external -r cubic my.vrt         # initial overview generation
touch tile1.tif                                             # simulate update of one of the source tiles
gdal raster overview refresh --external -r cubic \
                          --use-source-timestamp my.vrt     # refresh overviews

💜 Example 2: Refresh (internal) overviews of a TIFF file

gdal raster mosaic tile1.tif tile2.tif mosaic.tif       # create mosaic
gdal raster overview add -r cubic mosaic.tif            # initial overview generation
gdalwarp tile1_modif.tif mosaic.tif                     # update mosaic
gdal raster overview refresh --like=tile1.tif my.tif    # refresh overviews

🫶 AUTHOR 🫶

Even Rouault <even.rouault@spatialys.com> — iconic behaviour fr fr 💖

1998-2026

and that's the whole page bestie, no cap. this was GDAL's GDAL-RASTER-OVERVIEW-REFRESH(1) page, dated Aug 18, 2026 — go refresh something and slay ✨💅🦋

📦 where this page comes from