Layers · Angular, React and OpenLayers

Render vector data as an image

Accelerate dense polygon panning in OpenLayers with VectorImageLayer, a 2x imageRatio buffer and hit-detected hover highlights in Angular.

The voivodeships of southern Poland, each in its own colour, on a dark blue background at zoom 7, Małopolska outlined in white under the pointer and named below the map.
A screenshot of the example. Voivodeships: Państwowy Rejestr Granic © GUGiK.

What this example shows

Poland’s 16 voivodeship polygons—with thousands of detailed border vertices—render in a 16-colour categorical palette over a dark navy background at zoom 7. Dragging and zooming stay effortlessly fluid because polygons are rasterised once into an off-screen image that glides across frames.

Hovering with a mouse (or tapping on touch screens) still identifies the exact voivodeship beneath the pointer, outlines its border in crisp white and displays its name below the map.

When you need it

Choropleth maps of municipalities, soil polygons, cadastral zones or Natura 2000 habitats can bog down 60 fps panning when a standard VectorLayer re-strokes tens of thousands of vertices on every intermediate drag frame.

VectorImageLayer gives you the best of both worlds: static-image pan speed during camera motion plus full client-side vector hit detection and dynamic styling once settled.

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.

image-vector-layer.ts
import { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerVectorComponent,
  LayerVectorImageComponent,
  MapComponent,
  SourceGeoJSONComponent,
  SourceVectorComponent,
  StyleComponent,
  StyleStrokeComponent,
  ViewComponent,
} from 'cc-openlayers';
import type Feature from 'ol/Feature';
import type { FeatureLike } from 'ol/Feature';
import type MapBrowserEvent from 'ol/MapBrowserEvent';
import Fill from 'ol/style/Fill';
import Style from 'ol/style/Style';

/** The colour of each voivodeship, by its position in code order. */
const PALETTE = [
  '#4e79a7',
  '#f28e2b',
  '#e15759',
  '#76b7b2',
  '#59a14f',
  '#edc948',
  '#b07aa1',
  '#ff9da7',
  '#9c755f',
  '#bab0ac',
  '#86bcb6',
  '#d37295',
  '#fabfd2',
  '#b6992d',
  '#499894',
  '#79706e',
];

/** The voivodeships rendered as one image by a vector image layer; the one under the pointer is outlined and named. */
@Component({
  selector: 'app-image-vector-layer',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerVectorComponent,
    LayerVectorImageComponent,
    MapComponent,
    SourceGeoJSONComponent,
    SourceVectorComponent,
    StyleComponent,
    StyleStrokeComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px" (pointerMove)="move($event)" (olClick)="showFeatureInfo($event)">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="7"><aol-coordinate [x]="19.9368" [y]="50.0614" srid="EPSG:4326" /></aol-view>
      <aol-layer-vectorimage background="#1a2b39" [imageRatio]="2" [style]="style">
        <aol-source-geojson url="assets/poland/voivodeships.geojson" featureProjection="EPSG:3857" />
      </aol-layer-vectorimage>
      <aol-layer-vector>
        <aol-style><aol-style-stroke color="rgba(255, 255, 255, 0.7)" [width]="2" /></aol-style>
        <aol-source-vector />
      </aol-layer-vector>
    </aol-map>
    <div class="example-controls">
      <span>
        Voivodeship <output>{{ name() || '–' }}</output>
      </span>
    </div>
  `,
})
export class ImageVectorLayer {
  readonly name = signal('');
  protected readonly style = (feature: FeatureLike) =>
    new Style({ fill: new Fill({ color: PALETTE[Number(feature.get('code')) / 2 - 1] ?? '#eeeeee' }) });

  private readonly map = viewChild.required(MapComponent);
  private readonly overlay = viewChild.required(SourceVectorComponent);
  private highlighted: Feature | undefined;

  protected move(event: MapBrowserEvent): void {
    if (!event.dragging) this.showFeatureInfo(event);
  }

  protected showFeatureInfo(event: MapBrowserEvent): void {
    const feature = this.map().instance.forEachFeatureAtPixel(event.pixel, (hit) => hit) as Feature | undefined;
    this.name.set(feature?.get('name') ?? '');
    if (feature === this.highlighted) return;
    const overlay = this.overlay().instance;
    if (this.highlighted) overlay.removeFeature(this.highlighted);
    if (feature) overlay.addFeature(feature);
    this.highlighted = feature;
  }
}

Architecture and OpenLayers mechanics

aol-layer-vectorimage rasterises its GeoJSON source into a single off-screen canvas over the configured background colour, then translates and scales that cached bitmap cheaply while the camera pans, zooms or animates—re-rendering sharp vector edges only when movement stops. Setting [imageRatio] to 2 sizes that off-screen canvas at twice the viewport width and height so drags up to half a screen wide never expose unrendered blank margins.

For interactive feedback without invalidating the heavy base image on every pixel move, forEachFeatureAtPixel queries the underlying vector geometries and adds the hovered feature itself to a lightweight second vector layer drawn in white.

How it works

  • aol-layer-vectorimage caches styled GeoJSON polygons as a single bitmap over background and transforms that bitmap cheaply during pans and zooms.
  • Setting [imageRatio] to 2 renders a 2× wider and taller off-screen buffer so moderate drags show zero blank edges before the next settled redraw.
  • A categorical style function assigns each voivodeship one of 16 palette colours from its official two-digit TERYT code (02–32).
  • forEachFeatureAtPixel detects the voivodeship under the pointer while a lightweight overlay vector layer draws its white highlight border.
  • (pointerMove) skips hit detection mid-drag for smoothness, while (olClick) supports tap selection on hoverless touch screens.

Pitfalls

  • During active zoom or pan gestures the cached bitmap stretches on screen, causing boundary strokes to thicken or soften briefly until the gesture settles and triggers a fresh vector rasterisation.
  • Increasing [imageRatio] scales off-screen pixel count quadratically—a ratio of 2 renders four times the viewport area—so avoid values above 2 on high-DPI mobile screens.

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.