Raster, GeoTIFF and WebGL · Angular, React and OpenLayers

Hue, chroma and lightness of a map

Transform OpenTopoMap basemap hue, chroma and lightness perceptually in HCL colour space using an OpenLayers RasterSource worker and sliders.

OpenTopoMap's map of Kraków with its hue turned by 120°: woods and meadows in cyan and blue instead of green, main roads in teal, and the hue, chroma and lightness sliders below.
A screenshot of the example. Map style © OpenTopoMap (CC-BY-SA). Map data © OpenStreetMap contributors. Elevation: SRTM.

What this example shows

Over Kraków on OpenTopoMap, three sliders (Hue, Chroma and Lightness) rotate map colours smoothly through perceptual cylindrical HCL space—for example shifting green forests into cool cyan/blue while keeping road casings, contour lines and black place names equally sharp and legible.

When you need it

Third-party raster basemaps often clash with your application’s foreground colour palette (for instance bright green park fills hiding green status markers) or brand theme.

Manipulating colours in perceptual CIE HCL space preserves human-perceived luminance when rotating hue, unlike naive RGB or HSL shifts that turn yellows muddy or blues unreadably dark.

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.

color-manipulation.shared.ts
import { ATTRIBUTION } from 'ol/source/OSM.js';

/** A range control: its name, range and start, and the unit its value is shown in. */
export interface Control {
  name: 'hue' | 'chroma' | 'lightness';
  min: number;
  max: number;
  start: number;
  unit: string;
}

export const CONTROLS: Control[] = [
  { name: 'hue', min: -180, max: 180, start: 0, unit: '°' },
  { name: 'chroma', min: 0, max: 100, start: 100, unit: '%' },
  { name: 'lightness', min: 0, max: 100, start: 100, unit: '%' },
];

export const TOPOGRAPHY = [
  'Map style © <a href="https://opentopomap.org/">OpenTopoMap</a> (<a href="https://creativecommons.org/licenses/by-sa/3.0/">CC-BY-SA</a>)',
  ATTRIBUTION,
];

/**
 * The functions and constants the raster worker defines under these names before it runs the operation. They and
 * the operation call each other by these names as globals: a production build renames the functions of this module,
 * and a name taken from the module would not exist in the worker.
 *
 * Color manipulation functions below are adapted from
 * https://github.com/d3/d3-color.
 */
export const WORKER_LIB = {
  Xn: 0.95047,
  Yn: 1,
  Zn: 1.08883,
  t0: 4 / 29,
  t1: 6 / 29,
  t2: 3 * (6 / 29) * (6 / 29),
  t3: (6 / 29) * (6 / 29) * (6 / 29),
  twoPi: 2 * Math.PI,
  /** Convert an RGB pixel into an HCL pixel. */
  rgb2hcl: (pixel: number[]): number[] => {
    const red = rgb2xyz(pixel[0]);
    const green = rgb2xyz(pixel[1]);
    const blue = rgb2xyz(pixel[2]);
    const x = xyz2lab((0.4124564 * red + 0.3575761 * green + 0.1804375 * blue) / Xn);
    const y = xyz2lab((0.2126729 * red + 0.7151522 * green + 0.072175 * blue) / Yn);
    const z = xyz2lab((0.0193339 * red + 0.119192 * green + 0.9503041 * blue) / Zn);
    const l = 116 * y - 16;
    const a = 500 * (x - y);
    const b = 200 * (y - z);
    const c = Math.sqrt(a * a + b * b);
    let h = Math.atan2(b, a);
    if (h < 0) {
      h += twoPi;
    }
    pixel[0] = h;
    pixel[1] = c;
    pixel[2] = l;
    return pixel;
  },
  /** Convert an HCL pixel into an RGB pixel. */
  hcl2rgb: (pixel: number[]): number[] => {
    const h = pixel[0];
    const c = pixel[1];
    const l = pixel[2];
    const a = Math.cos(h) * c;
    const b = Math.sin(h) * c;
    let y = (l + 16) / 116;
    let x = isNaN(a) ? y : y + a / 500;
    let z = isNaN(b) ? y : y - b / 200;
    y = Yn * lab2xyz(y);
    x = Xn * lab2xyz(x);
    z = Zn * lab2xyz(z);
    pixel[0] = xyz2rgb(3.2404542 * x - 1.5371385 * y - 0.4985314 * z);
    pixel[1] = xyz2rgb(-0.969266 * x + 1.8760108 * y + 0.041556 * z);
    pixel[2] = xyz2rgb(0.0556434 * x - 0.2040259 * y + 1.0572252 * z);
    return pixel;
  },
  xyz2lab: (t: number): number => (t > t3 ? Math.pow(t, 1 / 3) : t / t2 + t0),
  lab2xyz: (t: number): number => (t > t1 ? t * t * t : t2 * (t - t0)),
  rgb2xyz: (x: number): number => ((x /= 255) <= 0.04045 ? x / 12.92 : Math.pow((x + 0.055) / 1.055, 2.4)),
  xyz2rgb: (x: number): number => 255 * (x <= 0.0031308 ? 12.92 * x : 1.055 * Math.pow(x, 1 / 2.4) - 0.055),
};

