Raster, GeoTIFF and WebGL · Angular, React and OpenLayers

Render map tiles in a worker

Render OpenStreetMap tiles inside a dedicated Web Worker OffscreenCanvas in OpenLayers and transfer ImageBitmaps to keep UI threads responsive.

OpenStreetMap of Kraków composed from tiles rendered in a web worker.
A screenshot of the example. Map data © OpenStreetMap contributors.

What this example shows

An interactive OpenStreetMap view of Kraków composites its visible tiles from 512-pixel ImageBitmaps rendered off the main browser thread inside a dedicated module Web Worker—keeping main-thread controls and animations smooth.

When you need it

Complex multi-layer tile composition, dense vector-to-tile styling or CPU-heavy map overlays can cause frame drops on the main UI thread while forms, charts or animations run alongside the map.

Delegating tile rendering to a headless OpenLayers map targeting an OffscreenCanvas inside a Web Worker isolates rendering work from main-thread UI responsiveness.

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.

offscreen-client.ts
export interface OffscreenClient {
  loader(z: number, x: number, y: number): Promise<ImageBitmap>;
  dispose(): void;
}
interface Job {
  id: number;
  tile: number[];
  resolve(image: ImageBitmap): void;
  reject(error: Error): void;
}
interface Reply {
  action: 'rendered' | 'error';
  id: number;
  image?: ImageBitmap;
  error?: string;
}
/** One worker map renders one tile at a time; every request settles even if rendering fails. */
export function createOffscreenClient(worker: Worker, onError: () => void, timeout = 20000): OffscreenClient {
  const queue: Job[] = [];
  let sequence = 0;
  let stopped = false;
  let timer: ReturnType<typeof setTimeout> | undefined;
  const next = () => {
    const job = queue[0];
    if (!job || stopped) return;
    timer = setTimeout(() => finish(undefined, new Error('Worker render timed out')), timeout);
    try {
      worker.postMessage({ action: 'render', id: job.id, tile: job.tile });
    } catch {
      finish(undefined, new Error('Worker could not receive the tile'));
    }
  };
  const finish = (image?: ImageBitmap, error?: Error) => {
    clearTimeout(timer);
    const job = queue.shift();
    if (error) {
      job?.reject(error);
      onError();
    } else if (image) {
      job?.resolve(image);
    }
    next();
  };
  const message = (event: MessageEvent<Reply>) => {
    const { action, id, image, error } = event.data;
    if (stopped || queue[0]?.id !== id) {
      image?.close();
      return;
    }
    if (action === 'rendered' && image) finish(image);
    else if (action === 'error') finish(undefined, new Error(error ?? 'Worker render failed'));
  };
  const dispose = () => {
    if (stopped) return;
    stopped = true;
    clearTimeout(timer);
    worker.terminate();
    worker.removeEventListener('error', fault);
    worker.removeEventListener('messageerror', fault);
    // Keep the message handler to close bitmaps already posted before termination.
    for (const job of queue.splice(0)) job.reject(new Error('Worker disposed'));
  };
  const fault = () => {
    onError();
    dispose();
  };
  worker.addEventListener('message', message);
  worker.addEventListener('error', fault);
  worker.addEventListener('messageerror', fault);
  return {
    loader: (z, x, y) => {
      if (stopped) return Promise.reject(new Error('Worker disposed'));
      return new Promise<ImageBitmap>((resolve, reject) => {
        queue.push({ id: ++sequence, tile: [z, x, y], resolve, reject });
        if (queue.length === 1) next();
      });
    },
    dispose,
  };
}
export function supportsOffscreenRendering(): boolean {
  return typeof Worker !== 'undefined' && typeof OffscreenCanvas !== 'undefined';
}
export function startOffscreenClient(onError: () => void): OffscreenClient {
  return createOffscreenClient(
    new Worker(new URL('./tiled-layer-rendering-in-offscreen-canvas.worker', import.meta.url), { type: 'module' }),
    onError
  );
}
tiled-layer-rendering-in-offscreen-canvas.ts
import { afterNextRender, ChangeDetectionStrategy, Component, DestroyRef, inject, signal } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceImageTileComponent,
  ViewComponent,
} from 'cc-openlayers';
import { type OffscreenClient, startOffscreenClient, supportsOffscreenRendering } from './offscreen-client';

