Raster, GeoTIFF and WebGL · Angular, React and OpenLayers

A local pyramid of Cloud Optimized GeoTIFFs

Stream a multi-file 5-level Cloud Optimized GeoTIFF pyramid over Kraków in OpenLayers using sourcesFromTileGrid for extent and scale selection.

A native true-colour Sentinel-2 crop over Kraków, centred on the Main Market Square, rendered from the local COG pyramid.
A screenshot of the example. Contains modified Copernicus Sentinel data 2024.

What this example shows

Centred on Kraków’s Main Market Square in UTM zone 34N (EPSG:32634), a 20.48 km satellite mosaic transitions seamlessly across five resolution tiers (160, 80, 40, 20 and 10 m/px)—dynamically selecting individual COG files by visible extent and zoom scale.

When you need it

Country-wide orthophoto coverages and continental Sentinel mosaics are partitioned into thousands of separate COG files across a spatial/resolution grid rather than one giant terabyte file.

OpenLayers’ sourcesFromTileGrid mounts only the specific COG files intersecting the current viewport and resolution tier while still exploiting each file’s internal TIFF pyramid.

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-pyramid.shared.ts
import GeoTIFF from 'ol/source/GeoTIFF.js';
import { sourcesFromTileGrid } from 'ol/source.js';
import type { Extent } from 'ol/extent.js';
import TileGrid from 'ol/tilegrid/TileGrid.js';
import type { ViewOptions } from 'ol/View.js';
import type { Size } from 'ol/size.js';

export const COG_PYRAMID_EXTENT: Extent = [413_660, 5_535_760, 434_140, 5_556_240];
export const COG_PYRAMID_RESOLUTIONS = [160, 80, 40, 20, 10];
export const COG_PYRAMID_TILE_SIZES: Size[] = [
  [128, 128],
  [256, 256],
  [512, 512],
  [1024, 1024],
  [1024, 2048],
];
export const COG_PYRAMID_ATTRIBUTION = 'Contains modified Copernicus Sentinel data 2024';
export const COG_PYRAMID_ATTRIBUTION_OPTIONS = { collapsible: false };
export const COG_PYRAMID_ASSET_ROOT = 'assets/krakow/cog-pyramid';

export const COG_PYRAMID_TILE_GRID = new TileGrid({
  extent: COG_PYRAMID_EXTENT,
  resolutions: COG_PYRAMID_RESOLUTIONS,
  tileSizes: COG_PYRAMID_TILE_SIZES,
});

export const COG_PYRAMID_VIEW: ViewOptions = {
  projection: 'EPSG:32634',
  extent: COG_PYRAMID_EXTENT,
  center: [423_901, 5_545_999],
  resolution: 20,
  minResolution: 10,
  maxResolution: 160,
  constrainOnlyCenter: true,
};

type PyramidSourcesFunction = (extent: Extent, resolution: number) => GeoTIFF[];

interface ManagedSourceSet {
  readonly sources: PyramidSourcesFunction;
  dispose(): void;
}

interface CogPyramidSourceOwner {
  readonly sources: PyramidSourcesFunction;
  /** Starts a new source cache when a React development StrictMode effect is replayed. */
  activate(): void;
  /** Releases every GeoTIFF created for this map. */
  dispose(): void;
}

function createManagedSourceSet(): ManagedSourceSet {
  const owned = new Set<GeoTIFF>();
  const gridSources = sourcesFromTileGrid(COG_PYRAMID_TILE_GRID, ([z, x, y]) => {
    const source = new GeoTIFF({
      sources: [{ url: `${COG_PYRAMID_ASSET_ROOT}/${z}/${y}/${x}.tif` }],
      attributions: COG_PYRAMID_ATTRIBUTION,
    });
    owned.add(source);
    return source;
  });

  return {
    sources: gridSources as unknown as PyramidSourcesFunction,
    dispose() {
      for (const source of owned) source.dispose();
      owned.clear();
    },
  };
}

