Tile and image services · Angular, React and OpenLayers

Read raster tiles from PMTiles

Stream Stamen raster tiles directly from a serverless single-file PMTiles archive in OpenLayers using HTTP byte-range requests and object URLs.

Read Stamen raster tiles directly from a PMTiles archive using HTTP range requests.
A screenshot of the example. Map data © OpenStreetMap contributors. Map tiles © Stamen Design, CC BY 4.0; OpenStreetMap data under ODbL.

What this example shows

Stamen Design raster cartography renders seamlessly inside OpenLayers straight from a single static .pmtiles archive file using HTTP Range requests—requiring zero tile database, Node/Python server or unpacked million-file directory tree.

When you need it

Protomaps PMTiles packs an entire multi-zoom raster or vector pyramid into one cloud-storage-friendly archive addressable via standard HTTP 206 Partial Content byte ranges on S3, R2, Nginx or static hosting.

Integrating pmtiles with OpenLayers lets teams deploy self-contained offline or CDN-cached tile pyramids as a single file.

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.

pmtiles-image.html
<aol-map height="480px"
  ><aol-interaction-default /><aol-control-defaults /><aol-view [zoom]="4"
    ><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view
  ><aol-layer-tile><aol-source-osm /></aol-layer-tile
  ><aol-layer-webgltile
    ><aol-source-datatile
      [loader]="loader"
      [maxZoom]="3"
      [transition]="0"
      [attributions]="credit" /></aol-layer-webgltile
></aol-map>
<p class="example-hint">This archive ends at zoom 3; closer views enlarge its existing tiles.</p>
pmtiles-image.shared.ts
import { PMTiles } from 'pmtiles';
import type { Loader } from 'ol/source/DataTile.js';

export const IMAGE_ARCHIVE = 'https://pmtiles.io/stamen_toner(raster)CC-BY+ODbL_z3.pmtiles';
export const IMAGE_CREDIT = 'Map tiles © Stamen Design, CC BY 4.0; data © OpenStreetMap contributors, ODbL.';

/** Temporary URLs live only until the browser decodes each archive entry. */
export async function decodeArchiveTile(data: Uint8Array): Promise<HTMLImageElement> {
  const url = URL.createObjectURL(new Blob([new Uint8Array(data)]));
  try {
    return await new Promise<HTMLImageElement>((resolve, reject) => {
      const image = new Image();
      image.onload = () => resolve(image);
      image.onerror = () => reject(new Error('Tile image could not be decoded'));
      image.src = url;
    });
  } finally {
    URL.revokeObjectURL(url);
  }
}

export function archiveLoader(url: string): Loader {
  const archive = new PMTiles(url);
  return async (z, x, y, options) => {
    const tile = await archive.getZxy(z, x, y, options.signal);
    if (!tile) throw new Error('Tile is absent from the archive');
    return decodeArchiveTile(new Uint8Array(tile.data));
  };
}
pmtiles-image.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceDataTileComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';
import { LayerWebGLTileComponent } from 'cc-openlayers/webgl';
import { archiveLoader, IMAGE_ARCHIVE, IMAGE_CREDIT } from './pmtiles-image.shared';
@Component({
  selector: 'app-pmtiles-image',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceDataTileComponent,
    SourceOsmComponent,
    ViewComponent,
    LayerWebGLTileComponent,
  ],
  templateUrl: './pmtiles-image.html',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class PmtilesImage {
  protected readonly loader = archiveLoader(IMAGE_ARCHIVE);
  protected readonly credit = IMAGE_CREDIT;
}

Architecture and OpenLayers mechanics

A shared pmtiles archive reader resolves each requested (z, x, y) tile via Hilbert-curve directory lookups and byte-range fetches, wraps the compressed image bytes in a temporary Blob object URL to decode the bitmap, and immediately revokes the object URL once decoded so browser memory stays flat.

How it works

  • The pmtiles reader fetches requested tile byte ranges on demand, decoding each image through a temporary object URL that is revoked immediately after load.

Pitfalls

  • This compact demonstration archive contains overview zoom levels 0 through 3 only—zooming in past level 3 smoothly enlarges level-3 tiles rather than loading street-level detail.

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.