/** Tile images are rendered in a worker's OpenLayers map on an OffscreenCanvas. */
@Component({
  selector: 'app-tiled-layer-rendering-in-offscreen-canvas',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceImageTileComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @if (client(); as renderer) {
      <aol-map height="480px">
        <aol-interaction-default />
        <aol-control-defaults />
        <aol-view [zoom]="13">
          <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
        </aol-view>
        <aol-layer-tile>
          <aol-source-imagetile [tileSize]="512" [loader]="renderer.loader" [attributions]="attributions" />
        </aol-layer-tile>
      </aol-map>
    } @else {
      <p class="example-hint">This example needs Web Workers and OffscreenCanvas.</p>
    }
    @if (failed()) {
      <p class="example-hint" role="status">The worker could not render the map.</p>
    }
  `,
})
export class TiledLayerRenderingInOffscreenCanvas {
  readonly client = signal<OffscreenClient | null>(null);
  readonly failed = signal(false);
  readonly attributions =
    '<a href="https://www.openstreetmap.org/copyright" target="_blank">© OpenStreetMap contributors</a>';
  constructor() {
    const destroy = inject(DestroyRef);
    afterNextRender(() => {
      if (!supportsOffscreenRendering()) return;
      try {
        const client = startOffscreenClient(() => this.failed.set(true));
        this.client.set(client);
        destroy.onDestroy(() => client.dispose());
      } catch {
        this.failed.set(true);
      }
    });
  }
}
tiled-layer-rendering-in-offscreen-canvas.worker.ts
import Map from 'ol/Map.js';
import View from 'ol/View.js';
import TileLayer from 'ol/layer/Tile.js';
import { unByKey } from 'ol/Observable.js';
import OSM from 'ol/source/OSM.js';
import { createXYZ } from 'ol/tilegrid.js';
import type { TileCoord } from 'ol/tilecoord.js';

const worker = self as unknown as {
  addEventListener(
    type: 'message',
    listener: (event: MessageEvent<{ action: string; id: number; tile: TileCoord }>) => void
  ): void;
  postMessage(
    message: { action: string; id: number; error?: string; image?: ImageBitmap },
    transfer?: Transferable[]
  ): void;
};
const tileGrid = createXYZ({ tileSize: 512 });
const canvas = new OffscreenCanvas(512, 512);
const source = new OSM({ transition: 0 });
// OpenLayers supports OffscreenCanvas targets; its DOM declaration retains HTMLElement.
const map = new Map({ target: canvas as unknown as HTMLElement, layers: [new TileLayer({ source })] });
let cleanup: (() => void) | undefined;

worker.addEventListener('message', ({ data }: MessageEvent<{ action: string; id: number; tile: TileCoord }>) => {
  if (data.action !== 'render') return;
  cleanup?.();
  let settled = false;
  const timer = setTimeout(() => finish('Render timed out'), 15000);
  const clear = () => {
    clearTimeout(timer);
    if (complete) unByKey(complete);
    if (failed) unByKey(failed);
  };
  const finish = (error?: string) => {
    if (settled) return;
    settled = true;
    clear();
    if (error) {
      worker.postMessage({ action: 'error', id: data.id, error });
      return;
    }
    try {
      const image = canvas.transferToImageBitmap();
      worker.postMessage({ action: 'rendered', id: data.id, image }, [image]);
    } catch {
      worker.postMessage({ action: 'error', id: data.id, error: 'Bitmap transfer failed' });
    }
  };
  cleanup = () => {
    settled = true;
    clear();
  };
  const complete = map.once('rendercomplete', () => finish());
  const failed = source.on('tileloaderror', () => finish('Tile loading failed'));
  try {
    map.setView(
      new View({ center: tileGrid.getTileCoordCenter(data.tile), resolution: tileGrid.getResolution(data.tile[0]) })
    );
  } catch {
    finish('Render failed');
  }
});

Architecture and OpenLayers mechanics

A dedicated module worker instantiates its own headless OpenLayers Map backed by a 512-pixel OffscreenCanvas. On the main thread, the visible image-tile source delegates tile loads through a serialized request client that correlates worker replies by request ID, transfers finished ImageBitmaps back with zero pixel copying, settles pending promises on timeouts or worker errors, and terminates the worker when the component unmounts.

How it works

  • A background module worker runs an OpenLayers map instance rendering onto a 512-pixel OffscreenCanvas.
  • A serialized client queue matches asynchronous tile requests and transferred ImageBitmap replies by request ID.
  • Timeouts, error handlers and component teardown settle in-flight promises and terminate the worker cleanly.

Pitfalls

  • Both Web Workers and OffscreenCanvas must be supported by the browser runtime (and workers are skipped during Server-Side Rendering, with an explicit fallback message shown on unsupported environments).
  • Because requests serialize through a single worker map instance, this pattern offloads work from the UI thread rather than parallelising across multiple worker threads.

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.