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.

The square Sentinel-2 image of Nowa Huta on a dark background: housing estates, the road junction in the north-east and fields and woods down to the Vistula.
A screenshot of the example. Contains modified Copernicus Sentinel data 2024.

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.ts
import { 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'] },
  ];
}

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)" configures aol-view across the full combined resolution span.

Pitfalls

  • External overviews URLs are supported strictly with standard URL-based GeoTIFF sources: combining overviews with a custom loader throws Source overviews are not supported when using a custom loader, and Blob sources ignore external overviews.

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.