Projections · Angular, React and OpenLayers

A 512-pixel geographic vector-tile grid

Configure an explicit 512-pixel EPSG:4326 vector-tile grid in OpenLayers and apply a local Mapbox GL v8 style with matching zoom resolutions.

Kraków municipality boundaries in pale yellow with grey outlines in a geographic map view.
A screenshot of the example. Municipal boundaries: Państwowy Rejestr Granic © GUGiK.

What this example shows

Centred on Kraków in an EPSG:4326 view ([zoom]="12", [constrainOnlyCenter]="true"), PRG municipality vector tiles load on an explicit 512-pixel geographic tile grid ([-180, 90] origin) and render through a local Mapbox GL v8 style document with expanded attribution.

When you need it

Commercial and enterprise EPSG:4326 vector-tile providers frequently serve 512-pixel logical tiles (maxResolution = 180 / 512) rather than OpenLayers’ default 256-pixel grid—requiring both the TileGrid and ol-mapbox-style zoom stops to share that exact resolution ladder.

Aligning resolutions across aol-tilegrid and applyStyle keeps tile requests and zoom-dependent Mapbox GL rules in exact lockstep.

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-4326.shared.ts
import { extend, createEmpty, type Extent } from 'ol/extent.js';
import type { TileCoord } from 'ol/tilecoord.js';
import { createXYZ } from 'ol/tilegrid.js';
import municipalityMetadata from '../../../assets/krakow/municipality-tiles/WorldCRS84Quad.json';

const TILESET_PATH = 'assets/krakow/municipality-tiles/WorldCRS84Quad';
const WORLD_EXTENT: Extent = [-180, -90, 180, 90];
const WORLD_ORIGIN = [-180, 90] as const;
const LOGICAL_TILE_SIZE = 512;
const GLOBAL_MAX_RESOLUTION = 180 / LOGICAL_TILE_SIZE;

const limitsByZoom = new Map(
  municipalityMetadata.tileMatrixSetLimits.map((limits) => [Number(limits.tileMatrix), limits])
);
const sourceZooms = [...limitsByZoom.keys()];
const MIN_SOURCE_ZOOM = Math.min(...sourceZooms);
const MAX_SOURCE_ZOOM = Math.max(...sourceZooms);

/** The 512-pixel grid keeps each WorldCRS84Quad matrix cell at its original z/x/y indices. */
export const geographicTileGrid = createXYZ({
  extent: WORLD_EXTENT,
  minZoom: MIN_SOURCE_ZOOM,
  tileSize: LOGICAL_TILE_SIZE,
  maxResolution: GLOBAL_MAX_RESOLUTION,
  maxZoom: MAX_SOURCE_ZOOM,
});

/** A value declaration for the Angular and React source adapters. */
export const geographicTileGridDeclaration = {
  extent: WORLD_EXTENT,
  minZoom: MIN_SOURCE_ZOOM,
  origin: [...WORLD_ORIGIN],
  resolutions: geographicTileGrid.getResolutions(),
  tileSize: LOGICAL_TILE_SIZE,
};

/**
 * The finite PRG coverage comes from the fixture's finest matrix limits. Extents are generated by
 * the public grid API so the geographic grid remains the single owner of cell geometry.
 */
export const municipalityFixtureExtent: Extent = (() => {
  const limits = limitsByZoom.get(MAX_SOURCE_ZOOM);
  if (!limits) throw new Error(`Missing WorldCRS84Quad limits for zoom ${MAX_SOURCE_ZOOM}.`);
  const extent = createEmpty();
  extend(extent, geographicTileGrid.getTileCoordExtent([MAX_SOURCE_ZOOM, limits.minTileCol, limits.minTileRow]));
  extend(extent, geographicTileGrid.getTileCoordExtent([MAX_SOURCE_ZOOM, limits.maxTileCol, limits.maxTileRow]));
  return extent;
})();

/** Keep the local PRG source credit expanded beside the map. */
export const municipalityAttributionOptions = { collapsible: false };

/**
 * Uses the PRG metadata to suppress requests outside the actual local fixture. OL tile coordinates
 * and the fixture's WorldCRS84Quad links both use a top-left, positive row index.
 */
export function municipalityTileUrl(tileCoord: TileCoord | null): string | undefined {
  if (!tileCoord) return undefined;
  const [zoom, column, row] = tileCoord;
  const limits = limitsByZoom.get(zoom);
  if (
    !limits ||
    column < limits.minTileCol ||
    column > limits.maxTileCol ||
    row < limits.minTileRow ||
    row > limits.maxTileRow
  ) {
    return undefined;
  }
  return new URL(`${TILESET_PATH}/${zoom}/${row}/${column}.mvt`, document.baseURI).href;
}

