Raster, GeoTIFF and WebGL · Angular, React and OpenLayers
A GeoTIFF with its overviews in a separate file
Pair a full-resolution GeoTIFF with an external .ovr overview file in OpenLayers so zoomed-out WebGL views fetch lightweight downsampled tiles.

What this example shows
Over Nowa Huta in eastern Kraków on a dark background, zooming out reads lightweight 20 m and 40 m downsampled imagery from a companion .ovr sidecar file, while zooming in seamlessly switches to the 10 m full-resolution .tif file.
When you need it
GDAL workflows (gdaladdo -ro) and archival GIS pipelines frequently generate external .tif.ovr overview sidecars beside read-only master GeoTIFFs instead of rewriting the original file.
Declaring external overviews prevents browsers from downloading megabytes of 10 m full-resolution pixels just to paint a small thumbnail overview.
The code
The example uses cc-openlayers, my Angular component library for OpenLayers: each aol-… element creates the OpenLayers object it names, updates it from its inputs and disposes of it with the component.
cog-overviews.tsimport { ChangeDetectionStrategy, Component, signal } from '@angular/core';
import { DefaultControlComponent, DefaultInteractionComponent, MapComponent, ViewComponent } from 'cc-openlayers';
import { LayerWebGLTileComponent, SourceGeoTIFFComponent } from 'cc-openlayers/webgl';
import type { SourceInfo } from 'ol/source/GeoTIFF';
import type { ViewOptions } from 'ol/View';
/**
* A GeoTIFF with external overviews: the sample of Nowa Huta holds only its 10 m pixels, and the `overviews` of its
* source name a separate file with the same image at 20 m and 40 m, which the map reads when zoomed out.
*/
@Component({
selector: 'app-cog-overviews',
imports: [
DefaultControlComponent,
DefaultInteractionComponent,
LayerWebGLTileComponent,
MapComponent,
SourceGeoTIFFComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px">
<aol-interaction-default />
<aol-control-defaults />
@if (view(); as options) {
<aol-view
[projection]="options.projection"
[resolutions]="options.resolutions"
[extent]="options.extent"
[center]="options.center"
[zoom]="options.zoom"
[showFullExtent]="options.showFullExtent"
/>
}
<aol-layer-webgltile>
<aol-source-geotiff
[sources]="sources"
attributions="Contains modified Copernicus Sentinel data 2024"
(viewReady)="view.set($event)"
/>
</aol-layer-webgltile>
</aol-map>
`,
})
export class CogOverviews {
readonly view = signal<ViewOptions | undefined>(undefined);
protected readonly sources: SourceInfo[] = [
{ url: 'assets/krakow/nowa-huta.tif', overviews: ['assets/krakow/nowa-huta.ovr.tif'] },
];
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
cog-overviews.react.tsximport { useState } from 'react';
import type { SourceInfo } from 'ol/source/GeoTIFF.js';
import type { ViewOptions } from 'ol/View.js';
import { DefaultControls, DefaultInteractions, Map, View } from 'cc-openlayers/react';
import { GeoTIFFSource, WebGLTileLayer } from 'cc-openlayers/react/webgl';
const SOURCES: SourceInfo[] = [{ url: 'assets/krakow/nowa-huta.tif', overviews: ['assets/krakow/nowa-huta.ovr.tif'] }];
/**
* A GeoTIFF with external overviews: the sample of Nowa Huta holds only its 10 m pixels, and the `overviews` of its
* source name a separate file with the same image at 20 m and 40 m, which the map reads when zoomed out.
*/
export function CogOverviews() {
const [view, setView] = useState<ViewOptions>();
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
{view && (
<View
projection={view.projection}
resolutions={view.resolutions}
extent={view.extent}
center={view.center}
zoom={view.zoom}
showFullExtent={view.showFullExtent}
/>
)}
<WebGLTileLayer>
<GeoTIFFSource
sources={SOURCES}
attributions="Contains modified Copernicus Sentinel data 2024"
onViewReady={setView}
/>
</WebGLTileLayer>
</Map>
);
}How the React version works
Nowa Huta from a GeoTIFF without its own overviews, read with the overviews of a separate file named in the source's overviews. The source reads the file in the browser, so nothing is drawn before its metadata arrive.
What both versions share
OpenLayers renders the map and handles the interactions; the cc-openlayers/core layer gives both adapters the same view binding (MapViewBinding) and the same conversion of coordinates from EPSG:4326 to the map's projection. OpenLayers draws the tiles with WebGL; the style expressions run on the GPU in both versions.
From Angular to React
| Angular | React |
|---|---|
<aol-source-geotiff [sources]> with overviews | <GeoTIFFSource sources> with the same module constant |
(viewReady) and a signal of the view options | onViewReady and useState; the View is rendered once the options are there |
Who creates, updates and disposes
Map creates the ol/Map in useLayoutEffect and disposes of it on unmount; each layer, source and interaction component adds its object to the parent it gets from context and removes it in its effect's cleanup, as ngOnDestroy does in Angular.
Architecture and OpenLayers mechanics
The GeoTIFF source entry specifies { url: 'assets/krakow/nowa-huta.tif', overviews: ['assets/krakow/nowa-huta.ovr.tif'] }. OpenLayers treats the main raster and its external overview TIFF as one unified multi-resolution pyramid, emitting the combined resolution range through (viewReady)="view.set($event)" into aol-view.
How it works
- Configuring
{ url: 'assets/krakow/nowa-huta.tif', overviews: ['assets/krakow/nowa-huta.ovr.tif'] }links the 10 m master TIFF with its 20 m and 40 m external overviews. - OpenLayers merges both files into one virtual pyramid and automatically reads whichever resolution matches the current zoom.
(viewReady)="view.set($event)"configuresaol-viewacross the full combined resolution span.
Pitfalls
- External
overviewsURLs are supported strictly with standard URL-based GeoTIFF sources: combiningoverviewswith a custom loader throws Source overviews are not supported when using a custom loader, and Blob sources ignore external overviews.
Related examples
The same feature in the OpenLayers examples .
Background: state and lifecycle of maps in Angular with OpenLayers, which the components of cc-openlayers take care of.