Tile and image services · Angular, React and OpenLayers

A watercolour map with labels over it

Stack transparent Esri reference labels and borders above archival Stamen Watercolor tiles in OpenLayers while capping source maxZoom at 18.

Kraków at zoom 12 as a watercolour map, its roads in orange and its parks in green on washes of beige, with Esri's place names and dashed borders over it.
A screenshot of the example. Map tiles by Stamen Design (CC BY 3.0), from the archive of the Cooper Hewitt, Smithsonian Design Museum. Labels: Esri (Esri, HERE, Garmin, OpenStreetMap contributors and the GIS user community). Map data © OpenStreetMap contributors.

What this example shows

Central Kraków at zoom 12 appears painted in warm hand-crafted washes—ochre streets and emerald parkland from Stamen Design’s iconic Watercolor tiles preserved by the Smithsonian’s Cooper Hewitt museum—made practical for navigation by a crisp upper layer of Esri place names and administrative boundaries.

When you need it

Editorial storytelling maps, tourism guides, museum exhibits and satellite viewers frequently pair unlabelled artistic or photographic base imagery with a dedicated transparent reference-label overlay.

Separating background washes or imagery from foreground typography also lets you insert thematic polygons in between—painting flood zones or districts over the artwork while keeping city names crisp and unobstructed on top.

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.

stamen.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import { ATTRIBUTION } from 'ol/source/OSM';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceXYZComponent,
  ViewComponent,
} from 'cc-openlayers';

/**
 * Two tile layers composed: Stamen's watercolor map of Kraków, as the Cooper Hewitt, Smithsonian Design Museum keeps
 * it, with Esri's place names and borders drawn over it.
 */
@Component({
  selector: 'app-stamen',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceXYZComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="12">
        <aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-tile>
        <aol-source-xyz
          url="https://watercolormaps.collection.cooperhewitt.org/tile/watercolor/{z}/{x}/{y}.jpg"
          [minZoom]="1"
          [maxZoom]="18"
          [attributions]="watercolor"
        />
      </aol-layer-tile>
      <aol-layer-tile>
        <aol-source-xyz
          url="https://server.arcgisonline.com/ArcGIS/rest/services/Reference/World_Boundaries_and_Places/MapServer/tile/{z}/{y}/{x}"
          attributions="Labels © Esri — Esri, HERE, Garmin, © OpenStreetMap contributors, and the GIS user community"
        />
      </aol-layer-tile>
    </aol-map>
  `,
})
export class Stamen {
  protected readonly watercolor = [
    'Map tiles by <a href="https://stamen.com/">Stamen Design</a>, under ' +
      '<a href="https://creativecommons.org/licenses/by/3.0">CC BY 3.0</a>, from the ' +
      '<a href="https://watercolormaps.collection.cooperhewitt.org/">Cooper Hewitt archive</a>',
    ATTRIBUTION,
  ];
}

Architecture and OpenLayers mechanics

Two aol-layer-tile elements stack in template order: the bottom aol-source-xyz fetches Stamen Watercolor tiles from the Smithsonian archive with [maxZoom] capped at 18 (the deepest level in the archive), while the top aol-source-xyz fetches Esri’s transparent World Boundaries and Places PNGs using {z}/{y}/{x} row-first coordinates.

Because [maxZoom] is declared on the watercolour source, zooming in to level 19 or 20 smoothly upscales level-18 tiles instead of requesting non-existent files.

How it works

  • The bottom aol-source-xyz loads unlabelled Stamen Watercolor tiles preserved in the Cooper Hewitt museum collection.
  • The upper aol-source-xyz overlays transparent Esri World Boundaries and Places labels using ArcGIS row-before-column URL order.
  • Setting source [maxZoom] to 18 lets OpenLayers overzoom level-18 watercolour tiles cleanly when users zoom closer.

Pitfalls

  • Because the museum archive serves watercolour tiles without CORS headers, they display normally in standard 2D canvas layers but taint the canvas—meaning map exports through canvas.toDataURL or pixel readbacks fail on that layer; the archive would also have to send CORS headers before the source could request them.
  • Always keep reference label layers at the top of the layer stack (or assign a high Z-index) so thematic fills do not paint over town and street names.

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.