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.
This commit is contained in:
Sameh Khamis committed 2026-11-11 20:05:25 -08:00
1 parent 7b07ddeefd
commit 7f500a551c
5 files changed
+181 -58

No files matched your search

+4 -2
View File
@@ -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. */
+48 -32
View File
@@ -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,
+32 -5
View File
@@ -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;
}
+90 -15
View File
@@ -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 () => {