/**
 * Creates the same function-valued layer sources used by the OpenLayers COG-pyramid example.
 * The wrappers release the layer and map; this owner also releases the GeoTIFF sources held by
 * OpenLayers' helper cache. React explicitly activates a fresh cache during StrictMode setup replay;
 * callbacks retained after final teardown return no sources.
 */
export function createCogPyramidSourceOwner(): CogPyramidSourceOwner {
  let managed = createManagedSourceSet();
  let disposed = false;

  return {
    sources(extent, resolution) {
      return disposed ? [] : managed.sources(extent, resolution);
    },
    activate() {
      if (!disposed) return;
      managed = createManagedSourceSet();
      disposed = false;
    },
    dispose() {
      if (disposed) return;
      disposed = true;
      managed.dispose();
    },
  };
}
cog-pyramid.ts
import { ChangeDetectionStrategy, Component, OnDestroy } from '@angular/core';
import { DefaultControlComponent, DefaultInteractionComponent, MapComponent, ViewComponent } from 'cc-openlayers';
import { LayerWebGLTileComponent } from 'cc-openlayers/webgl';
import { COG_PYRAMID_ATTRIBUTION_OPTIONS, COG_PYRAMID_VIEW, createCogPyramidSourceOwner } from './cog-pyramid.shared';

@Component({
  selector: 'app-cog-pyramid',
  imports: [DefaultControlComponent, DefaultInteractionComponent, LayerWebGLTileComponent, MapComponent, ViewComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px" ariaLabel="Kraków satellite imagery tile pyramid map">
      <aol-interaction-default />
      <aol-control-defaults [attributionOptions]="attributionOptions" />
      <aol-view
        [projection]="view.projection"
        [extent]="view.extent"
        [center]="view.center"
        [resolution]="view.resolution"
        [minResolution]="view.minResolution"
        [maxResolution]="view.maxResolution"
        [constrainOnlyCenter]="view.constrainOnlyCenter"
      />
      <aol-layer-webgltile [sources]="sources" />
    </aol-map>
  `,
})
export class CogPyramid implements OnDestroy {
  private readonly sourceOwner = createCogPyramidSourceOwner();
  readonly view = COG_PYRAMID_VIEW;
  readonly attributionOptions = COG_PYRAMID_ATTRIBUTION_OPTIONS;
  protected readonly sources = this.sourceOwner.sources;

  ngOnDestroy(): void {
    this.sourceOwner.dispose();
  }
}

Architecture and OpenLayers mechanics

An outer five-level pyramid in EPSG:32634 (160 down to 10 m/px, using single files on coarse tiers and adjacent split files at the finest 10 m tier) drives sourcesFromTileGrid, which supplies a dynamic source-selector function to the WebGL tile layer.

The view constrains navigation to the 160–10 m/px resolution range starting at 20 m/px over Rynek Główny.

How it works

  • A local five-tier UTM 34N (EPSG:32634) pyramid covers a 20.48 km square around Kraków across 160, 80, 40, 20 and 10 m/px.
  • Coarser tiers map to single COG files while the finest 10 m tier splits into two adjacent regional COG files.
  • sourcesFromTileGrid passes a function-valued source selector to the WebGL tile layer, preserving each file’s GeoKeys and internal overviews.
  • Camera zoom is bounded cleanly to the 160–10 m/px pyramid range centred on the Main Market Square.

Pitfalls

  • Every member TIFF in a pyramid must be a true Cloud Optimized GeoTIFF with valid GeoKeys, tiled IFDs and overview layout—plain striped TIFFs break efficient range reads.
  • Ensure static file hosts support HTTP 206 Partial Content with Content-Range headers for byte-range requests.
  • Keep outer sourcesFromTileGrid resolution cut-offs aligned with the native pixel sizes of each pyramid tier so the right regional files activate at each zoom.

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.