/** Local Mapbox GL v8 style shared by the geographic and reprojected examples. */
export const municipalityStyle = {
  version: 8,
  sources: {
    municipalities: {
      type: 'vector',
      tiles: [`${TILESET_PATH}/{z}/{y}/{x}.mvt`],
      minzoom: 4,
      maxzoom: MAX_SOURCE_ZOOM,
      tileSize: LOGICAL_TILE_SIZE,
    },
  },
  layers: [
    {
      id: 'municipality-fill',
      type: 'fill',
      source: 'municipalities',
      'source-layer': 'municipalities',
      paint: { 'fill-color': '#f7f7e9' },
    },
    {
      id: 'municipality-boundaries',
      type: 'line',
      source: 'municipalities',
      'source-layer': 'municipalities',
      paint: {
        'line-color': '#8c8b8b',
        'line-width': ['interpolate', ['linear'], ['zoom'], 4, 0.6, 10, 1.6],
      },
    },
    {
      id: 'background',
      type: 'background',
      paint: { 'background-color': '#d1d1d1' },
    },
  ],
} as const;
vector-tiles-4326.ts
import { AfterViewInit, ChangeDetectionStrategy, Component, OnDestroy, signal, viewChild } from '@angular/core';
import { applyBackground, applyStyle } from 'ol-mapbox-style';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  FormatMVTComponent,
  LayerVectorTileComponent,
  MapComponent,
  SourceVectorTileComponent,
  TileGridComponent,
  ViewComponent,
} from 'cc-openlayers';
import {
  geographicTileGrid,
  geographicTileGridDeclaration,
  municipalityAttributionOptions,
  municipalityFixtureExtent,
  municipalityStyle,
  municipalityTileUrl,
} from './vector-tiles-4326.shared';

/** The local PRG MVT fixture rendered in its WorldCRS84Quad geographic projection. */
@Component({
  selector: 'app-vector-tiles-4326',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    FormatMVTComponent,
    LayerVectorTileComponent,
    MapComponent,
    SourceVectorTileComponent,
    TileGridComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px" [ariaLabel]="ariaLabel">
      <aol-interaction-default />
      <aol-control-defaults [attributionOptions]="attributionOptions" />
      <aol-view projection="EPSG:4326" [zoom]="12" [extent]="municipalityFixtureExtent" [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>
    }
  `,
})
export class VectorTiles4326 implements AfterViewInit, OnDestroy {
  protected readonly ariaLabel = 'Geographic vector tiles over Kraków';
  protected readonly grid = geographicTileGridDeclaration;
  protected readonly attributionOptions = municipalityAttributionOptions;
  protected readonly municipalityFixtureExtent = municipalityFixtureExtent;
  protected readonly tileUrlFunction = municipalityTileUrl;

  protected readonly styleError = signal(false);
  private readonly layer = viewChild.required(LayerVectorTileComponent);
  private destroyed = false;

  ngAfterViewInit(): void {
    const layer = this.layer().instance;
    void Promise.all([
      applyStyle(layer, municipalityStyle, {
        resolutions: geographicTileGrid.getResolutions(),
        updateSource: false,
      }),
      applyBackground(layer, municipalityStyle),
    ]).catch(() => {
      if (!this.destroyed) this.styleError.set(true);
    });
  }

  ngOnDestroy(): void {
    this.destroyed = true;
  }
}

Architecture and OpenLayers mechanics

aol-source-vectortile (projection="EPSG:4326") declares <aol-tilegrid> explicitly with 512-pixel tileSize, global origin [-180, 90], and halved resolutions starting at 180 / 512 across matrix levels 4–10.

In ngAfterViewInit, applyStyle (updateSource: false, passing geographicTileGrid.getResolutions()) and applyBackground from ol-mapbox-style style the aol-layer-vectortile without overwriting its custom geographic source.

How it works

  • Local PRG municipality MVT cells are served on an explicit 512-pixel EPSG:4326 grid styled via a local Mapbox GL v8 document.
  • Using 512-pixel logical tiles with origin [-180, 90] and top resolution 180 / 512 preserves identical geographic cell footprints to 256-pixel WorldCRS84Quad matrices.
  • Passing the source grid’s resolution array into applyStyle (updateSource: false) aligns Mapbox GL zoom expressions with geographic scale.
  • View extent bounds navigation around Kraków while keeping global tile matrix coordinates intact.

Pitfalls

  • Doubling tileSize from 256 to 512 without halving the resolution ladder doubles the geographic footprint of every cell and requests completely wrong {z}/{x}/{y} files.
  • Never replace the global [-180, 90] grid origin with your local city bounding box—use view/grid extent to restrict requests while keeping matrix row/column numbering global.

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.