Vector data · Angular, React and OpenLayers

Canvas vector tiles in TMS order

Render local MVT municipality vector tiles in south-origin TMS row order and inspect z/x/-y tile grid coordinates in Angular and React.

Municipality boundaries around Kraków with zoom, column and south-origin TMS row labels on the vector tile grid.
A screenshot of the example. Municipal boundaries: Państwowy Rejestr Granic © GUGiK.

What this example shows

The map displays municipal administrative boundaries around Kraków from a local Mapbox Vector Tile pyramid while overlaying a crisp coordinate debug grid directly on top of the canvas. Every visible 512-pixel square is outlined and labelled with its zoom level, column index and south-origin TMS row number so you can verify spatial alignment at a glance.

Panning and zooming across levels 0 through 15 demonstrates how vector polygons and interior holes stay seamlessly stitched across tile borders even when the server stores rows counted upward from the southern edge of the Web Mercator world.

When you need it

Geospatial teams frequently integrate legacy OSGeo Tile Map Service caches, offline mbtiles exports or custom static tile pyramids whose row index starts in the south rather than the north.

When a vector or raster tile layer appears vertically mirrored, shifted by several hundred kilometres or completely blank over your study area, the fastest diagnostic is comparing the requested URL row index against an on-screen debug grid configured with the exact same tile grid. Pairing a TMS-ordered vector tile source with a matching debug overlay isolates row-inversion mistakes immediately without inspecting dozens of network requests by hand.

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.

canvas-tiles-tms.shared.ts
import type { UrlFunction } from 'ol/Tile.js';
import municipalityTileMetadata from '../../../assets/krakow/municipality-tiles/WebMercator512TMS/metadata.json';

export const municipalityTileDirectory = 'assets/krakow/municipality-tiles/WebMercator512TMS';
export const municipalityTileSize = 512;
export const municipalityMaxZoom = 15;
export const tileDebugTemplate = 'z:{z} x:{x} y:{-y}';

/** The generated local tile bounds for each zoom in the global EPSG:3857 XYZ grid. */
export const municipalityTileBounds: typeof municipalityTileMetadata.grid.bounds = municipalityTileMetadata.grid.bounds;

/** The local MVT URL in global TMS row order; coordinates outside the generated bounds are not requested. */
export const municipalityTileUrl: UrlFunction = ([z, x, y]) => {
  const bounds = municipalityTileBounds[z];
  if (!bounds || bounds.z !== z || x < bounds.minX || x > bounds.maxX || y < bounds.minY || y > bounds.maxY) {
    return undefined;
  }
  const tmsY = 2 ** z - y - 1;
  return new URL(`${municipalityTileDirectory}/${z}/${x}/${tmsY}.mvt`, document.baseURI).href;
};
canvas-tiles-tms.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import type TileGrid from 'ol/tilegrid/TileGrid';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  FormatMVTComponent,
  LayerTileComponent,
  LayerVectorTileComponent,
  MapComponent,
  SourceTileDebugComponent,
  SourceVectorTileComponent,
  TileGridComponent,
  ViewComponent,
} from 'cc-openlayers';
import { municipalityStyle } from '../declutter-group/declutter-group.shared';
import {
  municipalityMaxZoom,
  municipalityTileSize,
  municipalityTileUrl,
  tileDebugTemplate,
} from './canvas-tiles-tms.shared';

/** Kraków's municipality MVTs in a global 512 pixel Web Mercator grid with TMS URLs and tile labels. */
@Component({
  selector: 'app-canvas-tiles-tms',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    FormatMVTComponent,
    LayerTileComponent,
    LayerVectorTileComponent,
    MapComponent,
    SourceTileDebugComponent,
    SourceVectorTileComponent,
    TileGridComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults [attributionOptions]="attributionOptions" />
      <aol-view projection="EPSG:3857" [zoom]="9">
        <aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-vectortile [declutter]="true" [style]="style">
        <aol-source-vectortile
          projection="EPSG:3857"
          [maxZoom]="maxZoom"
          [wrapX]="false"
          [tileUrlFunction]="tileUrlFunction"
          attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
        >
          <aol-format-mvt />
          <aol-tilegrid [maxZoom]="maxZoom" [tileSize]="tileSize" (instanceChange)="captureTileGrid($event)" />
        </aol-source-vectortile>
      </aol-layer-vectortile>
      <aol-layer-tile>
        <aol-source-tiledebug
          [tileGrid]="tileGrid"
          projection="EPSG:3857"
          [wrapX]="false"
          [zDirection]="1"
          [template]="tileDebugTemplate"
        />
      </aol-layer-tile>
    </aol-map>
  `,
})
export class CanvasTilesTms {
  protected readonly maxZoom = municipalityMaxZoom;
  protected readonly tileSize = municipalityTileSize;
  protected readonly tileUrlFunction = municipalityTileUrl;
  protected readonly style = municipalityStyle;
  protected readonly tileDebugTemplate = tileDebugTemplate;
  protected readonly attributionOptions = { collapsible: false };
  protected tileGrid?: TileGrid;

  protected captureTileGrid(tileGrid: TileGrid): void {
    this.tileGrid = tileGrid;
  }
}

Architecture and OpenLayers mechanics

Standard XYZ and OGC Web Mercator pyramids place row 0 at the northern top edge of the projection extent, whereas OSGeo TMS counts row 0 from the southern bottom edge. At zoom level z, converting a north-origin row y into its TMS equivalent evaluates 2 to the power of z, minus y, minus 1—a convention OpenLayers represents in URL templates with the {-y} placeholder.

To keep polygon rendering sharp and artifact-free, the local PRG municipality dataset is pre-sliced on the full global Web Mercator grid using 512-pixel tiles and per-tile clip buffers. Sharing the exact same tile grid and projection instance between the vector tile source and the debug source guarantees that every wireframe cell and row label matches the underlying vector requests pixel for pixel.

How it works

  • The local MVT pyramid encodes Polish Register of Borders (PRG) municipalities around Kraków on a global Web Mercator grid with 512-pixel tiles across zoom levels 0–15.
  • TMS row addressing inverts the standard north-origin row index: for zoom level z, the requested TMS row equals 2 to the power of z, minus the XYZ row, minus one.
  • A companion TileDebug layer reuses the vector source’s exact tile grid and projection so its rendered wireframe and south-origin labels align with every loaded vector tile.
  • Offline tile generation clips multipart municipal polygons and interior enclaves with a safety buffer around each tile edge, preventing double strokes or missing boundary segments along tile seams.

Pitfalls

  • Always keep the full global Web Mercator grid extent when serving a regional TMS extract; shrinking the tileGrid extent to a local bounding box alters the total row count per zoom level and breaks the south-origin row inversion formula.
  • Because this offline fixture only bundles tiles intersecting Kraków and neighbouring municipalities, panning outside the generated coverage window intentionally skips network requests rather than failing.
  • Do not mix a default 256-pixel debug grid with a 512-pixel vector tile grid—mismatched tile sizes shift zoom indices by one level and mislabel every cell.

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.