Layers · Angular, React and OpenLayers

Switch layers by resolution

Control scale-dependent OpenLayers tile layers in map units per pixel using inclusive minResolution and exclusive maxResolution thresholds.

A topographic map of central Europe at zoom 5 centred on Kraków, from the Baltic Sea to the Alps and the Carpathians.
A screenshot of the example. Map style © OpenTopoMap (CC-BY-SA). Map data © OpenStreetMap contributors. Elevation: SRTM.

What this example shows

Opening at zoom 5 across central Europe from the Baltic Sea to the Carpathians and Alps, the map displays OpenTopoMap’s regional shaded contours. Zooming in past ~zoom 6.3 switches automatically to OpenStreetMap street tiles for zooms 7 through 9, while zooming out to zoom 2 or zooming in to 10+ leaves both layers outside their resolution bands.

When you need it

Cartographic styling rules, OGC SLD/WMS MinScaleDenominator specifications and custom local-projection GIS projects frequently define visibility windows in ground/map units per pixel rather than Web Mercator tile zoom integers.

Using minResolution and maxResolution keeps visibility thresholds anchored directly to physical map resolution even when views use custom tile grids or continuous fractional zooms.

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.

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

/** A topographic map at small scales and the street map at middle ones, each shown only within its resolutions. */
@Component({
  selector: 'app-min-max-resolution',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    SourceXYZComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="5">
        <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-tile [minResolution]="200" [maxResolution]="2000"><aol-source-osm /></aol-layer-tile>
      <aol-layer-tile [minResolution]="2000" [maxResolution]="20000">
        <aol-source-xyz
          url="https://tile.opentopomap.org/{z}/{x}/{y}.png"
          [maxZoom]="17"
          [attributions]="topoAttributions"
        />
      </aol-layer-tile>
    </aol-map>
  `,
})
export class MinMaxResolution {
  protected readonly topoAttributions = [
    'Map style © <a href="https://opentopomap.org/">OpenTopoMap</a> (<a href="https://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a>)',
    ATTRIBUTION,
  ];
}

Architecture and OpenLayers mechanics

Each aol-layer-tile declares [minResolution] and [maxResolution] in the view’s coordinate units per CSS pixel: OpenTopoMap spans 2000 to 20000 m/px, and OpenStreetMap spans 200 to 2000 m/px. Mirroring zoom limits, OpenLayers includes the detailed boundary (resolution >= minResolution) and excludes the coarse boundary (resolution < maxResolution).

Because Web Mercator resolution 2000 falls at fractional zoom ~6.29, integer zooms 3–6 render OpenTopoMap (configured via aol-source-xyz with source [maxZoom] 17) and integer zooms 7–9 render OpenStreetMap.

How it works

  • [minResolution] (inclusive) and [maxResolution] (exclusive) define each aol-layer-tile visibility band in map units per pixel.
  • A threshold of 2000 Web Mercator units per pixel corresponds to zoom ~6.29, showing OpenTopoMap on integer zooms 3–6 and OpenStreetMap on zooms 7–9.
  • OpenTopoMap streams through aol-source-xyz with its required attribution and native source [maxZoom] of 17.

Pitfalls

  • Resolution values are measured in projection units rather than true ground metres: at Kraków’s 50° N latitude, one Web Mercator unit equals roughly 0.64 ground metres, so 200 map units per pixel represents ~128 metres on the ground.
  • Keep boundary inclusivity straight: a layer renders at exact minResolution (most detailed end) and turns off at exact maxResolution (coarsest end), so sharing 2000 across two adjacent layers hands off cleanly without overlap.

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.