GDAL-RASTER-OVERVIEW-REFRESH(1) GDAL GDAL-RASTER-OVERVIEW-REFRESH(1)
gdal-raster-overview-refresh - Refresh overviews
Added in version 3.12.
Usage: gdal raster overview refresh [OPTIONS] <DATASET>
Refresh overviews.
Positional arguments:
--dataset <DATASET> 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)
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]
gdal raster overview refresh can be used to refresh existing
overviews of a dataset. By default all overviews are refreshed, but
it is also possible to restrict the refreshed overviews by level
and/or extent.
--dataset <DATASET>
Dataset name, to be updated in-place by default (unless
--external is specified). Required.
--external
Refresh external .ovr overviews.
--resampling
{nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode}
Select a resampling algorithm. 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.
--levels <level1,level2,...>
A list of overview levels to build. Each overview level must
be an integer value greater or equal to 2.
If not specified all existing overviews are refreshed.
--bbox <xmin>,<ymin>,<xmax>,ymax>
This option performs a partial refresh of existing overviews,
in the region of interest specified by 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.
--like <filename1>[,<filenameN>]...
This option performs a partial refresh of existing overviews,
in the region of interest specified by one or several
filenames (names separated by comma). Note that the filenames
are only used to determine 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.
--use-source-timestamp
This option performs a partial refresh of existing overviews
of a VRT -- GDAL Virtual Format or GTI -- GDAL Raster Tile
Index file with an external overview. It checks the
modification timestamp of all the sources of the VRT and
regenerate 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.
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
Even Rouault <even.rouault@spatialys.com>
1998-2026
March 20, 2026
GDAL-RASTER-OVERVIEW-REFRESH(1)
NAME
gdal-raster-overview-refresh - Refresh overviews
Added in version 3.12.
SYNOPSIS
Usage: gdal raster overview refresh [OPTIONS] <DATASET>
Refresh overviews.
Positional arguments:
--dataset <DATASET> 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)
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
gdal raster overview refresh can be used to refresh existing
overviews of a dataset. By default all overviews are refreshed, but
it is also possible to restrict the refreshed overviews by level
and/or extent.
--dataset <DATASET>
Dataset name, to be updated in-place by default (unless
--external is specified). Required.
--external
Refresh external .ovr overviews.
--resampling
{nearest|average|cubic|cubicspline|lanczos|bilinear|gauss|average_magphase|rms|mode}
Select a resampling algorithm. 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.
--levels <level1,level2,...>
A list of overview levels to build. Each overview level must
be an integer value greater or equal to 2.
If not specified all existing overviews are refreshed.
--bbox <xmin>,<ymin>,<xmax>,ymax>
This option performs a partial refresh of existing overviews,
in the region of interest specified by 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.
--like <filename1>[,<filenameN>]...
This option performs a partial refresh of existing overviews,
in the region of interest specified by one or several
filenames (names separated by comma). Note that the filenames
are only used to determine 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.
--use-source-timestamp
This option performs a partial refresh of existing overviews
of a VRT -- GDAL Virtual Format or GTI -- GDAL Raster Tile
Index file with an external overview. It checks the
modification timestamp of all the sources of the VRT and
regenerate 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.
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>
COPYRIGHT
1998-2026
March 20, 2026
GDAL-RASTER-OVERVIEW-REFRESH(1)