Tile and image services · Angular, React and OpenLayers
An orthophoto WMTS at zoom 18
Display sub-metre WMTS aerial orthophotography at zoom 18 in OpenLayers with exact Web Mercator origin alignment on Kraków’s Main Square.

What this example shows
Zoomed all the way to level 18 directly above Kraków’s Main Square and the Cloth Hall (Sukiennice), GUGiK’s national WMTS orthophotomap fills the entire viewport as a standalone sub-metre aerial base layer—resolving individual skylights, market umbrellas, tram rails and pavement slabs.
When you need it
Cadastral boundary verification, rooftop solar layout, kerbside inventory and street-furniture mapping operate at zoom levels 18–19 where a single pixel spans less than 40 centimetres on the ground.
At sub-metre scales, even a tiny rounding shortcut in a manual WMTS grid origin shifts aerial imagery visibly against surveyed vector parcels.
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.
wmts-ign.tsimport { ChangeDetectionStrategy, Component } from '@angular/core';
import { getTopLeft, getWidth } from 'ol/extent';
import { EXTENT } from 'ol/proj/epsg3857';
import {
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceTileWMTSComponent,
TileGridWMTSComponent,
ViewComponent,
} from 'cc-openlayers';
const maxResolution = getWidth(EXTENT) / 256;
/**
* The national orthophoto WMTS layer (a national mapping agency's service) built from fixed options, close up on
* Kraków's Main Square at zoom 18 of the service's 20 levels.
*/
@Component({
selector: 'app-wmts-ign',
imports: [
CoordinateComponent,
DefaultControlComponent,
DefaultInteractionComponent,
LayerTileComponent,
MapComponent,
SourceTileWMTSComponent,
TileGridWMTSComponent,
ViewComponent,
],
changeDetection: ChangeDetectionStrategy.OnPush,
template: `
<aol-map height="480px">
<aol-interaction-default />
<aol-control-defaults />
<aol-view [zoom]="18">
<aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
</aol-view>
<aol-layer-tile>
<aol-source-tilewmts
attributions='<a href="https://www.geoportal.gov.pl/" target="_blank">GUGiK</a>'
url="https://mapy.geoportal.gov.pl/wss/service/PZGIK/ORTO/WMTS/StandardResolution"
layer="ORTOFOTOMAPA"
matrixSet="EPSG:3857"
format="image/jpeg"
projection="EPSG:3857"
[style]="'default'"
>
<aol-tilegrid-wmts [origin]="origin" [resolutions]="resolutions" [matrixIds]="matrixIds" />
</aol-source-tilewmts>
</aol-layer-tile>
</aol-map>
`,
})
export class WmtsIgn {
/** The corner of the matrix set: rounded to whole metres, the tiles would lie a pixel off at zoom 19. */
protected readonly origin = getTopLeft(EXTENT);
protected readonly resolutions = Array.from({ length: 20 }, (_, i) => maxResolution / 2 ** i);
protected readonly matrixIds = Array.from({ length: 20 }, (_, i) => `EPSG:3857:${i}`);
} 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.
wmts-ign.react.tsximport { getTopLeft, getWidth } from 'ol/extent.js';
import { EXTENT } from 'ol/proj/epsg3857.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
Map,
TileLayer,
View,
WMTSSource,
useWMTSTileGrid,
} from 'cc-openlayers/react';
const maxResolution = getWidth(EXTENT) / 256;
/** The corner of the matrix set: rounded to whole metres, the tiles would lie a pixel off at zoom 19. */
const origin = getTopLeft(EXTENT);
const resolutions = Array.from({ length: 20 }, (_, i) => maxResolution / 2 ** i);
const matrixIds = Array.from({ length: 20 }, (_, i) => `EPSG:3857:${i}`);
const gridOptions = { origin, resolutions, matrixIds };
/**
* The national orthophoto WMTS layer (a national mapping agency's service) built from fixed options, close up on
* Kraków's Main Square at zoom 18 of the service's 20 levels.
*/
export function WmtsIgn() {
const tileGrid = useWMTSTileGrid(gridOptions);
return (
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={18}>
<Coordinate x={19.9373} y={50.0617} srid="EPSG:4326" />
</View>
<TileLayer>
<WMTSSource
attributions='<a href="https://www.geoportal.gov.pl/" target="_blank">GUGiK</a>'
url="https://mapy.geoportal.gov.pl/wss/service/PZGIK/ORTO/WMTS/StandardResolution"
layer="ORTOFOTOMAPA"
matrixSet="EPSG:3857"
format="image/jpeg"
projection="EPSG:3857"
style="default"
tileGrid={tileGrid}
/>
</TileLayer>
</Map>
);
}How the React version works
An orthophoto from a WMTS whose grid origin lies exactly at the corner of the service's matrix set; rounded to metres, it would shift the tiles by a pixel at zoom 19.
What both versions share
OpenLayers renders the map and handles the interactions; the cc-openlayers/core layer gives both adapters the same view binding (MapViewBinding) and the same conversion of coordinates from EPSG:4326 to the map's projection.
From Angular to React
| Angular | React |
|---|---|
<aol-source-tilewmts> with <aol-tilegrid-wmts> inside | <WMTSSource tileGrid={tileGrid}> with useWMTSTileGrid(...) |
Who creates, updates and disposes
Map creates the ol/Map in useLayoutEffect and disposes of it on unmount; each layer, source and interaction component adds its object to the parent it gets from context and removes it in its effect's cleanup, as ngOnDestroy does in Angular.
Architecture and OpenLayers mechanics
At zoom 18, one Web Mercator pixel spans roughly 0.60 projection units—under 0.40 ground metres at Kraków’s 50° N latitude. Setting [origin] on the WMTS tile grid to getTopLeft(EXTENT) uses the exact IEEE-754 corner of the Spherical Mercator world (-20037508.342789244, 20037508.342789244), whereas rounding that constant to whole metres would introduce a ~0.34 m shift exceeding one full pixel at zoom 19.
[resolutions] and [matrixIds] cover all 20 pyramid levels from global zoom 0 down to street zoom 19.
How it works
- Opening at zoom 18 over the Main Square delivers ~0.6 m Web Mercator resolution (under 0.4 m on the ground in Kraków).
- Setting
[origin]viagetTopLeft(EXTENT)preserves sub-metre floating-point precision instead of rounding Web Mercator’s corner to whole metres. [resolutions]and[matrixIds]declare the service’s 20 pyramid levels down to zoom 19.- Running the orthophoto as the sole layer dedicates the entire viewport to high-resolution aerial inspection.
Pitfalls
- Because WMTS orthophotos are served as opaque JPEGs for compact file size, border tiles outside national coverage contain solid black or white padding that a rectangular layer extent cannot trim along irregular borders.
- Panning or zooming into matrix cells outside GUGiK’s published coverage often returns HTTP 200 containing an OGC XML TileOutOfRange exception rather than an image, leaving those tiles blank.
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.