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.

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.tsimport { 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.tsimport { 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;
}
}
} The React version uses the library's React adapter, cc-openlayers/react: each component creates the OpenLayers object it names when it mounts, updates it from its props and disposes of it when it unmounts.
color-manipulation.react.tsximport { useRef, useState, type ChangeEvent } from 'react';
import type Raster from 'ol/source/Raster.js';
import type { RasterSourceEvent } from 'ol/source/Raster.js';
import {
Coordinate,
DefaultControls,
DefaultInteractions,
ImageLayer,
Map,
RasterSource,
View,
XYZSource,
} from 'cc-openlayers/react';
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.
*/
export function ColorManipulation() {
const [values, setValues] = useState(Object.fromEntries(CONTROLS.map((control) => [control.name, control.start])));
const raster = useRef<Raster>(null);
const set = (name: Control['name'], event: ChangeEvent<HTMLInputElement>) => {
const value = Number(event.target.value);
setValues((current) => ({ ...current, [name]: value }));
raster.current?.changed();
};
/** The event's data object is passed to the operation. */
const beforeOperations = (event: RasterSourceEvent) => {
for (const [name, value] of Object.entries(values)) {
event.data[name] = value;
}
};
return (
<>
<Map height="480px">
<DefaultInteractions />
<DefaultControls />
<View zoom={11} maxZoom={18}>
<Coordinate x={19.9373} y={50.0617} srid="EPSG:4326" />
</View>
<ImageLayer>
<RasterSource ref={raster} operation={rotateColors} lib={WORKER_LIB} onBeforeOperations={beforeOperations}>
<XYZSource
url="https://tile.opentopomap.org/{z}/{x}/{y}.png"
crossOrigin="anonymous"
maxZoom={17}
attributions={TOPOGRAPHY}
/>
</RasterSource>
</ImageLayer>
</Map>
<div className="example-controls">
{CONTROLS.map((control) => (
<label key={control.name}>
{control.name}
<input
type="range"
name={control.name}
min={control.min}
max={control.max}
value={values[control.name]}
onChange={(event) => set(control.name, event)}
/>
<output>{values[control.name]}</output>
{control.unit}
</label>
))}
</div>
</>
);
}color-manipulation.shared.tsimport { 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);
}How the React version works
OpenTopoMap tiles of Kraków whose hue, chroma and lightness are changed per pixel by a raster source in a worker, set with three sliders.
What both versions share
OpenLayers renders the map and handles the interactions; the cc-openlayers/core layer gives both adapters the same view binding (MapViewBinding) and the same conversion of coordinates from EPSG:4326 to the map's projection. Both versions import the slider definitions, the topographic layer, the worker library and rotateColors from the example's .shared.ts file, so the logic exists once. The raster source turns the operation into source text for its worker.
From Angular to React
| Angular | React |
|---|---|
<aol-source-raster [operation] [lib] (beforeOperations)> | <RasterSource operation lib onBeforeOperations> |
viewChild of the source and changed() after a slider | ref on the source (useRef) and changed() in the slider handler |
a signal of the slider values | useState of the values, read in onBeforeOperations |
Who creates, updates and disposes
Map creates the ol/Map in useLayoutEffect and disposes of it on unmount; each layer, source and interaction component adds its object to the parent it gets from context and removes it in its effect's cleanup, as ngOnDestroy does in Angular.
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-rasterexecutesrotateColorsoveraol-source-xyzOpenTopoMap tiles loaded withcrossOrigin="anonymous".rotateColorsconverts RGB pixels viargb2hcl, shifts hue bydata.hueand scales chroma/lightness, then converts back viahcl2rgb.[lib]exports the colour-space helpers and constants into the worker scope while(beforeOperations)populatesevent.data.
Pitfalls
- Every helper function or constant referenced inside
rotateColorsmust 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.
Related examples
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.