/* Defined in the raster worker from `WORKER_LIB`. */
declare const Xn: number, Yn: number, Zn: number, t0: number, t1: number, t2: number, t3: number, twoPi: number;
declare const rgb2hcl: (typeof WORKER_LIB)['rgb2hcl'];
declare const hcl2rgb: (typeof WORKER_LIB)['hcl2rgb'];
declare const xyz2lab: (typeof WORKER_LIB)['xyz2lab'];
declare const lab2xyz: (typeof WORKER_LIB)['lab2xyz'];
declare const rgb2xyz: (typeof WORKER_LIB)['rgb2xyz'];
declare const xyz2rgb: (typeof WORKER_LIB)['xyz2rgb'];

/** Turns the hue of a pixel by `data.hue` degrees and scales its chroma and lightness by percentages. */
export function rotateColors(pixels: (number[] | ImageData)[], data: object): number[] {
  const { hue, chroma, lightness } = data as Record<string, number>;
  const hcl = rgb2hcl(pixels[0] as number[]);
  let h = hcl[0] + (Math.PI * hue) / 180;
  if (h < 0) {
    h += twoPi;
  } else if (h > twoPi) {
    h -= twoPi;
  }
  hcl[0] = h;
  hcl[1] *= chroma / 100;
  hcl[2] *= lightness / 100;
  return hcl2rgb(hcl);
}
color-manipulation.ts
import { ChangeDetectionStrategy, Component, signal, viewChild } from '@angular/core';
import type { RasterSourceEvent } from 'ol/source/Raster';
import {
  CoordinateComponent,
  DefaultControlComponent,
  DefaultInteractionComponent,
  LayerImageComponent,
  MapComponent,
  SourceRasterComponent,
  SourceXYZComponent,
  ViewComponent,
} from 'cc-openlayers';
import { CONTROLS, type Control, rotateColors, TOPOGRAPHY, WORKER_LIB } from './color-manipulation.shared';

/**
 * A pixel operation of a raster source on OpenTopoMap's map of Kraków: each pixel goes from RGB to the HCL colour
 * space, where the sliders turn its hue and scale its chroma and lightness, and back.
 */
@Component({
  selector: 'app-color-manipulation',
  imports: [
    CoordinateComponent,
    DefaultControlComponent,
    DefaultInteractionComponent,
    LayerImageComponent,
    MapComponent,
    SourceRasterComponent,
    SourceXYZComponent,
    ViewComponent,
  ],
  changeDetection: ChangeDetectionStrategy.OnPush,
  template: `
    <aol-map height="480px">
      <aol-interaction-default />
      <aol-control-defaults />
      <aol-view [zoom]="11" [maxZoom]="18">
        <aol-coordinate [x]="19.9373" [y]="50.0617" srid="EPSG:4326" />
      </aol-view>
      <aol-layer-image>
        <aol-source-raster [operation]="operation" [lib]="lib" (beforeOperations)="beforeOperations($event)">
          <aol-source-xyz
            url="https://tile.opentopomap.org/{z}/{x}/{y}.png"
            crossOrigin="anonymous"
            [maxZoom]="17"
            [attributions]="topography"
          />
        </aol-source-raster>
      </aol-layer-image>
    </aol-map>
    <div class="example-controls">
      @for (control of controls; track control.name) {
        <label>
          {{ control.name }}
          <input
            type="range"
            [name]="control.name"
            [min]="control.min"
            [max]="control.max"
            [value]="values()[control.name]"
            (input)="set(control.name, $event)"
          />
          <output>{{ values()[control.name] }}</output>
          {{ control.unit }}
        </label>
      }
    </div>
  `,
})
export class ColorManipulation {
  protected readonly topography = TOPOGRAPHY;
  protected readonly operation = rotateColors;
  protected readonly lib = WORKER_LIB;
  protected readonly controls = CONTROLS;
  protected readonly values = signal(Object.fromEntries(CONTROLS.map((control) => [control.name, control.start])));
  private readonly raster = viewChild.required(SourceRasterComponent);

  protected set(name: Control['name'], event: Event): void {
    const value = Number((event.target as HTMLInputElement).value);
    this.values.update((values) => ({ ...values, [name]: value }));
    this.raster().instance.changed();
  }

  /** The event's data object is passed to the operation. */
  protected beforeOperations(event: RasterSourceEvent): void {
    for (const [name, value] of Object.entries(this.values())) {
      event.data[name] = value;
    }
  }
}

Architecture and OpenLayers mechanics

aol-source-raster reads CORS-enabled (crossOrigin="anonymous") OpenTopoMap tiles from aol-source-xyz and runs rotateColors per pixel in worker threads. Helper functions rgb2hcl and hcl2rgb (alongside their colourimetric constants) are registered via [lib] so worker serialisation includes them.

On each pass, (beforeOperations) copies slider settings into event.data, shifting data.hue in degrees and scaling chroma and lightness by percentage factors before converting back to RGB.

How it works

  • aol-source-raster executes rotateColors over aol-source-xyz OpenTopoMap tiles loaded with crossOrigin="anonymous".
  • rotateColors converts RGB pixels via rgb2hcl, shifts hue by data.hue and scales chroma/lightness, then converts back via hcl2rgb.
  • [lib] exports the colour-space helpers and constants into the worker scope while (beforeOperations) populates event.data.

Pitfalls

  • Every helper function or constant referenced inside rotateColors must be listed in [lib], because OpenLayers serialises worker functions as standalone source text stripped of ES module imports.
  • Rotating hue in HCL preserves perceived lightness across labels and shaded relief, whereas HSL hue rotation distorts apparent brightness.
  • Input tile servers must send permissive CORS headers alongside crossOrigin="anonymous" for pixel readback to succeed.

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.