The OSINT investigator's workbench. One case, one folder, every tool. Local-first: your media and your investigations never leave your machine.
JavaScript
/**
* One added layer on the map: a GeoJSON source and the GL layers over it.
*
* **Not DOM markers.** The case's own pins are one `div` each (`surface.js`),
* which is right for a few hundred rich, draggable, hoverable marks and caps out
* around a thousand or two. A layer somebody else made holds tens of thousands,
* and a personal layer adds editing actions to its cards, so it is a source
* with `circle`, `symbol`, `line` and `fill` layers, which MapLibre paints in
* one pass and culls to the viewport for free. Nothing here filters by viewport
* or truncates the data: the engine already does the first and the second would
* be a map lying about what it read.
*
* The drawing follows these rules:
*
* - **Decluttering is collision, not a cap.** At low zoom the symbols would be a
* solid mat, and a cap taken in file order clumps badly — a KML is ordered by
* folder or by creation, never by geography. `icon-allow-overlap: false` lets
* MapLibre drop a symbol that overlaps one already placed, which gives an
* evenly spread map that densifies as you zoom in, for nothing.
* - **Icons are registered at runtime.** The engine deliberately loads no style
* URL, no sprite and no glyphs (`engine.js`), and this must not be the reason
* it starts. Each pictogram is drawn to a canvas here and handed to
* `map.addImage` as an **SDF**, which is what lets one image per shape be
* tinted to any colour a source asked for. Personal icons use coloured
* images instead, with one image per symbol and colour shared by their points.
* - **A source's own icons are a second symbol layer, not a second option on the
* first.** They arrive as real PNGs the backend composed
* (`engine/maplayers.py`), which means non-SDF, which means no `icon-color`
* and no `icon-halo-*` — the colour is already in the pixels. Mixing SDF and
* non-SDF images in one symbol layer is not something MapLibre renders
* reliably, so the points split by whether their icon loaded: the ones that
* did draw the source's picture, the ones that did not draw our tinted shape.
* That split is also the fallback. An icon that 404s, decodes badly or never
* arrives costs its features nothing beyond the pictogram they would have had.
* - **No map labels.** A feature's name lives in the hover reading and in the
* card, both resolved through the engine's own hit testing.
*/
import { Popup } from 'maplibre-gl';
import { paths } from '../../components/Icon.svelte';
import { wrapLon } from '../coords.js';
import { categoryColour } from './addedLayers.js';
import { drawMarker, drawOwnMarker, isBadge, MARKER_PIXELS, ownMarkerSide } from './markerGlyphs.js';
import { loadPicture } from './ownIcons.js';
/** Geometry defaults and the symbols available to personal layer points. */
const GLYPHS = { point: 'pin', line: 'line', area: 'polygon', circle: 'circle', star: 'star', flag: 'flag' };
const BASE_KINDS = ['point', 'line', 'area'];
export function markerIcon(geometry, symbol) {
return iconName(geometry?.type === 'Point' && ['circle', 'star', 'flag'].includes(symbol)
? symbol : kindOf(geometry));
}
/** How big an icon is drawn into its own image, before the engine scales it. */
const ICON_PIXELS = 64;
/**
* Empty pixels kept around the glyph inside that image.
*
* The outline is drawn *outside* the shape, so a glyph filling its own image
* would have its outline cut off at the edge — worst at the pin's tip, which is
* the part that names the point.
*/
const ICON_PAD = 10;
/**
* How far from the edge the distance field still means something.
*
* The outline can only be as wide as the field can measure, so this is what
* bounds `icon-halo-width` below: too small and the outline is clipped into a
* hard ring, which looks worse than none.
*/
const ICON_SPREAD = 8;
/** …and how much of that is shown. An added layer sits under the case's own
* marks in weight as well as in stacking order. */
const ICON_SCALE = 0.4;
// A pin's painted height is smaller than a disc in the same canvas.
const PERSONAL_PIN_SCALE = 0.6;
/**
* …and the weight a source's own icon is drawn at.
*
* The backend composes every one of them to one painted weight (`ICON_SIDE`),
* which is what makes a single number right here: a 16px road sign and a 512px
* badge come out of the same door, so a My Maps cannot have one group towering
* over another just because its creator uploaded a bigger PNG.
*
* Lower than the pictogram above it, because a real icon is a filled picture
* where ours is a stroked outline: at equal size the picture reads heavier, and
* these are somebody else's marks sitting under the case's own.
*/
export const SOURCE_ICON_SCALE = 0.28;
/**
* The white edge around every mark.
*
* A foreign layer is drawn in the source's own colours, and a source picks them
* against its own basemap — never against this case's imagery. A dark green pin
* on a field and a pale one on concrete both disappear. The outline is what
* makes the colour readable wherever the analyst happens to be looking, and it
* costs nothing: `icon-halo-*` only works on SDF icons, which is already the
* format chosen so the source's colour could tint our pictogram.
*/
const ICON_OUTLINE = '#fff';
/** What is new on the day a tracked layer is read on is ringed in this, on any ground. */
export const NEW_COLOUR = '#ffd400';
/** Enough to lift the mark off the ground under it, and no more: past about a
* pixel the edge starts reading as the mark and the colour as its filling. */
const ICON_OUTLINE_WIDTH = 0.8;
/**
* The frame a searched-for feature is shown in.
*
* A pin has no extent at all, so the box collapses to a point and the ceiling is
* what decides the zoom; a district frames itself. One rule for all three kinds,
* and the same numbers the map's other handoffs travel by (`Satellite.svelte`).
*/
const REVEAL_PADDING = [48, 48];
const REVEAL_ZOOM = 17;
/**
* How far off its point a card hangs.
*
* A pin stands above the ground it claims — its image is `ICON_PIXELS` tall,
* shown at `ICON_SCALE`, and pulled back down by the padding under its tip — so
* a card opened at the point itself would cover the mark that was clicked. An
* edge or an area is clicked where it is, and takes the smaller gap.
*/
const PIN_CARD_OFFSET = Math.round((ICON_PIXELS - ICON_PAD) * ICON_SCALE);
const EDGE_CARD_OFFSET = 12;
let layers = 0; // one id prefix per layer, so two of them never collide
const owners = new WeakMap();
/** The card a feature opens, dressed like every other card on this map
* (`lib/map/engine.css`) and closed the same two ways: its own cross, or the
* next click anywhere. */
function defaultPopup(offset) {
return new Popup({
className: 'added-layer-card',
closeOnClick: true,
focusAfterOpen: false,
maxWidth: '320px',
offset,
});
}
/** The image `addImage` knows a pictogram by. Shared: they are SDFs, so one
* copy serves every layer and every colour. */
export function iconName(kind) {
return `azimut-layer-${kind}`;
}
/**
* …and the one it knows a source's own icon by: the address it is read from,
* which names its case and layer as well as its key.
*
* Never the key alone. The backend hashes what the source says of the icon, and
* a KMZ says `images/icon-3.png` whatever is drawn in it, so two My Maps give one
* key to two pictures. Named by key, the first layer loaded drew its picture on
* the other's markers.
*/
export function sourceIconName(url) {
return `azimut-source-${url}`;
}
/** One composed icon, fetched from the case folder and decoded by the engine. */
async function defaultLoadIcon(map, url) {
const loaded = await map.loadImage(url);
return loaded?.data ?? null;
}
/**
* A pictogram as a signed-distance-field image.
*
* SDF is the whole reason the colour rule works: MapLibre tints an SDF icon with
* `icon-color`, so the source's own colour paints our shape. A plain image would
* have to be re-registered per colour.
*
* The field is crude — inside the stroke is opaque, outside falls off over a few
* pixels — which is all a 48px pictogram needs, and it keeps this to a canvas
* and no dependency.
*/
export function iconImage(kind, size = ICON_PIXELS, make = defaultCanvas) {
const canvas = make(size, size);
const context = canvas.getContext('2d');
if (!context) return null;
context.clearRect(0, 0, size, size);
// inset, so the outline drawn outside the shape has pixels to live in
const scale = (size - ICON_PAD * 2) / 24;
context.setTransform(scale, 0, 0, scale, ICON_PAD, ICON_PAD);
context.strokeStyle = '#fff';
context.fillStyle = '#fff';
context.lineWidth = 2.4;
context.lineJoin = 'round';
context.lineCap = 'round';
const path = new Path2D(paths[GLYPHS[kind] ?? 'pin']);
if (['point', 'circle', 'star', 'flag'].includes(kind)) context.fill(path);
context.stroke(path);
context.setTransform(1, 0, 0, 1, 0, 0);
const pixels = context.getImageData(0, 0, size, size);
return { width: size, height: size, data: sdf(pixels.data, size, ICON_SPREAD) };
}
/** A coloured disc with its glyph, drawn locally without an icon service. */
export function badgeImage(symbol, colour, marks = {}, make = defaultCanvas) {
return isBadge(symbol) ? personalMarkerImage(symbol, colour, marks, make) : null;
}
/** Plain personal markers share a bitmap layer with badges to respect group order.
* `marks` are the status stroke and the external rim (`markerParts`). */
export function personalMarkerImage(symbol, colour, marks = {}, make = defaultCanvas) {
const canvas = make(MARKER_PIXELS, MARKER_PIXELS), context = canvas.getContext('2d');
if (!context) return null;
drawMarker(context, symbol, colour, marks);
return context.getImageData(0, 0, MARKER_PIXELS, MARKER_PIXELS);
}
/**
* A marker wearing one of the analyst's icons (`drawOwnMarker`): in its disc, or
* as it is with its status stroke or external rim. `picture` is `{ image, box }`
* (`ownIcons.loadPicture`).
*/
export function ownMarkerImage(picture, colour, look = {}, make = defaultCanvas) {
const side = ownMarkerSide(picture?.image, look.mode);
const canvas = make(side, side), context = canvas?.getContext('2d');
if (!context || !picture?.image) return null;
drawOwnMarker(context, picture.image, colour, { ...look, box: picture.box });
return context.getImageData(0, 0, side, side);
}
/** The image a marker is registered under: one per symbol, colour and marks. */
export function markerImageKey(symbol, colour, { status = '', external = false } = {}) {
return `${symbol}-${String(colour).toLowerCase().replace('#', '')}${status ? `-${status}` : ''}${external ? '-x' : ''}`;
}
/** The size of the direction mark's image, around a marker at the same scale. */
const BEARING_PIXELS = 96;
const BEARING_ICON = 'azimut-layer-bearing';
/**
* A wedge just outside a badge's rim, pointing up: the map turns it to the
* marker's `bearing`, so it says which way a camera looked or a convoy drove.
*/
/**
* The stripes an area's gains or losses are hatched with, in its own colour:
* gains in close stripes one way, losses in sparser fainter ones the other, so
* the two read apart in print as well as on screen.
*/
export const HATCH_PIXELS = 12;
export function hatchImage(colour, kind, make = defaultCanvas) {
const canvas = make(HATCH_PIXELS, HATCH_PIXELS);
const ctx = canvas?.getContext?.('2d');
if (!ctx) return null;
ctx.strokeStyle = colour;
ctx.globalAlpha = kind === 'gained' ? 0.85 : 0.5;
ctx.lineWidth = kind === 'gained' ? 2.2 : 1.4;
ctx.beginPath();
// Three strokes so the stripe runs on across the tile's corners without a seam.
for (const shift of [-HATCH_PIXELS, 0, HATCH_PIXELS]) {
if (kind === 'gained') { ctx.moveTo(shift, HATCH_PIXELS); ctx.lineTo(shift + HATCH_PIXELS, 0); }
else { ctx.moveTo(shift, 0); ctx.lineTo(shift + HATCH_PIXELS, HATCH_PIXELS); }
}
ctx.stroke();
return ctx.getImageData(0, 0, HATCH_PIXELS, HATCH_PIXELS);
}
/** The head drawn on a line's end, in its own colour, pointing up before it is turned. */
export const ARROW_PIXELS = 26;
export function arrowHeadImage(colour, make = defaultCanvas) {
const canvas = make(ARROW_PIXELS, ARROW_PIXELS);
const ctx = canvas?.getContext?.('2d');
if (!ctx) return null;
const middle = ARROW_PIXELS / 2;
ctx.beginPath();
ctx.moveTo(middle, 2);
ctx.lineTo(ARROW_PIXELS - 4, ARROW_PIXELS - 4);
ctx.lineTo(middle, ARROW_PIXELS - 9);
ctx.lineTo(4, ARROW_PIXELS - 4);
ctx.closePath();
ctx.fillStyle = colour; ctx.fill();
ctx.lineWidth = 1.6; ctx.strokeStyle = 'rgba(255,255,255,0.9)'; ctx.lineJoin = 'round'; ctx.stroke();
return ctx.getImageData(0, 0, ARROW_PIXELS, ARROW_PIXELS);
}
/** How a confidence is drawn when the feature names no dash of its own: probable dashed, claimed dotted. */
export const CONFIDENCE_DASH = { probable: 'dashed', claimed: 'dotted' };
/** …and how strongly a point of each confidence is drawn. */
export const CONFIDENCE_OPACITY = { probable: 0.8, claimed: 0.55 };
/** The degrees from north a line leaves its last point by, read off its last two. */
export function endBearing(line, atStart = false) {
const points = atStart ? [line[1], line[0]] : [line.at(-2), line.at(-1)];
if (!points[0] || !points[1]) return 0;
const [[lon1, lat1], [lon2, lat2]] = points;
const dx = (lon2 - lon1) * Math.cos((((lat1 + lat2) / 2) * Math.PI) / 180);
return ((Math.atan2(dx, lat2 - lat1) * 180) / Math.PI + 360) % 360;
}
/** The arrowheads a feature's line ends carry, as points the map turns its head image on. */
export function arrowHeads(feature) {
const ends = feature?.properties?.line_arrow;
const geometry = feature?.geometry;
if (!ends || !geometry || !String(geometry.type).includes('LineString')) return [];
const lines = geometry.type === 'LineString' ? [geometry.coordinates] : geometry.coordinates;
const heads = [];
for (const line of lines) {
if (line.length < 2) continue;
heads.push({ at: line.at(-1), angle: endBearing(line) });
if (ends === 'both') heads.push({ at: line[0], angle: endBearing(line, true) });
}
return heads;
}
export function bearingImage(make = defaultCanvas) {
const canvas = make(BEARING_PIXELS, BEARING_PIXELS), context = canvas.getContext('2d');
if (!context) return null;
const middle = BEARING_PIXELS / 2;
context.clearRect(0, 0, BEARING_PIXELS, BEARING_PIXELS);
context.beginPath();
context.moveTo(middle, 3);
context.lineTo(middle + 9, 16);
context.lineTo(middle - 9, 16);
context.closePath();
context.lineJoin = 'round';
context.lineWidth = 3;
context.strokeStyle = 'rgba(0, 0, 0, 0.6)';
context.stroke();
context.fillStyle = '#fff';
context.fill();
return context.getImageData(0, 0, BEARING_PIXELS, BEARING_PIXELS);
}
/** The app's sans-serif stack, which the engine hands to the browser to draw names. */
const LABEL_FONT = ['ui-sans-serif', 'system-ui', 'sans-serif'];
function defaultCanvas(width, height) {
const canvas = document.createElement('canvas');
canvas.width = width;
canvas.height = height;
return canvas;
}
/**
* Alpha → the distance field MapLibre reads.
*
* MapLibre treats an SDF's alpha channel as distance from the shape's edge, with
* 0.5 the edge itself. Drawn opaque, a pictogram already says inside from
* outside; this spreads that boundary over a few pixels so the icon has an edge
* to antialias rather than a cliff.
*/
function sdf(data, size, spread = ICON_SPREAD) {
const out = new Uint8ClampedArray(data.length);
const inside = (x, y) =>
x >= 0 && y >= 0 && x < size && y < size && data[(y * size + x) * 4 + 3] > 127;
for (let y = 0; y < size; y += 1) {
for (let x = 0; x < size; x += 1) {
const index = (y * size + x) * 4;
let distance = spread;
for (let radius = 0; radius <= spread && distance === spread; radius += 1) {
// the first ring at which this pixel disagrees with the one it is in
for (let dy = -radius; dy <= radius; dy += 1) {
for (let dx = -radius; dx <= radius; dx += 1) {
if (inside(x + dx, y + dy) !== inside(x, y)) {
distance = Math.min(distance, Math.hypot(dx, dy));
}
}
}
}
const signed = inside(x, y) ? distance : -distance;
out[index] = out[index + 1] = out[index + 2] = 255;
out[index + 3] = Math.round(((signed / spread) * 0.5 + 0.5) * 255);
}
}
return out;
}
/** Register requested pictograms once per map. */
export function registerIcons(map, build = iconImage, kinds = BASE_KINDS) {
for (const kind of kinds) {
const name = iconName(kind);
if (map.hasImage?.(name)) continue;
const image = build(kind);
if (image) map.addImage(name, image, { sdf: true });
}
}
/**
* What a category is painted, as one expression over the whole layer.
*
* Built as a `match` on the category name rather than resolved per feature into
* the data: the colour a legend row shows and the colour the map draws are then
* the same value read from the same place, and switching one cannot leave the
* other behind.
*/
export function colourExpression(categories = []) {
if (!categories.length) return categoryColour(null, 0);
const match = ['match', ['get', 'category']];
categories.forEach((category, index) => {
match.push(category.name, categoryColour(category, index));
});
match.push(categoryColour(null, 0));
return match;
}
/** Which features are drawn: everything, minus the categories switched off. */
export function visibilityFilter(hidden = []) {
if (!hidden.length) return null;
return ['!', ['in', ['get', 'category'], ['literal', [...hidden]]]];
}
/**
* The row's time filter as a MapLibre filter, or null for every date.
*
* Days are `YYYY-MM-DD`, which sort as strings the way they sort as dates, so the
* comparison needs no parsing on the engine's side. A feature spanning several
* days (`date_end`) is kept when any of them is in the period. A feature with no
* date is outside any period.
*/
export function periodFilter(period = null) {
if (!period?.start && !period?.end) return null;
const rule = ['all', ['has', 'date']];
if (period.start) rule.push(['>=', ['coalesce', ['get', 'date_end'], ['get', 'date']], period.start]);
if (period.end) rule.push(['<=', ['get', 'date'], period.end]);
return rule;
}
/**
* Whether two lists of features say the same, in the same order: each the same
* object, or one written the same. A layer read back holds new objects for the
* features it already drew.
*/
export function sameFeatures(a, b) {
if (a.length !== b.length) return false;
for (let i = 0; i < a.length; i += 1) {
if (a[i] !== b[i] && JSON.stringify(a[i]) !== JSON.stringify(b[i])) return false;
}
return true;
}
/**
* @param {object} engine the façade from `engine.js`
* @param {object} [opts]
* @param {(properties: object, point: { lat: number, lon: number } | null, geometry: object | null) => HTMLElement} [opts.card]
* the read-only popup's body, handed the feature's own point when it has one
* and its geometry as the source wrote it, so a line or an area can be measured
* @param {(offset: number) => object} [opts.popup] the card itself, swappable so
* the click path can be read off a test without standing up the engine's own popup
* @param {(key: string) => string} [opts.iconUrl] where this case keeps the
* source's composed icons. Absent — a layer added without the box ticked, or one
* whose icons could not be made — and every point draws the app's own pictogram.
* @param {(map: object, url: string) => Promise<object|null>} [opts.loadIcon]
* @param {(at: { lat: number, lon: number, x: number, y: number }, properties: object | null) => void} [opts.menu]
* what a right-click on a feature opens: the map's own point menu, on the
* feature's point when it is a pin (with its properties), on the ground under
* the cursor for a line or an area (with none). The features claim their
* clicks, so without this a right-click on one opens nothing at all.
* @param {boolean} [opts.page] drawn for a plate's page: every symbol drawn, where
* the live map lets overlapping ones drop out far out with a dot for each, since a
* page that leaves the app must not lose a point the reader cannot zoom in to find;
* and its areas may be hatched, as a plate draws a claimed ground.
*/
export function createAddedLayer(
engine,
{ card, popup = defaultPopup, iconUrl = null, loadIcon = defaultLoadIcon, menu = null,
editable = false, history = false, page = false, buildBadge = badgeImage, buildPersonal = personalMarkerImage, buildHatch = hatchImage,
buildOwn = ownMarkerImage, readPicture = loadPicture } = {}
) {
const map = engine.impl;
const prefix = `added-${++layers}`;
const SOURCE = `${prefix}-src`;
const FILL = `${prefix}-fill`;
const LINE = `${prefix}-line`;
const DOT = `${prefix}-dot`;
const MARK = `${prefix}-mark`;
const OWN = `${prefix}-own`;
const HIT = `${prefix}-hit`;
const HIT_OWN = `${prefix}-hit-own`;
const BEARING = `${prefix}-bearing`;
const LABEL = `${prefix}-label`;
// A personal feature's own line look, a hatched fill, and the heads on its line ends.
const LINE_DASH = `${prefix}-line-dash`;
const LINE_DOT = `${prefix}-line-dot`;
const FILL_HATCH = `${prefix}-fill-hatch`;
const ARROW = `${prefix}-arrow`;
const ARROW_SOURCE = `${prefix}-arrow-src`;
// A tracked layer's past, under what it is now (`layerHistory.js`): the
// state before, dashed, and an area's gains and losses, hatched.
const CHANGE_FILL = `${prefix}-change-fill`;
const CHANGE_LINE = `${prefix}-change-line`;
const TRAIL_LINE = `${prefix}-trail-line`;
const TRAIL_DOT = `${prefix}-trail-dot`;
// …and what is new on the day it is read on, ringed under it.
const NEW_LINE = `${prefix}-new-line`;
const NEW_RING = `${prefix}-new-ring`;
// A source draws no text and no direction: its names are read in the card,
// and a personal layer is the one whose analyst asks for either.
// a dash is drawn on any layer, a plate setting one for a source layer as for the analyst's own
const hatched = editable || page;
const declutter = !page;
const PAINTED = [FILL, ...(hatched ? [FILL_HATCH] : []), LINE, LINE_DASH, LINE_DOT, DOT,
...(editable ? [BEARING] : []), MARK, OWN, ...(editable ? [LABEL, HIT, HIT_OWN] : [])];
// Drawn, never clicked: the past says nothing a card on the feature would not.
// Only a layer followed over time has a past, so only it pays for these.
const DECOR = editable && history ? [CHANGE_FILL, CHANGE_LINE, TRAIL_LINE, TRAIL_DOT, NEW_LINE, NEW_RING] : [];
const DRAWN = [...DECOR, ...PAINTED, ...(editable ? [ARROW] : [])];
// A merge makes multi-part lines and areas, so each kind names both forms.
const POINT = ['in', ['geometry-type'], ['literal', ['Point', 'MultiPoint']]];
const NOW = ['!', ['any', ['has', '$trail'], ['has', '$change']]];
const BASE = {
[FILL]: ['all', NOW, ['in', ['geometry-type'], ['literal', ['Polygon', 'MultiPolygon']]]],
[LINE]: ['all', NOW, ['!', POINT], ['!', ['has', '$dash']]],
[LINE_DASH]: ['all', NOW, ['!', POINT], ['==', ['get', '$dash'], 'dashed']],
[LINE_DOT]: ['all', NOW, ['!', POINT], ['==', ['get', '$dash'], 'dotted']],
[FILL_HATCH]: ['all', NOW, ['has', '$fillhatch']],
[ARROW]: NOW,
[DOT]: ['all', NOW, POINT],
[BEARING]: ['all', NOW, POINT, ['has', 'bearing']],
// The two symbol layers split the points between them on the one
// question of whether this feature's own icon is registered.
[MARK]: ['all', NOW, POINT, ['!', ['has', '$own']]],
[OWN]: ['all', NOW, POINT, ['has', '$own']],
[LABEL]: ['all', NOW, ['has', 'show_label'], ['!=', ['get', 'name'], '']],
[HIT]: ['all', NOW, POINT, ['!', ['has', '$own']]],
[HIT_OWN]: ['all', NOW, POINT, ['has', '$own']],
[CHANGE_FILL]: ['has', '$change'],
[CHANGE_LINE]: ['has', '$change'],
[TRAIL_LINE]: ['all', ['has', '$trail'], ['!', POINT]],
[TRAIL_DOT]: ['all', ['has', '$trail'], POINT],
[NEW_LINE]: ['all', NOW, ['has', '$new'], ['!', POINT]],
[NEW_RING]: ['all', NOW, ['has', '$new'], POINT],
};
const badgeIcons = new Set();
/** The analyst's icons a personal layer wears, `{ image, box }` by address, for its discs and marks. */
const pictures = new Map();
// Features held off the map while the editor drags their copies (`hide`).
let hiddenKeys = new Set();
let lastFilter = [[], null];
let built = false;
// what the source was last handed (`set`): the features as given and the style they were built with
let sent = null;
// whether the arrow heads' source holds any
let arrowsSent = false;
let shown = true;
let filtered = ''; // the filter last applied, so the same one is not re-applied
let categories = [];
let collection = null; // what was last drawn, so a feature can be found by number
let open = null; // the read-only card, so it can be closed by name
let releaseClicks = null;
// Off while the map's own tool holds the pointer (a measure, a pin, an area
// being drawn): a click there is the tool's, not a card's.
let interactive = true;
// Bumped by every `set` and by `destroy`, so a set whose icons were still
// loading when the layer moved on lands nowhere.
let generation = 0;
const listeners = [];
function build(attribution) {
if (built) return;
built = true;
sent = null;
arrowsSent = false;
registerIcons(map);
map.addSource(SOURCE, {
type: 'geojson',
data: { type: 'FeatureCollection', features: [] },
// the credit line the source is owed, picked up by the engine's own
// attribution control exactly as a curated overlay's is
attribution,
});
const colour = ['to-color', ['get', '$colour']];
if (DECOR.length) {
map.addLayer({ id: CHANGE_FILL, type: 'fill', source: SOURCE, filter: BASE[CHANGE_FILL],
paint: { 'fill-pattern': ['get', '$hatch'] } });
map.addLayer({ id: CHANGE_LINE, type: 'line', source: SOURCE, filter: BASE[CHANGE_LINE],
layout: { 'line-join': 'round' },
paint: { 'line-color': colour, 'line-width': 1, 'line-opacity': ['case', ['==', ['get', '$change'], 'gained'], 0.9, 0.5],
'line-dasharray': [3, 2] } });
map.addLayer({ id: TRAIL_LINE, type: 'line', source: SOURCE, filter: BASE[TRAIL_LINE],
layout: { 'line-cap': 'butt', 'line-join': 'round' },
paint: { 'line-color': colour, 'line-width': ['coalesce', ['get', 'stroke_width'], 2], 'line-opacity': 0.55,
'line-dasharray': [2, 2] } });
map.addLayer({ id: TRAIL_DOT, type: 'circle', source: SOURCE, filter: BASE[TRAIL_DOT],
paint: { 'circle-radius': 5, 'circle-color': 'rgba(0, 0, 0, 0)', 'circle-stroke-color': colour,
'circle-stroke-width': 1.5, 'circle-stroke-opacity': 0.7 } });
map.addLayer({ id: NEW_LINE, type: 'line', source: SOURCE, filter: BASE[NEW_LINE],
layout: { 'line-cap': 'round', 'line-join': 'round' },
paint: { 'line-color': NEW_COLOUR, 'line-width': ['+', 6, ['coalesce', ['get', 'stroke_width'], 2]], 'line-opacity': 0.6, 'line-blur': 2 } });
map.addLayer({ id: NEW_RING, type: 'circle', source: SOURCE, filter: BASE[NEW_RING],
paint: { 'circle-radius': ['*', 15, ['coalesce', ['get', 'icon_scale'], 1]], 'circle-color': 'rgba(255, 212, 0, 0.18)',
'circle-stroke-color': NEW_COLOUR, 'circle-stroke-width': 2.5, 'circle-blur': 0.1 } });
}
map.addLayer({
id: FILL,
type: 'fill',
source: SOURCE,
filter: BASE[FILL],
paint: { 'fill-color': colour, 'fill-opacity': ['case', ['has', '$fade'], 0.07, ['==', ['get', 'area_fill'], 'none'], 0,
['coalesce', ['get', 'fill_opacity'], 0.18]] },
});
// a personal area's hatching, or any layer's that a plate hatches
if (hatched) map.addLayer({ id: FILL_HATCH, type: 'fill', source: SOURCE, filter: BASE[FILL_HATCH],
paint: { 'fill-pattern': ['get', '$fillhatch'] } });
map.addLayer({
id: LINE,
type: 'line',
source: SOURCE,
filter: BASE[LINE],
layout: { 'line-cap': 'round', 'line-join': 'round' },
paint: { 'line-color': colour, 'line-width': ['coalesce', ['get', 'stroke_width'], 2], 'line-opacity': ['case', ['has', '$fade'], 0.35, 0.9] },
});
// a dash cannot be read off a feature, so each look is its own layer
for (const [id, dash, cap] of [[LINE_DASH, [3, 2], 'butt'], [LINE_DOT, [0.1, 2], 'round']]) {
map.addLayer({ id, type: 'line', source: SOURCE, filter: BASE[id], layout: { 'line-cap': cap, 'line-join': 'round' },
paint: { 'line-color': colour, 'line-width': ['coalesce', ['get', 'stroke_width'], 2],
'line-opacity': ['case', ['has', '$fade'], 0.35, 0.9], 'line-dasharray': dash } });
}
if (editable) {
map.addSource(ARROW_SOURCE, { type: 'geojson', data: { type: 'FeatureCollection', features: [] } });
map.addLayer({ id: ARROW, type: 'symbol', source: ARROW_SOURCE, filter: BASE[ARROW],
layout: { 'icon-image': ['get', '$arrowicon'], 'icon-rotate': ['get', '$angle'], 'icon-rotation-alignment': 'map',
'icon-size': ['max', 0.45, ['*', 0.22, ['coalesce', ['get', 'stroke_width'], 2]]],
'icon-allow-overlap': true, 'icon-ignore-placement': true },
paint: { 'icon-opacity': ['case', ['has', '$fade'], 0.35, 0.95] } });
}
// Under the symbols, and only while they are being dropped: far out, the
// collision below hides most of a dense layer, and a dot per feature is what
// keeps the map honest about how much is really there. Close in, every
// symbol is placed, so the same dot is just a bead stuck under each pin —
// it fades out over the zooms where that changes.
map.addLayer({
id: DOT,
type: 'circle',
source: SOURCE,
filter: BASE[DOT],
paint: {
'circle-radius': declutter ? ['interpolate', ['linear'], ['zoom'], 11, 2.5, 14, 0] : 0,
'circle-color': colour,
'circle-opacity': 0.85,
},
});
// Under the marker it turns around, so the badge always reads first.
if (editable && !map.hasImage?.(BEARING_ICON)) {
const wedge = bearingImage();
if (wedge) map.addImage(BEARING_ICON, wedge);
}
if (editable) map.addLayer({
id: BEARING,
type: 'symbol',
source: SOURCE,
filter: BASE[BEARING],
layout: {
'icon-image': BEARING_ICON,
'icon-size': ['*', ICON_SCALE, ['coalesce', ['get', 'icon_scale'], 1]],
'icon-rotate': ['get', 'bearing'],
'icon-rotation-alignment': 'map',
'icon-allow-overlap': true,
'icon-ignore-placement': true,
},
});
map.addLayer({
id: MARK,
type: 'symbol',
source: SOURCE,
filter: BASE[MARK],
layout: {
'icon-image': ['get', '$icon'],
'icon-size': ['*', editable ? PERSONAL_PIN_SCALE : ICON_SCALE, ['coalesce', ['get', 'icon_scale'], 1]],
'icon-anchor': 'bottom',
'icon-offset': [0, ICON_PAD],
// The decluttering, and the whole of it: MapLibre hides a symbol that
// overlaps one already placed, so the map spreads evenly and densifies
// as it is zoomed into. A cap in file order would clump.
'icon-allow-overlap': editable || !declutter,
'icon-ignore-placement': editable || !declutter,
// …and who wins a contested spot. File order, so the answer is at least
// the same one twice running.
// a feature with no place in the file (one drawn by hand) comes first, never a null the engine warns of
'symbol-sort-key': ['coalesce', ['get', 'index'], 0],
},
paint: {
'icon-color': colour,
// an event past its day reads faintly, as what has happened rather than what stands
'icon-opacity': ['case', ['has', '$fade'], 0.4, ['coalesce', ['get', '$opacity'], 0.95]],
'icon-halo-color': ICON_OUTLINE,
'icon-halo-width': ICON_OUTLINE_WIDTH,
'icon-halo-blur': 0.2,
// The anchor is the image's bottom edge, and the padding that gives the
// outline room to draw sits between that edge and the pin's tip. Without
// this the pin floats its own padding above the ground, which reads as
// the dot underneath having come loose from it.
},
});
// The source's own pictures, which is a separate layer rather than a second
// `icon-image` on the one above: these are plain PNGs, the ones above are
// SDFs, and MapLibre does not reliably render both out of one symbol layer.
// Personal markers also use these bitmap layers so their group order holds
// across plain pins and badges. Colour and outline are already in the pixels.
map.addLayer({
id: OWN,
type: 'symbol',
source: SOURCE,
filter: BASE[OWN],
layout: {
'icon-image': ['get', '$own'],
'icon-size': ['*', ['case', editable ? ['any', ['has', '$badge'], ['has', '$native']] : ['has', '$badge'], ICON_SCALE, SOURCE_ICON_SCALE], ['coalesce', ['get', 'icon_scale'], 1]],
// The anchor is the middle because the backend padded each image until
// the pixel the source anchors it by *was* the middle — a pin's tip
// lands on the ground without a per-feature offset to carry.
'icon-anchor': editable ? ['case', ['has', '$native'], 'bottom', 'center'] : 'center',
'icon-offset': editable ? ['case', ['has', '$native'], ['literal', [0, 7.7]], ['literal', [0, 0]]] : [0, 0],
'icon-allow-overlap': editable || !declutter,
'icon-ignore-placement': editable || !declutter,
'symbol-sort-key': ['coalesce', ['get', 'index'], 0],
},
paint: { 'icon-opacity': ['case', ['has', '$fade'], 0.4, ['coalesce', ['get', '$opacity'], 0.95]] },
});
// A group's names, written under its marks once the analyst asks for them.
if (editable) map.addLayer({
id: LABEL,
type: 'symbol',
source: SOURCE,
filter: BASE[LABEL],
layout: {
'text-field': ['get', 'name'],
'text-font': LABEL_FONT,
'text-size': ['coalesce', ['get', 'label_size'], 11],
'text-anchor': 'top',
'text-offset': [0, 0.9],
'text-max-width': 10,
'text-optional': true,
'symbol-placement': 'point',
},
paint: { 'text-color': '#fff', 'text-halo-color': 'rgba(0, 0, 0, 0.85)', 'text-halo-width': 1.3 },
});
if (editable) {
// Personal points are all visible, so a circle gives them a reliable hit
// area even on engines that miss the symbol's painted pixels.
map.addLayer({ id: HIT, type: 'circle', source: SOURCE,
filter: BASE[HIT],
paint: { 'circle-radius': ['max', 12, ['*', 22, ['coalesce', ['get', 'icon_scale'], 1]]], 'circle-opacity': 0 } });
map.addLayer({ id: HIT_OWN, type: 'circle', source: SOURCE,
filter: BASE[HIT_OWN],
paint: { 'circle-radius': ['max', 10, ['*', ['case', ['has', '$native'], 22, 13], ['coalesce', ['get', 'icon_scale'], 1]]], 'circle-opacity': 0 } });
}
if (!owners.has(map)) owners.set(map, new Map());
owners.get(map).set(prefix, { layers: PAINTED, active: () => interactive && shown });
bindHandlers();
if (!shown) applyVisibility();
}
/**
* Where a pin stands, as the source wrote it, or null for a line or an area.
*
* Read off the collection rather than off the feature the engine hands back:
* that one is rebuilt out of a tile, its position rounded to the tile's grid,
* which far out is tens of metres. The number the backend gave every feature
* finds the original.
*/
function pointOf(feature) {
const original = featureAt(collection, feature?.properties?.index);
const geometry = original?.geometry ?? feature?.geometry;
if (geometry?.type !== 'Point') return null;
const [lon, lat] = geometry.coordinates ?? [];
if (!Number.isFinite(lat) || !Number.isFinite(lon)) return null;
return { lat, lon: wrapLon(lon) };
}
/**
* The card and the point menu, the only two things a feature answers.
*
* The caller builds the card and supplies personal-layer actions. The menu
* is the map's own, moved onto the pin's point. Saving a case place remains
* an explicit action.
*/
function bindHandlers() {
const bind = (type, handler) => {
map.on(type, PAINTED, handler);
listeners.push([type, PAINTED, handler]);
};
bind('click', (event) => {
const feature = event.features?.[0];
if (!feature || !interactive || !ownsClick(event)) return;
showCard(feature, event.lngLat);
});
bind('contextmenu', (event) => {
if (!menu || !interactive || !ownsClick(event)) return;
const features = event.features ?? [];
// a pin drawn over an area is the pin that was meant
const feature = features.find((one) => pointOf(one)) ?? features[0];
if (!feature) return;
const point = pointOf(feature);
const at = point ?? { lat: event.lngLat.lat, lon: wrapLon(event.lngLat.lng) };
menu({ ...at, x: event.point.x, y: event.point.y }, point ? (feature.properties ?? {}) : null);
});
bind('mouseenter', () => {
if (interactive) map.getCanvas().style.cursor = 'pointer';
});
bind('mouseleave', () => {
if (interactive) map.getCanvas().style.cursor = '';
});
if (interactive) releaseClicks = engine.claimClicks?.(PAINTED) ?? null;
}
function ownsClick(event) {
if (!map.queryRenderedFeatures || !event.point) return true;
const painted = [...(owners.get(map)?.values() ?? [])]
.filter((owner) => owner.active()).flatMap((owner) => owner.layers)
.filter((id) => map.getLayer(id));
const hits = map.queryRenderedFeatures(event.point, { layers: painted });
const top = hits.find((hit) => hit.geometry?.type === 'Point') ?? hits[0];
return !top || PAINTED.includes(top.layer?.id);
}
/**
* Open the card on a feature, hung off the feature's own point.
*
* Not off the cursor: a pin is clicked on its head, a good twenty pixels above
* the ground it claims, and the two are then the same *ground* distance apart
* at every zoom — which shows on screen as the card sliding away from its own
* mark the further you zoom in. A point states where it is, so that is what
* the card is pinned to; an edge or an area has no one point, and is read
* where it was touched.
*/
function showCard(feature, at) {
if (!card) return;
closeCard();
const point = pointOf(feature);
// measured off the original, never the tile's copy: that one is clipped at the tile's edge
const geometry = featureAt(collection, feature.properties?.index)?.geometry ?? null;
open = popup(point ? PIN_CARD_OFFSET : EDGE_CARD_OFFSET)
.setLngLat(point ? [point.lon, point.lat] : at)
.setDOMContent(card(feature.properties ?? {}, point, geometry))
.addTo(map);
open.on('close', () => {
open = null;
});
}
function closeCard() {
open?.remove();
open = null;
}
/**
* Register every source icon these features ask for, and say which arrived.
*
* The whole of the fallback, and the reason it needs no switch on the panel:
* a key that is not in the returned set is a key no feature is routed by, so
* an icon that 404s, decodes badly or times out leaves its features drawing
* the app's own pictogram in the source's colour. One layer being undressed is
* not a map that stopped working.
*
* All of them at once rather than in turn: they are a few dozen small files
* off localhost, and doing them serially would show as the icons appearing
* one by one.
*/
async function registerSourceIcons(features) {
const arrived = new Set();
if (!iconUrl) return arrived;
// a personal layer composes its own icons into discs and marks, so it keeps the pictures too
if (editable) {
const wanted = new Set(features.map((feature) => feature?.properties?.icon).filter((key) => key && !pictures.has(iconUrl(key))));
await Promise.all([...wanted].map(async (key) => {
const picture = await readPicture(iconUrl(key));
if (picture) pictures.set(iconUrl(key), picture);
}));
}
const keys = new Set();
for (const feature of features) {
const key = feature?.properties?.icon;
if (key) keys.add(key);
}
await Promise.all(
[...keys].map(async (key) => {
const name = sourceIconName(iconUrl(key));
if (map.hasImage?.(name)) {
arrived.add(key);
return;
}
try {
const image = await loadIcon(map, iconUrl(key));
if (!image) return;
// checked again: the same layer drawn twice can be loading it twice
if (!map.hasImage?.(name)) map.addImage(name, image);
arrived.add(key);
} catch {
/* this key's features keep the pictogram they already had */
}
})
);
return arrived;
}
/** What a personal feature's own look adds to its properties: its dash, its hatching, its strength. */
function lookOf(feature, colour) {
const properties = feature.properties ?? {};
const point = String(feature.geometry?.type).includes('Point');
const look = {};
const dash = properties.line_dash || (editable ? CONFIDENCE_DASH[properties.confidence] : '');
if (!point && (dash === 'dashed' || dash === 'dotted')) look.$dash = dash;
// hatched: a personal area asked so, or a plate hatches the layer
if (String(feature.geometry?.type).includes('Polygon') && properties.area_fill === 'hatch') {
const id = `${prefix}-fillhatch-${String(colour).replace(/[^0-9a-z]/gi, '')}`;
if (!map.hasImage(id)) {
const pixels = buildHatch(colour, 'gained');
if (pixels) { map.addImage(id, pixels); badgeIcons.add(id); }
}
if (map.hasImage(id)) look.$fillhatch = id;
}
if (!editable) return Object.keys(look).length ? look : null;
if (point && CONFIDENCE_OPACITY[properties.confidence]) look.$opacity = CONFIDENCE_OPACITY[properties.confidence];
return Object.keys(look).length ? look : null;
}
function arrowIcon(colour) {
const id = `${prefix}-arrowhead-${String(colour).replace(/[^0-9a-z]/gi, '')}`;
if (!map.hasImage(id)) {
const pixels = arrowHeadImage(colour);
if (pixels) { map.addImage(id, pixels); badgeIcons.add(id); }
}
return id;
}
function applyVisibility() {
for (const layer of DRAWN) {
if (map.getLayer(layer)) {
map.setLayoutProperty(layer, 'visibility', shown ? 'visible' : 'none');
}
}
}
return {
/**
* Put a parsed collection on the map. Every feature, whenever any changed: the
* source is the whole layer and the engine culls what is off screen.
*
* `held`, when given, is what `hide` holds off the map from now on, changed
* with the data rather than before it: features the editor dragged come back
* where they landed, never for a frame where they were.
*/
async set(data, { categories: groups = [], hidden = [], period = null, attribution, held = null } = {}) {
build(attribution);
categories = groups;
collection = data;
const mine = ++generation;
// Before the data, not after: a feature is only routed to the source-icon
// layer once its image is registered, so there is no frame in which a
// point asks for a picture the map does not have and draws nothing.
const ready = await registerSourceIcons(data?.features ?? []);
if (mine !== generation || !built) return;
const colour = colourExpression(groups);
// The same features handed again, as a layer read back after its own save is,
// are not cut again: the engine would tile the whole layer anew to draw the same.
const style = JSON.stringify([groups, [...ready].sort().map((key) => iconUrl(key))]);
const unchanged = sent?.style === style && sameFeatures(sent.features, data?.features ?? []);
sent = { style, features: [...(data?.features ?? [])] };
// nothing to cut, but a frame still comes for whoever waits for the map to settle
if (unchanged) map.triggerRepaint?.();
const features = unchanged ? [] : (data?.features ?? []).map((feature) => {
const symbol = feature.properties?.symbol || 'pin';
const groupAt = Math.max(0, groups.findIndex((group) => group.name === feature.properties?.category));
const colour = feature.properties?.colour || categoryColour(groups[groupAt], groupAt);
let badge = null;
if (feature.properties?.$change) {
const kind = feature.properties.$change === 'gained' ? 'gained' : 'lost';
const id = `${prefix}-hatch-${kind}-${String(colour).replace(/[^0-9a-z]/gi, '')}`;
if (!map.hasImage(id)) {
const pixels = buildHatch(colour, kind);
if (pixels) { map.addImage(id, pixels); badgeIcons.add(id); }
}
return { ...feature, properties: { ...feature.properties, $hatch: id } };
}
const own = lookOf(feature, colour);
if (own) feature = { ...feature, properties: { ...feature.properties, ...own } };
const native = editable && !isBadge(symbol) && !ready.has(feature.properties?.icon);
const wearing = editable && feature.geometry?.type === 'Point' && ready.has(feature.properties?.icon)
? pictures.get(iconUrl(feature.properties.icon)) : null;
if (wearing) {
// one of the analyst's icons: drawn plain when it can be, composed when a disc or a mark is asked for
const mode = feature.properties.icon_mode === 'disc' ? 'disc' : 'image';
const marks = { status: feature.properties?.status ?? '', external: feature.properties?.provenance === 'external' };
if (mode === 'disc' || marks.status || marks.external) {
const id = `${prefix}-own-${feature.properties.icon}-${mode}-${markerImageKey('', colour, marks)}`;
if (!map.hasImage(id)) {
const pixels = buildOwn(wearing, colour, { mode, ...marks });
if (pixels) { map.addImage(id, pixels); badgeIcons.add(id); }
}
if (map.hasImage(id)) badge = id;
}
} else if (feature.geometry?.type === 'Point' && (isBadge(symbol) || native)) {
const marks = { status: feature.properties?.status ?? '', external: feature.properties?.provenance === 'external' };
const id = `${prefix}-${markerImageKey(symbol, colour, marks)}`;
if (!map.hasImage(id)) {
const pixels = native ? buildPersonal(symbol || 'pin', colour, marks) : buildBadge(symbol, colour, marks);
if (pixels) { map.addImage(id, pixels); badgeIcons.add(id); }
}
if (map.hasImage(id)) badge = id;
}
return {
...feature,
properties: {
...feature.properties,
// Resolved into the data rather than expressed per layer, because the
// icon has to be chosen per feature and the colour has to fall back
// per feature when the source painted only some of them.
$icon: markerIcon(feature.geometry, feature.properties?.symbol),
...(badge ? { $own: badge, ...(native ? { $native: true } : { $badge: true }) } : ready.has(feature.properties?.icon)
? { $own: sourceIconName(iconUrl(feature.properties.icon)) }
: null),
},
}; });
const arrows = editable && !unchanged ? features.flatMap((feature) => {
const heads = arrowHeads(feature);
if (!heads.length) return [];
const groupAt = Math.max(0, groups.findIndex((group) => group.name === feature.properties?.category));
const icon = arrowIcon(feature.properties?.colour || categoryColour(groups[groupAt], groupAt));
return heads.map(({ at, angle }) => ({ type: 'Feature', geometry: { type: 'Point', coordinates: at },
properties: { ...feature.properties, $angle: angle, $arrowicon: icon } }));
}) : [];
// a layer with no arrow heads leaves their source empty rather than emptying it again
if (editable && !unchanged && (arrows.length || arrowsSent)) {
map.getSource(ARROW_SOURCE)?.setData({ type: 'FeatureCollection', features: arrows });
arrowsSent = arrows.length > 0;
}
if (!unchanged) {
const symbols = [...new Set(features.map((feature) => feature.properties.symbol))]
.filter((symbol) => ['circle', 'star', 'flag'].includes(symbol));
registerIcons(map, iconImage, symbols);
map.getSource(SOURCE)?.setData({ type: 'FeatureCollection', features });
}
for (const layer of DRAWN) {
if ([OWN, HIT, HIT_OWN, BEARING, LABEL, CHANGE_FILL, NEW_LINE, NEW_RING, FILL_HATCH, ARROW].includes(layer) || !map.getLayer(layer)) continue;
const property = layer === MARK ? 'icon-color' : layer === FILL ? 'fill-color' : layer === DOT ? 'circle-color'
: layer === TRAIL_DOT ? 'circle-stroke-color' : 'line-color';
map.setPaintProperty(layer, property, featureColour(colour));
}
if (held) hiddenKeys = new Set(held);
filtered = '';
this.filter(hidden, period);
},
/**
* Once the map has drawn what `set` last handed it. The engine cuts a layer's
* tiles off the page's thread, so new data is on screen some frames after it
* was set. Bounded, since a map kept busy may not say so for a while.
*/
drawn(ms = 400) {
if (!built || typeof map.isSourceLoaded !== 'function') return Promise.resolve();
const sources = [SOURCE, ...(editable ? [ARROW_SOURCE] : [])];
return new Promise((resolve) => {
let timer = null;
const done = () => { clearTimeout(timer); map.off('render', check); resolve(); };
// a frame is only drawn from tiles that were cut before it began
function check() { if (sources.every((id) => !map.getSource(id) || map.isSourceLoaded(id))) done(); }
timer = setTimeout(done, ms);
map.on('render', check);
map.triggerRepaint?.();
});
},
/**
* Hide exactly the categories named and the days outside the period, and
* nothing else.
*
* A filter rather than a second source: the features stay loaded, so the row
* can keep saying how many there are while saying how many are drawn. The
* same filter twice is applied once, since a dragged time strip asks on every
* frame and a card opened on the map would otherwise close under it.
*/
filter(hidden = [], period = null) {
lastFilter = [hidden, period];
if (!built) return;
const key = JSON.stringify([hidden, period?.start ?? '', period?.end ?? '', [...hiddenKeys]]);
if (key === filtered) return;
filtered = key;
const rules = [visibilityFilter(hidden), periodFilter(period), hiddenKeys.size
? ['!', ['in', ['get', 'key'], ['literal', [...hiddenKeys]]]] : null].filter(Boolean);
const rule = rules.length > 1 ? ['all', ...rules] : rules[0];
for (const layer of DRAWN) {
if (!map.getLayer(layer)) continue;
map.setFilter(layer, rule ? ['all', BASE[layer], rule] : BASE[layer]);
}
closeCard();
},
/**
* Frame one feature and open its card — what picking a search result does.
*
* The second way into this layer, and deliberately the same one: it ends at
* the card a click ends at, which states what the source says and offers no
* route from it into the case. Finding a feature is not adopting it.
*
* False when the number names nothing here, which is what a card opened on
* the wrong feature would otherwise be.
*/
reveal(index) {
const feature = featureAt(collection, index);
const extent = feature && featureExtent(feature.geometry);
if (!extent) return false;
engine.fitBounds(extent, {
padding: REVEAL_PADDING,
maxZoom: REVEAL_ZOOM,
animate: true,
});
showCard(feature, [(extent.west + extent.east) / 2, (extent.south + extent.north) / 2]);
return true;
},
/** The feature numbered `index` as the source wrote it, not as a tile cut it. */
feature(index) {
return featureAt(collection, index);
},
/** The lowest of this layer's GL layers, or null while nothing is built. */
floor() {
const lowest = DRAWN[0];
return built && map.getLayer(lowest) ? lowest : null;
},
/**
* Move every GL layer of this one, in its own order, to just under `other`,
* another added layer. Nothing moves until both are built.
*/
stackUnder(other) {
const below = other?.floor();
if (!built || !below) return;
for (const layer of DRAWN) {
if (map.getLayer(layer)) map.moveLayer(layer, below);
}
},
/**
* Hold these features off the map, or none: the editor draws them where the
* analyst is dragging them until the layer draws them where they landed.
*/
hide(keys = []) {
const next = new Set(keys);
if (next.size === hiddenKeys.size && [...next].every((key) => hiddenKeys.has(key))) return;
hiddenKeys = next;
if (built) this.filter(...lastFilter);
},
/** Keep the features, take them off the map (or put them back). */
visible(on) {
shown = on;
if (!built) return;
applyVisibility();
if (!on) closeCard();
},
/**
* Whether a feature answers a click. Off, its clicks reach the map's own
* tool underneath, as if the layer were a picture; on, a click opens its card.
*/
interactive(on) {
if (on === interactive) return;
interactive = on;
if (!built) return;
if (on) releaseClicks ??= engine.claimClicks?.(PAINTED) ?? null;
else {
releaseClicks?.();
releaseClicks = null;
closeCard();
}
},
/** What the legend is painting, so a caller can read it back. */
categories() {
return categories;
},
destroy() {
closeCard();
owners.get(map)?.delete(prefix);
collection = null;
generation += 1;
releaseClicks?.();
releaseClicks = null;
for (const [type, on, handler] of listeners) map.off(type, on, handler);
listeners.length = 0;
if (built) {
for (const layer of DRAWN) {
if (map.getLayer(layer)) map.removeLayer(layer);
}
if (map.getSource(SOURCE)) map.removeSource(SOURCE);
if (map.getSource(ARROW_SOURCE)) map.removeSource(ARROW_SOURCE);
}
for (const id of badgeIcons) if (map.hasImage(id)) map.removeImage?.(id);
badgeIcons.clear();
built = false;
},
};
}
/**
* The source's own colour where it stated one, the category's where it did not.
*
* Per feature, because a My Maps often paints half a folder and leaves the rest
* on the default — and a legend row saying one colour while half its marks draw
* another is exactly the kind of quiet lie this feature must not tell.
*/
function featureColour(fallback) {
return ['case', ['!=', ['get', 'colour'], ''], ['to-color', ['get', 'colour']], fallback];
}
/**
* The feature the backend numbered `index`, or nothing.
*
* The number *is* the position — `_collection` writes it while it fills the
* array — so the hit is direct. The scan behind it costs nothing on the miss
* that cannot happen, and what it rules out is a card opened on the wrong
* feature, which on a map somebody makes decisions from is the failure worth
* two lines to refuse.
*/
export function featureAt(collection, index) {
const features = collection?.features ?? [];
const at = features[index];
if (at?.properties?.index === index) return at;
return features.find((feature) => feature?.properties?.index === index) ?? null;
}
/**
* Where one feature is, as a box to frame the camera on.
*
* A point gives a box with no extent, which the façade answers by clamping to
* the ceiling it was given — so a pin, a road and a district are one rule here
* rather than three. Nothing is materialised: a traced coastline is half a
* million points, and the four numbers are all that is wanted from them.
*/
export function featureExtent(geometry) {
let north = -Infinity;
let south = Infinity;
let east = -Infinity;
let west = Infinity;
eachCoordinate(geometry, (lon, lat) => {
west = Math.min(west, lon);
east = Math.max(east, lon);
south = Math.min(south, lat);
north = Math.max(north, lat);
});
return west > east ? null : { north, south, east, west };
}
/** Mirrors the backend's `_coordinates`: every position, however nested. */
function eachCoordinate(geometry, visit) {
if (geometry?.type === 'GeometryCollection') {
for (const child of geometry.geometries ?? []) eachCoordinate(child, visit);
return;
}
walk(geometry?.coordinates, visit);
}
function walk(node, visit) {
if (!Array.isArray(node)) return;
if (node.length >= 2 && typeof node[0] === 'number' && typeof node[1] === 'number') {
visit(node[0], node[1]);
return;
}
for (const child of node) walk(child, visit);
}
/** Mirrors the backend's `_kind`: three shapes, and nothing finer. */
export function kindOf(geometry) {
const type = String(geometry?.type ?? '');
if (type.includes('Point')) return 'point';
if (type.includes('Line')) return 'line';
return 'area';
}