From 7f500a551c1d3b1d8c45a1f53e0c05d307e72141 Mon Sep 17 00:00:00 2001 From: Sameh Khamis Date: Wed, 11 Nov 2026 20:05:25 -0800 Subject: [PATCH] vectorBase: a value that cannot be evaluated is the property's default, as in MapLibre A paint or layout value that throws for a feature (a type that does not fit, step or interpolate over what is not a number) or comes to null, undefined or NaN is now the property's default, and a legacy function's miss is its default, else the property's; only a filter that cannot be evaluated leaves the feature out. The canvas still never keeps the last feature's colour or width. A background colour given as rgba numbers is the style's background rather than none. --- docs/RENDERER-CONTRACT.md | 11 ++- src/render/vectorBase/expressions.js | 6 +- src/render/vectorBase/paint.js | 80 ++++++++++------- src/render/vectorBase/style.js | 37 ++++++-- src/render/vectorBase/vectorBase.test.mjs | 105 ++++++++++++++++++---- 5 files changed, 181 insertions(+), 58 deletions(-) diff --git a/docs/RENDERER-CONTRACT.md b/docs/RENDERER-CONTRACT.md index 504e27e7d..6aea35878 100644 --- a/docs/RENDERER-CONTRACT.md +++ b/docs/RENDERER-CONTRACT.md @@ -345,10 +345,13 @@ What it draws of the style specification: `sky` layers; layers on raster sources; layers setting a pattern (`fill-pattern`, `line-pattern`, `background-pattern`), `line-offset`, `line-gradient` or a translation; layers whose values use an expression - not listed (or are malformed). A feature whose values cannot be evaluated - (a type that does not fit, a `step` or `interpolate` over what is not a - number, or a value that comes to nothing: null, or not a finite number - where one is needed) is left out. Nothing unsupported throws. + not listed (or are malformed). As MapLibre does, a paint or layout value + that cannot be evaluated for a feature (a type that does not fit, a + `step` or `interpolate` over what is not a number) or comes to nothing + (null, or not a finite number where one is needed) is the property's + default; a legacy function's miss is its `default`, else the property's. + A feature whose filter cannot be evaluated is left out. Nothing + unsupported throws. - Ignored: icons (`icon-image`, sprites: a symbol layer draws its text alone), text along lines (drawn level), `glyphs` (system fonts), and any other paint or layout property not listed above. diff --git a/src/render/vectorBase/expressions.js b/src/render/vectorBase/expressions.js index 87a4d5989..8c36af642 100644 --- a/src/render/vectorBase/expressions.js +++ b/src/render/vectorBase/expressions.js @@ -5,8 +5,10 @@ * value is compiled once into a function of `{zoom, properties, type, id}` * (`type` is `'Point'`, `'LineString'` or `'Polygon'`). Compiling throws an * {@link Unsupported} for what is not covered, so the caller skips the layer; - * a compiled function that meets a value it cannot handle throws one too, so - * the caller skips the feature. Nothing here guesses. + * a compiled function that meets a value it cannot handle throws one too: a + * filter that throws leaves the feature out, a paint or layout value that + * throws is the property's default (as MapLibre takes it). Nothing here + * guesses. */ /** What the painter does not evaluate: the layer or feature is skipped. */ diff --git a/src/render/vectorBase/paint.js b/src/render/vectorBase/paint.js index c0be1ed00..a12566e46 100644 --- a/src/render/vectorBase/paint.js +++ b/src/render/vectorBase/paint.js @@ -9,8 +9,9 @@ * `z + log2(size / 512)` (at least 0), as a 512 px style tile at that zoom shows the * same ground; sizes in the style are pixels of the painted tile. A source * past its `maxzoom` is drawn from its deepest tile over this one (over- - * zoomed); below its `minzoom` it draws nothing. A feature whose filter or - * values cannot be evaluated is left out. + * zoomed); below its `minzoom` it draws nothing. A feature whose filter + * cannot be evaluated is left out; a value that cannot be is the property's + * default. * * Labels are placed top layer first (a layer's own in their features' order * in the tile), each kept clear of those placed @@ -22,7 +23,7 @@ */ import { PbfReader } from 'pbf'; import { VectorTile } from '@mapbox/vector-tile'; -import { cssOf, fillTokens, Unsupported } from './expressions.js'; +import { cssOf, fillTokens } from './expressions.js'; /** The tile size style zooms are given for, pixels. */ export const STYLE_TILE_SIZE = 512; @@ -93,35 +94,49 @@ function sourceTile(style, url, fetchImpl) { return tile; } -/** A value of a layer for a feature; throws where it cannot be evaluated. */ -const valueOf = (layer, key, f) => layer.values[key]?.(f); +/** Whether a value is nothing: null, undefined or a number that is not one. */ +const nothing = (v) => + v === null || + v === undefined || + (typeof v === 'number' && !Number.isFinite(v)); /** - * A number value; throws (the feature is left out) for null, undefined or - * what is not a finite number, which a canvas would ignore, keeping the - * last feature's. + * A value of a layer for a feature. One that cannot be evaluated, or comes + * to nothing, is the property's default, as MapLibre takes it (never the + * last feature's, which a canvas given nothing would keep). */ +function valueOf(layer, key, f) { + let v; + try { + v = layer.values[key]?.(f); + } catch { + v = undefined; + } + return nothing(v) ? layer.defaults?.[key] : v; +} + +/** A number value; the property's default for one that is not a number. */ function numberOf(layer, key, f) { const v = valueOf(layer, key, f); - const n = v === null || v === undefined || v === '' ? NaN : Number(v); - if (!Number.isFinite(n)) throw new Unsupported(`${key} is ${v}`); - return n; + const n = typeof v === 'number' || typeof v === 'string' ? Number(v) : NaN; + return Number.isFinite(n) && v !== '' ? n : Number(layer.defaults?.[key]); } -/** A colour value as CSS; throws, as {@link numberOf}, for no colour. */ -function colorOf(layer, key, f) { - const v = valueOf(layer, key, f); - if (typeof v === 'string' && v.trim()) return v; - if (Array.isArray(v) && v.length === 4 && v.every(Number.isFinite)) - return cssOf(v); - throw new Unsupported(`${key} is ${v}`); +/** A colour as CSS, a string or `[r, g, b, a]`; else the default (or `or`). */ +function colorOf(layer, key, f, or = layer.defaults?.[key]) { + const css = (v) => { + if (typeof v === 'string' && v.trim()) return v; + if (Array.isArray(v) && v.length === 4 && v.every(Number.isFinite)) + return cssOf(v); + return null; + }; + return css(valueOf(layer, key, f)) ?? css(or); } -/** A keyword value (`line-cap`, `line-join`); throws for no string. */ +/** A keyword value (`line-cap`, `line-join`); the default for no string. */ function keywordOf(layer, key, f) { const v = valueOf(layer, key, f); - if (typeof v !== 'string' || !v) throw new Unsupported(`${key} is ${v}`); - return v; + return typeof v === 'string' && v ? v : layer.defaults?.[key]; } /** Paths a feature's rings or lines in tile pixels. */ @@ -273,7 +288,7 @@ export async function paintVectorTile( if (!f.type || !layer.filter(f)) continue; drawFeature(ctx, layer, feature, f, at, labels, order); } catch { - // A filter or value not evaluated: the feature is left out. + // A filter not evaluated: the feature is left out. } ctx.globalAlpha = 1; ctx.setLineDash?.([]); @@ -285,8 +300,8 @@ export async function paintVectorTile( /** * Draw a feature of a fill, line or circle layer; queue a symbol's label. - * Every value is evaluated before anything is drawn, so a feature with one - * that cannot be is left out whole. + * Every value is evaluated (to the property's default where it cannot be) + * before anything is drawn. */ function drawFeature(ctx, layer, feature, f, at, labels, order) { const v = (key) => valueOf(layer, key, f); @@ -297,8 +312,9 @@ function drawFeature(ctx, layer, feature, f, at, labels, order) { if (f.type !== 'Polygon') return; const opacity = num('fill-opacity'); const fill = color('fill-color'); + // An outline that comes to nothing is the fill's colour, as MapLibre's. const outline = layer.values['fill-outline-color'] - ? color('fill-outline-color') + ? colorOf(layer, 'fill-outline-color', f, fill) : null; tracePath(ctx, feature.loadGeometry(), at); ctx.globalAlpha = opacity; @@ -324,12 +340,12 @@ function drawFeature(ctx, layer, feature, f, at, labels, order) { const cap = keywordOf(layer, 'line-cap', f); const join = keywordOf(layer, 'line-join', f); const dashes = layer.values['line-dasharray'] && v('line-dasharray'); - const dash = + let dash = Array.isArray(dashes) && gap <= 0 ? dashes.map((d) => Number(d) * width) : null; - if (dash && !dash.every(Number.isFinite)) - throw new Unsupported(`line-dasharray is ${dashes}`); + // A dash array that is not numbers: solid, its default. + if (dash && !dash.every(Number.isFinite)) dash = null; tracePath(ctx, feature.loadGeometry(), at); ctx.globalAlpha = opacity; ctx.strokeStyle = stroke; @@ -393,12 +409,12 @@ function drawFeature(ctx, layer, feature, f, at, labels, order) { } const px = num('text-size'); const offset = layer.values['text-offset'] ? v('text-offset') : [0, 0]; - const dx = Number(offset?.[0] ?? 0) * px; - const dy = Number(offset?.[1] ?? 0) * px; + let dx = Number(offset?.[0] ?? 0) * px; + let dy = Number(offset?.[1] ?? 0) * px; + // An offset that is not numbers: none, its default. + if (!Number.isFinite(dx) || !Number.isFinite(dy)) dx = dy = 0; const maxWidth = (layer.values['text-max-width'] ? num('text-max-width') : 10) * px; - if (!Number.isFinite(dx) || !Number.isFinite(dy)) - throw new Unsupported(`text-offset is ${offset}`); const label = { text, px, diff --git a/src/render/vectorBase/style.js b/src/render/vectorBase/style.js index 6fb012d8f..e95aaac48 100644 --- a/src/render/vectorBase/style.js +++ b/src/render/vectorBase/style.js @@ -6,7 +6,12 @@ * and its background. A layer the painter cannot draw is listed in `skipped` * with the reason, never drawn wrong. */ -import { compileFilter, compileValue, Unsupported } from './expressions.js'; +import { + compileFilter, + compileValue, + cssOf, + Unsupported, +} from './expressions.js'; /** Layer types the painter draws. */ export const PAINTED_TYPES = Object.freeze([ @@ -112,6 +117,19 @@ const DEFAULTS = { }, }; +/** + * Defaults a value that cannot be evaluated falls back to, beyond those the + * painter always reads (`DEFAULTS`): the specification's. + */ +const FALLBACKS = { + symbol: { + 'text-field': '', + 'text-anchor': 'center', + 'text-offset': [0, 0], + 'text-max-width': 10, + }, +}; + /** `url` resolved against `base`; a data or blob URL as it is. */ function resolve(url, base) { if (/^(data|blob):/i.test(url)) return url; @@ -171,6 +189,8 @@ function compileLayer(layer, sources) { maxzoom: layer.maxzoom ?? 24, filter: compileFilter(layer.filter), values, + // What a value that cannot be evaluated, or comes to nothing, is. + defaults: { ...FALLBACKS[type], ...DEFAULTS[type] }, hasText: type === 'symbol' && layout['text-field'] !== undefined, // A text field not an expression fills `{name}` tokens. tokens: !Array.isArray(layout['text-field']), @@ -242,12 +262,19 @@ export async function loadVectorStyle( if (layer.type === 'background' && !background) try { const at = { zoom: 0, properties: {}, type: 'Polygon' }; - const color = layer.values['background-color'](at); + const value = layer.values['background-color'](at); + // A colour as a string, or `[r, g, b, a]` (as `to-color` gives one). + const color = + typeof value === 'string' + ? value + : Array.isArray(value) && + value.length === 4 && + value.every(Number.isFinite) + ? cssOf(value) + : null; const opacity = layer.values['background-opacity'](at); background = - typeof color === 'string' && Number.isFinite(opacity) - ? { color, opacity } - : null; + color && Number.isFinite(opacity) ? { color, opacity } : null; } catch { background = null; } diff --git a/src/render/vectorBase/vectorBase.test.mjs b/src/render/vectorBase/vectorBase.test.mjs index 42e315455..4902ba719 100644 --- a/src/render/vectorBase/vectorBase.test.mjs +++ b/src/render/vectorBase/vectorBase.test.mjs @@ -292,11 +292,12 @@ test('past its maxzoom a source is drawn from its deepest tile, overzoomed', asy assert.equal(asked.length, before); }); -test('a feature whose value cannot be evaluated is left out, the rest drawn', async () => { +test('a value that cannot be evaluated is the property’s default; a filter that cannot leaves the feature out', async () => { const tile = encodeVectorTile({ water: [ { type: 'Polygon', geometry: FULL, properties: { depth: 'deep' } }, { type: 'Polygon', geometry: FULL, properties: { depth: 3 } }, + { type: 'Polygon', geometry: FULL, properties: { depth: 3, rank: 'x' } }, ], }); const { fetch } = fetchOver({ @@ -309,6 +310,7 @@ test('a feature whose value cannot be evaluated is left out, the rest drawn', as type: 'fill', source: 'base', 'source-layer': 'water', + filter: ['<', ['+', ['coalesce', ['get', 'rank'], 0], 1], 5], paint: { 'fill-opacity': ['/', ['get', 'depth'], 10], 'fill-color': '#00f', @@ -321,14 +323,17 @@ test('a feature whose value cannot be evaluated is left out, the rest drawn', as const style = await loadVectorStyle('https://example.test/s.json', fetch); const { canvas, calls } = recordingCanvas(); await paintVectorTile(style, 0, 0, 0, { fetch, canvas }); - assert.equal(calls.filter(([k]) => k === 'fill').length, 1); - assert.deepEqual( - calls - .filter(([k]) => k === '=globalAlpha') - .map(([, v]) => v) - .filter((v) => v !== 1), - [0.3], - ); + // The third's filter adds to a string: left out. The first's opacity + // divides a string: its default, 1. + assert.equal(calls.filter(([k]) => k === 'fill').length, 2); + // The alpha each fill is drawn at. + let alpha; + const filled = []; + for (const [k, v] of calls) { + if (k === '=globalAlpha') alpha = v; + if (k === 'fill') filled.push(alpha); + } + assert.deepEqual(filled, [1, 0.3]); }); test('a legacy function without a type steps on a property that cannot interpolate', () => { @@ -439,7 +444,7 @@ async function paintOne(layer, features) { return calls; } -test('a feature whose colour or width evaluates to nothing is left out, not drawn in the last one’s', async () => { +test('a colour or width that evaluates to nothing is the property’s default, never the last feature’s', async () => { const fills = await paintOne( { id: 'water', @@ -454,10 +459,10 @@ test('a feature whose colour or width evaluates to nothing is left out, not draw ], }, ); - assert.equal(fills.filter(([k]) => k === 'fill').length, 1); + assert.equal(fills.filter(([k]) => k === 'fill').length, 2); assert.deepEqual( fills.filter(([k]) => k === '=fillStyle').map(([, v]) => v), - ['#00f'], + ['#00f', '#000000'], ); const line = [ [ @@ -480,10 +485,14 @@ test('a feature whose colour or width evaluates to nothing is left out, not draw ], }, ); - assert.equal(lines.filter(([k]) => k === 'stroke').length, 1); + assert.equal(lines.filter(([k]) => k === 'stroke').length, 3); assert.deepEqual( lines.filter(([k]) => k === '=strokeStyle').map(([, v]) => v), - ['#f00'], + ['#f00', '#000000', '#0f0'], + ); + assert.deepEqual( + lines.filter(([k]) => k === '=lineWidth').map(([, v]) => v), + [3, 2, 1], ); const circles = await paintOne( { @@ -499,7 +508,73 @@ test('a feature whose colour or width evaluates to nothing is left out, not draw ], }, ); - assert.equal(circles.filter(([k]) => k === 'arc').length, 1); + assert.deepEqual( + circles.filter(([k]) => k === 'arc').map((call) => call[3]), + [4, 5], + 'the second at the default radius', + ); +}); + +test('a step over a missing value, and a categorical miss with no default, are the property’s default', async () => { + const line = [ + [ + [0, 2048], + [4096, 2048], + ], + ]; + const calls = await paintOne( + { + id: 'roads', + type: 'line', + 'source-layer': 'roads', + paint: { + 'line-width': ['step', ['get', 'rank'], 2, 5, 8], + 'line-color': { + property: 'kind', + type: 'categorical', + stops: [['major', '#f00']], + }, + }, + }, + { + roads: [ + { + type: 'LineString', + geometry: line, + properties: { rank: 6, kind: 'major' }, + }, + { type: 'LineString', geometry: line, properties: { kind: 'minor' } }, + ], + }, + ); + assert.deepEqual( + calls.filter(([k]) => k === '=lineWidth').map(([, v]) => v), + [8, 1], + ); + assert.deepEqual( + calls.filter(([k]) => k === '=strokeStyle').map(([, v]) => v), + ['#f00', '#000000'], + ); +}); + +test('a background colour given as rgba numbers is the style’s background', async () => { + const { fetch } = fetchOver({ + 'https://example.test/s.json': { + version: 8, + sources: {}, + layers: [ + { + id: 'bg', + type: 'background', + paint: { + 'background-color': ['to-color', ['literal', [0, 0, 255, 1]]], + }, + }, + ], + }, + }); + const style = await loadVectorStyle('https://example.test/s.json', fetch); + assert.deepEqual(style.background, { color: 'rgba(0,0,255,1)', opacity: 1 }); }); test('labels of one layer are placed in their features’ order, the first winning', async () => {