Tile and image services · Angular, React and OpenLayers

WMS tiles of 512 by 256 pixels

Configure a custom 512x256 rectangular OpenLayers TileGrid bounded to Poland for tiled WMS requests and inspect seams with a TileDebug layer.

Poland at zoom 6 with its voivodeships' boundaries in pink over OpenStreetMap, in two wide tiles that the tile debug layer outlines and numbers; the voivodeships they split are named in each.
A screenshot of the example. Voivodeships: Państwowy Rejestr Granic © GUGiK. Map data © OpenStreetMap contributors.

What this example shows

At zoom 6 across Poland, voivodeship boundaries from GUGiK’s WMS load in wide rectangular 512 × 256 pixel tiles anchored to the northwest corner of Poland’s bounding box, while a matching TileDebug wireframe outlines and labels the exact two stacked tiles covering the country.

When you need it

Standard 256 × 256 tiles can generate excessive HTTP request counts across wide widescreen monitors—and standard global WMS grids still evaluate coordinates outside your national dataset.

Because dynamic OGC WMS servers draw arbitrary BBOX and WIDTH/HEIGHT combinations on demand, a custom rectangular TileGrid halves horizontal request counts and restricts grid indexing strictly to your coverage extent.

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.

wms-custom-tilegrid-512x256.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerTileComponent,
  MapComponent,
  SourceOsmComponent,
  SourceTileDebugComponent,
  SourceTileWMSComponent,
  ViewComponent,
} from 'cc-openlayers';
import { getWidth } from 'ol/extent';
import { get as getProjection } from 'ol/proj';
import type Projection from 'ol/proj/Projection';
import TileGrid from 'ol/tilegrid/TileGrid';

/**
 * Poland's voivodeship boundaries requested in 512 by 256 pixel tiles over a tile grid limited to the country, with
 * the grid's tiles outlined and numbered above them.
 */
@Component({
  selector: 'app-wms-custom-tilegrid-512x256',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerTileComponent,
    MapComponent,
    SourceOsmComponent,
    SourceTileDebugComponent,
    SourceTileWMSComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="6"><aol-coordinate [x]="19.4" [y]="52.1" srid="EPSG:4326" /></aol-view>
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
      <aol-layer-tile>
        <aol-source-tilewms
          url="https://mapy.geoportal.gov.pl/wss/service/PZGIK/PRG/WMS/AdministrativeBoundaries"
          [params]="{ LAYERS: 'A01_Granice_wojewodztw', TILED: true }"
          serverType="mapserver"
          [tileGrid]="tileGrid"
          attributions="Administrative boundaries © GUGiK"
        />
      </aol-layer-tile>
      <aol-layer-tile><aol-source-tiledebug [tileGrid]="tileGrid" /></aol-layer-tile>
    </aol-map>
  `,
})
export class WmsCustomTilegrid512x256 {
  protected readonly tileGrid = createTileGrid();
}

/** Resolutions of the Web Mercator world in 256 pixel tiles, an extent around Poland and tiles 512 wide, 256 high. */
function createTileGrid(): TileGrid {
  const webMercator = getProjection('EPSG:3857') as Projection;
  const startResolution = getWidth(webMercator.getExtent()) / 256;
  return new TileGrid({
    extent: [1525077, 6207260, 2771855, 7381298],
    resolutions: Array.from({ length: 22 }, (_, zoom) => startResolution / Math.pow(2, zoom)),
    tileSize: [512, 256],
  });
}

Architecture and OpenLayers mechanics

An explicit OpenLayers TileGrid specifies tileSize: [512, 256], Poland’s projected Web Mercator extent, and 22 resolution steps. With no separate origin passed, tile indexing starts cleanly at the top-left (northwest) corner of Poland’s extent.

Passing [tileGrid] both to aol-source-tilewms and to a companion aol-source-tiledebug layer lets you verify the exact rectangular cell boundaries—including how provinces straddling the horizontal seam (such as mazowieckie and łódzkie) receive labels in both tiles.

How it works

  • TileGrid defines rectangular tileSize: [512, 256] cells across Poland’s extent and 22 Web Mercator resolution levels.
  • Omitting a custom origin anchors tile (0, 0) at the northwest corner of Poland’s bounding box.
  • [tileGrid] drives aol-source-tilewms to request 512 × 256 GetMap images strictly inside Poland.
  • Sharing the identical [tileGrid] with aol-source-tiledebug visualises tile seams and indices directly over the boundaries.

Pitfalls

  • Custom non-square grids anchored to a local extent will not match pre-seeded global 256 × 256 XYZ/WMTS caches—use them only against dynamic WMS endpoints or caches seeded with the identical grid.
  • Remember HiDPI multiplication against server MaxWidth / MaxHeight limits in GetCapabilities: on a 2x Retina screen, a 512 × 256 logical tile requests 1024 × 512 pixels, which can exceed a stricter server’s MaxWidth / MaxHeight.
  • Independent per-tile labelling names polygons crossed by a tile seam once in each tile.

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.