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.

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.tsimport 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.tsimport { 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();
}
} 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-pyramid.react.tsximport { useLayoutEffect, useState } from 'react';
import { DefaultControls, DefaultInteractions, Map, View } from 'cc-openlayers/react';
import { WebGLTileLayer } from 'cc-openlayers/react/webgl';
import { COG_PYRAMID_ATTRIBUTION_OPTIONS, COG_PYRAMID_VIEW, createCogPyramidSourceOwner } from './cog-pyramid.shared';
export function CogPyramidReact() {
const [sourceOwner] = useState(createCogPyramidSourceOwner);
useLayoutEffect(() => {
sourceOwner.activate();
return () => sourceOwner.dispose();
}, [sourceOwner]);
return (
<Map height="480px" ariaLabel="Kraków satellite imagery tile pyramid map">
<DefaultInteractions />
<DefaultControls attributionOptions={COG_PYRAMID_ATTRIBUTION_OPTIONS} />
<View {...COG_PYRAMID_VIEW} />
<WebGLTileLayer sources={sourceOwner.sources} />
</Map>
);
}cog-pyramid.shared.tsimport 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();
},
};
}How the React version works
A five-level geographic pyramid over Kraków selects separate GeoTIFF files by the visible extent and resolution. Each file is a COG with its own internal overview chain. The first four outer levels use one file each; the finest level uses two adjacent files.
What both versions share
The adapters use the existing WebGL tile layer's function-valued sources option and OpenLayers sourcesFromTileGrid. The outer grid covers [413660, 5535760, 434140, 5556240] in EPSG:32634 at 160, 80, 40, 20 and 10 metres per pixel. The view starts at 20 m and stays inside that declared range. constrainOnlyCenter keeps the center inside the crop while allowing a larger viewport to reach every outer level. Local URLs follow assets/krakow/cog-pyramid/{z}/{y}/{x}.tif. This is an external file pyramid, distinct from the overviews inside each TIFF and from the single-file cog example. The image is a native crop of the same Sentinel-2 true-colour scene; it does not claim survey detail beyond its original 10 m pixels.
From Angular to React
| Angular | React |
|---|---|
CogPyramid composes the map, view and WebGL layer | CogPyramidReact composes the same existing adapters |
The layer receives a function-valued sources input | The layer receives the equivalent sources prop |
| Component teardown releases its owned GeoTIFF sources | Effect cleanup releases its owned GeoTIFF sources |
Who creates, updates and disposes
The source factory owns only the public GeoTIFF objects it creates. It does not access the OpenLayers helper's private cache. The map/layer adapters retain their normal lifecycle ownership. The data and coordinate rules are shared; neither framework reimplements a second pyramid.
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.
sourcesFromTileGridpasses 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
sourcesFromTileGridresolution cut-offs aligned with the native pixel sizes of each pyramid tier so the right regional files activate at each zoom.
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.