Tile and image services · Angular, React and OpenLayers

MapServer's own CGI interface

Render legacy native MapServer mode=map CGI layers in geographic EPSG:4326 degrees over reprojected OpenStreetMap tiles within Poland bounds.

Poland at zoom 6 in geographic degrees: the MapServer demo's Blue Marble with its borders and cities, Warsaw in red, within the country's bounding box, over OpenStreetMap.
A screenshot of the example. Map images: MapServer's demonstration server (GatewayGeo), with NASA's Blue Marble, world country boundaries and cities.

What this example shows

Framed over Poland at zoom 6 in geographic EPSG:4326 degrees, MapServer’s native non-WMS CGI endpoint (mode=map) draws Blue Marble land imagery, borders and major cities inside Poland’s bounding box over a client-reprojected OpenStreetMap backdrop.

When you need it

Long-lived government and academic intranet systems occasionally expose older .map configurations exclusively through MapServer’s classic CGI query parameters (mode=map&mapext=...&layers=...) without OGC WMS wrappers enabled.

OpenLayers’ dedicated MapServer loader integrates those legacy endpoints cleanly alongside modern XYZ or vector layers during incremental migrations.

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.

mapserver-cgi.ts
import { ChangeDetectionStrategy, Component } from '@angular/core';
import {
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerImageComponent,
  LayerTileComponent,
  MapComponent,
  SourceImageComponent,
  SourceOsmComponent,
  ViewComponent,
} from 'cc-openlayers';
import { getCenter } from 'ol/extent';
import { createLoader } from 'ol/source/mapserver';

const mapserverUrl = 'https://demo.mapserver.org/cgi-bin/wms?';
/** Poland's bounding box, in the degrees of the demo's map file and of the view. */
const bounds = [14.07, 49.0, 24.15, 54.84];

/**
 * An image of MapServer's CGI interface (`mode=map`), not of its WMS: the demo's world map file draws Blue Marble,
 * country borders and cities for the map's extent, and the layer's extent keeps the image within Poland's bounding
 * box, over OpenStreetMap reprojected into the view's degrees.
 */
@Component({
  selector: 'app-mapserver-cgi',
  imports: [
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerImageComponent,
    LayerTileComponent,
    MapComponent,
    SourceImageComponent,
    SourceOsmComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view projection="EPSG:4326" [center]="center" [zoom]="6" />
      <aol-layer-tile><aol-source-osm /></aol-layer-tile>
      <aol-layer-image [extent]="bounds">
        <aol-source-image [loader]="loader" attributions="MapServer demo: NASA Blue Marble" />
      </aol-layer-image>
    </aol-map>
  `,
})
export class MapserverCgi {
  protected readonly bounds = bounds;
  protected readonly center = getCenter(bounds);
  protected readonly loader = createLoader({
    url: mapserverUrl,
    params: { layers: 'bluemarble country_bounds cities' },
  });
}

Architecture and OpenLayers mechanics

createLoader from OpenLayers’ MapServer module builds mode=map requests passing space-delimited layers, pixel image size and map extent—relying on the .map file’s native degree coordinate system without a WMS CRS parameter.

Layer [extent] restricts CGI requests to bounds (Poland’s degree box, centred initially via getCenter), while aol-source-osm underneath demonstrates OpenLayers automatically warping Web Mercator street tiles into the view’s EPSG:4326 degree projection.

How it works

  • OpenLayers’ MapServer createLoader speaks native mode=map CGI parameters directly from extent and pixel dimensions.
  • layers lists .map layer names separated by spaces rather than WMS commas.
  • Because CGI mode=map uses the server mapfile’s native degree CRS, the OpenLayers view runs in matching degrees.
  • Layer [extent] fences requests to bounds (centred via getCenter), while aol-source-osm reprojects Web Mercator tiles into degrees underneath.

Pitfalls

  • Prefer standard OGC WMS (mapserver-wms) whenever you control server configuration—native CGI mode=map lacks standardised capabilities discovery, GetFeatureInfo and projection negotiation.
  • Unlike WMS with serverType mapserver, the CGI loader requests Retina pixel counts without passing MAP_RESOLUTION, causing server-drawn point symbols and text to appear smaller on 2x displays.

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.