Projections · Angular, React and OpenLayers

Geographic vector tiles in a polar equal-area view

Reproject EPSG:4326 geographic vector tiles on the fly into a polar Lambert Azimuthal Equal Area (ESRI:102017) OpenLayers view with proj4.

The same pale Kraków municipality polygons reprojected into the North Pole equal-area view.
A screenshot of the example. Municipal boundaries: Państwowy Rejestr Granic © GUGiK.

What this example shows

Using the exact same EPSG:4326 PRG municipality vector-tile pyramid as vector-tiles-4326, OpenLayers reprojects decoded polygon geometries in the browser into the North Pole Lambert Azimuthal Equal Area projection (ESRI:102017)—displaying Kraków and surrounding communes rotated along their true polar meridian angle.

When you need it

Polar research portals, pan-European equal-area atlases (EPSG:3035) and national-grid CAD apps (EPSG:2180) often need custom projected views while consuming vector-tile basemaps published in EPSG:4326 or EPSG:3857.

When a VectorTile source declares its own native projection and tileGrid explicitly, OpenLayers reprojects decoded vector-tile geometries into any proj4-registered View CRS cleanly.

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.

vector-tiles-reprojected.shared.ts
import type { Extent } from 'ol/extent.js';
import { transformExtent } from 'ol/proj.js';
import { municipalityFixtureExtent } from '../vector-tiles-4326/vector-tiles-4326.shared';

export const ESRI_102017_CODE = 'ESRI:102017';
export const ESRI_102017_DEFINITION =
  '+proj=laea +lat_0=90 +lon_0=0 +x_0=0 +y_0=0 +datum=WGS84 +units=m +no_defs +type=crs';

/** Transforms the real fixture bound for the view after ESRI:102017 has been registered. */
export function getReprojectedMunicipalityFixtureExtent(): Extent {
  return transformExtent(municipalityFixtureExtent, 'EPSG:4326', ESRI_102017_CODE);
}
vector-tiles-reprojected.ts
import {
  ChangeDetectionStrategy,
  Component,
  DestroyRef,
  PendingTasks,
  effect,
  inject,
  signal,
  viewChild,
} from '@angular/core';
import { applyBackground, applyStyle } from 'ol-mapbox-style';
import type OLVectorTileLayer from 'ol/layer/VectorTile.js';
import type { Extent } from 'ol/extent.js';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  FormatMVTComponent,
  LayerVectorTileComponent,
  loadProj4,
  MapComponent,
  registerProjectionDefinitions,
  SourceVectorTileComponent,
  TileGridComponent,
  ViewComponent,
} from 'cc-openlayers';
import {
  geographicTileGridDeclaration,
  municipalityAttributionOptions,
  municipalityStyle,
  municipalityTileUrl,
} from '../vector-tiles-4326/vector-tiles-4326.shared';
import {
  ESRI_102017_CODE,
  ESRI_102017_DEFINITION,
  getReprojectedMunicipalityFixtureExtent,
} from './vector-tiles-reprojected.shared';

@Component({
  selector: 'app-vector-tiles-reprojected',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    FormatMVTComponent,
    LayerVectorTileComponent,
    MapComponent,
    SourceVectorTileComponent,
    TileGridComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    @if (ready()) {
      <aol-map height="480px" ariaLabel="Geographic vector tiles in a North Pole equal-area view">
        <aol-interaction-default />
        <aol-control-defaults [attributionOptions]="attributionOptions" />
        <aol-view
          [projection]="projection"
          [zoom]="11"
          [minZoom]="3"
          [extent]="fixtureExtent"
          [constrainOnlyCenter]="true"
        >
          <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
        </aol-view>
        <aol-layer-vectortile [declutter]="true" background="#d1d1d1">
          <aol-source-vectortile
            projection="EPSG:4326"
            [tileUrlFunction]="tileUrlFunction"
            attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
          >
            <aol-format-mvt />
            <aol-tilegrid
              [extent]="grid.extent"
              [minZoom]="grid.minZoom"
              [origin]="grid.origin"
              [resolutions]="grid.resolutions"
              [tileSize]="grid.tileSize"
            />
          </aol-source-vectortile>
        </aol-layer-vectortile>
      </aol-map>
    }
    @if (styleError()) {
      <p role="status">The local vector style could not be applied.</p>
    }
    @if (initializationError()) {
      <p role="status">The projected map could not be initialized.</p>
    }
  `,
})
export class VectorTilesReprojected {
  protected readonly projection = ESRI_102017_CODE;
  protected readonly grid = geographicTileGridDeclaration;
  protected readonly attributionOptions = municipalityAttributionOptions;
  protected readonly tileUrlFunction = municipalityTileUrl;
  protected readonly ready = signal(false);
  protected readonly styleError = signal(false);
  protected readonly initializationError = signal(false);
  protected fixtureExtent: Extent = [0, 0, 0, 0];

  private readonly layer = viewChild(LayerVectorTileComponent);
  private readonly destroyRef = inject(DestroyRef);

  constructor() {
    void inject(PendingTasks).run(async () => {
      try {
        const proj4 = await loadProj4();
        if (this.destroyRef.destroyed) return;
        registerProjectionDefinitions(proj4, { [ESRI_102017_CODE]: ESRI_102017_DEFINITION });
        this.fixtureExtent = getReprojectedMunicipalityFixtureExtent();
        this.ready.set(true);
      } catch {
        if (!this.destroyRef.destroyed) this.initializationError.set(true);
      }
    });

    effect(() => {
      const layer = this.layer()?.instance as OLVectorTileLayer | undefined;
      if (!layer) return;
      void Promise.all([
        applyStyle(layer, municipalityStyle, { updateSource: false }),
        applyBackground(layer, municipalityStyle),
      ]).catch(() => {
        if (!this.destroyRef.destroyed) this.styleError.set(true);
      });
    });
  }
}

Architecture and OpenLayers mechanics

Inside PendingTasks, the constructor lazily loads proj4 (loadProj4()), registers ESRI:102017 via registerProjectionDefinitions, computes the reprojected bounding box, and sets ready to true before @if (ready()) mounts aol-map and aol-view in ESRI:102017.

Meanwhile, aol-source-vectortile keeps projection="EPSG:4326" and its 512-pixel geographic aol-tilegrid, while applyStyle (updateSource: false) and applyBackground style the layer.

How it works

  • The EPSG:4326 vector-tile source and 512-pixel geographic grid remain unchanged while only the View switches to ESRI:102017.
  • Asynchronous proj4 registration finishes inside PendingTasks before @if mounts the projected aol-view.
  • Local Mapbox GL styling and background apply cleanly in both Angular and React adapters without duplicating source setup.
  • Metre-based view resolutions stay decoupled from the degree-based source tile matrix.

Pitfalls

  • Never set the VectorTile source projection to ESRI:102017 when the tiles themselves are cut in EPSG:4326: the source must keep projection="EPSG:4326" so OpenLayers knows what CRS to reproject decoded vertices from.
  • Always register custom proj4 definitions before instantiating View or transforming [center] / [extent] coordinates, otherwise OpenLayers cannot look up the target CRS.

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.