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.

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.tsimport 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.tsimport { 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;
}
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
canvas-tiles-tms.react.tsximport { useState } from 'react';
import type { FeatureLike } from 'ol/Feature.js';
import OLVectorTileSource from 'ol/source/VectorTile.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
Map,
TileDebugSource,
TileLayer,
useMVTFormat,
useTileGrid,
VectorTileLayer,
VectorTileSource,
View,
} from 'cc-openlayers/react';
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. */
export function CanvasTilesTmsReact() {
const tileGrid = useTileGrid({ maxZoom: municipalityMaxZoom, tileSize: municipalityTileSize });
const format = useMVTFormat();
const [vectorSource, setVectorSource] = useState<OLVectorTileSource<FeatureLike> | null>(null);
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls attributionOptions={{ collapsible: false }} />
<View projection="EPSG:3857" zoom={9}>
<Coordinate x={19.9368} y={50.0614} srid="EPSG:4326" />
</View>
<VectorTileLayer declutter style={municipalityStyle}>
<VectorTileSource
ref={setVectorSource}
format={format}
projection="EPSG:3857"
maxZoom={municipalityMaxZoom}
tileGrid={tileGrid}
tileUrlFunction={municipalityTileUrl}
wrapX={false}
attributions="Boundaries: PRG, Główny Urząd Geodezji i Kartografii"
/>
</VectorTileLayer>
<TileLayer>
<TileDebugSource
source={vectorSource ?? undefined}
tileGrid={tileGrid}
projection="EPSG:3857"
wrapX={false}
zDirection={1}
template={tileDebugTemplate}
/>
</TileLayer>
</Map>
);
}canvas-tiles-tms.shared.tsimport 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;
};How the React version works
Local PRG municipality boundaries around Kraków rendered from Mapbox Vector Tiles on a global Web Mercator grid. A debug layer shows the zoom, column and south-origin TMS row of each tile.
What both versions share
Both adapters compose the existing vector-tile layer, MVT format and tile-debug APIs. The vector source and debug source share the same 512-pixel grid, projection and zoom limits. The debug template uses {-y}, and zDirection: 1 selects the matching tile level between resolutions. The static fixture comes from the existing PRG municipality GeoJSON and make-ogc-tilesets.mjs. Its global row conversion is 2 ** z - y - 1. The source restricts requests using the generated per-level limits while retaining the global grid; the data extent does not become a new tile-grid origin. Geometry generation preserves separate polygon exteriors and holes, and includes a clipping buffer.
From Angular to React
| Angular | React |
|---|---|
<aol-source-vectortile [tileUrlFunction]="tileUrlFunction"> | <VectorTileSource tileUrlFunction={municipalityTileUrl}> |
<aol-format-mvt /> | useMVTFormat() supplies the format |
<aol-tilegrid> creates the shared grid | useTileGrid() creates the shared grid |
<aol-source-tiledebug [wrapX]="false" [zDirection]="1"> | <TileDebugSource wrapX={false} zDirection={1}> |
Who creates, updates and disposes
The Angular template and React tree share the source configuration and style instead of implementing separate tile coordinate rules. Each map, layer and source adapter owns its OpenLayers object and removes it through its normal lifecycle. React uses the existing hooks and context bindings; Angular forwards the same public options through component inputs.
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.
Related examples
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.