Layers · Angular, React and OpenLayers

Pan and zoom a static image

Display non-geographic floor plans, diagrams or screenshots in OpenLayers using a custom pixel-based Projection and an ImageStatic source.

A screenshot of GeoAtlas shown as a map that pans and zooms.
A screenshot of the example. Image: a screenshot of GeoAtlas.

What this example shows

An application screenshot (1280 × 800 pixels) mounts inside OpenLayers in a projection of its own, so its coordinates count image pixels instead of Earth longitude and latitude.

When you need it

Building floor plans, stadium seating charts, engineering schematics, historical manuscript scans and industrial P&ID diagrams have no geographic CRS yet benefit enormously from OpenLayers’ pan, zoom and vector-annotation tools.

Defining a custom pixel projection lets you overlay interactive vector pins, measurement polygons and HTML popups in straightforward [x, y] image pixel coordinates.

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-static.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import type { Extent } from 'ol/extent';
import Projection from 'ol/proj/Projection';
import { LayerImageComponent, MapComponent, SourceImageStaticComponent, ViewComponent } from 'cc-openlayers';

/** One image, a screenshot of GeoAtlas, as a map in a pixel projection of its own: panned and zoomed like any map. */
@Component({
  selector: 'app-image-static',
  imports: [LayerImageComponent, MapComponent, SourceImageStaticComponent, ViewComponent],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-view [projection]="projection" [zoom]="2" [center]="[640, 400]" />
      <aol-layer-image [extent]="extent">
        <aol-source-imagestatic url="assets/geoatlas.webp" [projection]="projection" [imageExtent]="extent" />
      </aol-layer-image>
    </aol-map>
  `,
})
export class ImageStatic {
  /** The image's size in pixels: its coordinates run from the lower left corner. */
  protected readonly extent: Extent = [0, 0, 1280, 800];
  protected readonly projection = new Projection({ code: 'geoatlas-image', units: 'pixels', extent: this.extent });
}

Architecture and OpenLayers mechanics

Instead of default Spherical Mercator, the component instantiates an OpenLayers Projection configured with units: 'pixels' and an extent matching the bitmap’s dimensions ([0, 0, 1280, 800], measured from the lower-left origin).

Both aol-view and aol-source-imagestatic (imageExtent) reference that exact pixel projection so view centre coordinates, zoom resolutions and any vector overlays map directly to image pixels.

How it works

  • A custom OpenLayers Projection with units: 'pixels' and [0, 0, width, height] bounds replaces geographic coordinates.
  • aol-source-imagestatic stretches the single bitmap across imageExtent (1280 × 800 pixels anchored at the bottom-left corner).
  • Sharing the pixel projection on the view expresses camera centre and resolution directly in image pixels.

Pitfalls

  • Always match imageExtent aspect ratio exactly to the bitmap’s natural pixel dimensions (naturalWidth × naturalHeight), otherwise OpenLayers stretches or squashes the drawing.
  • Browsers decode an ImageStatic file into memory all at once: for scans larger than ~4000 × 4000 pixels, slice the artwork into a Zoomify or IIIF tile pyramid instead so mobile GPUs do not hit texture limits.

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.