@tangram.gl/tangram-renderer 0.0.0-stage → 0.0.1

package/src/styles/style_parser.ts

@@ -0,0 +1,620 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import type {PropertyCache, PropertyContext, PropertyFunction, PropertyStop, PropertyTransform, PointSizeCache, PointSizeFlags, PointSizeImage, StyleParserRuntime, UnitValue} from './property-types';
+
+import Utils from '../utils/utils';
+import {compileFunctionString} from '../utils/functions';
+import Geo from '../utils/geo';
+import log from '../utils/log';
+
+import parseCSSColor from 'csscolorparser';
+
+// This macro is stringified and evaluated inside wrapFunction's feature scope.
+declare const feature: {id: string};
+
+// Members are installed below before this object is exposed to callers.
+const StyleParser = {} as StyleParserRuntime;
+export default StyleParser;
+
+// Helpers for string converstion / NaN handling
+const clampPositive = (v: unknown) => Math.max(v as number, 0);
+const noNaN = (v: number) => isNaN(v) ? 0 : v;
+const parseNumber = ((v: unknown) => Array.isArray(v) ? v.map(parseFloat).map(noNaN) : noNaN(parseFloat(v as string))) as StyleParserRuntime['parseNumber'];
+const parsePositiveNumber = ((v: unknown) => Array.isArray(v) ? v.map(parseNumber).map(clampPositive) : clampPositive(parseNumber(v) as number)) as StyleParserRuntime['parsePositiveNumber'];
+
+Object.assign(StyleParser, {clampPositive, noNaN, parseNumber, parsePositiveNumber});
+
+// Wraps style functions and provides a scope of commonly accessible data:
+// - feature: the 'properties' of the feature, e.g. accessed as 'feature.name'
+// - global: user-defined properties on the `global` object in the scene file
+// - $zoom: the current map zoom level
+// - $geometry: the type of geometry, 'point', 'line', or 'polygon'
+// - $meters_per_pixel: conversion for meters/pixels at current map zoom
+StyleParser.wrapFunction = function (func, preserveNaN = false) {
+    var f = `
+        var feature = context.feature.properties;
+        var global = context.global;
+        var $zoom = context.zoom;
+        var $layer = context.layer;
+        var $source = context.source;
+        var $geometry = context.geometry;
+        var $meters_per_pixel = context.meters_per_pixel;
+        var $id = context.id;
+
+        var val = (function(){ ${func} }());
+
+        ${preserveNaN ? '' : `if (typeof val === 'number' && isNaN(val)) {
+            val = null; // convert NaNs to nulls
+        }`}
+
+        return val;
+    `;
+    return f;
+};
+
+
+// Style parsing
+
+StyleParser.zeroPair = Object.freeze([0, 0] as [number, number]); // single allocation for zero values that won't be modified
+
+// Style defaults
+StyleParser.defaults = {
+    color: [1, 1, 1, 1],
+    width: 1,
+    size: 1,
+    extrude: false,
+    height: 20,
+    min_height: 0,
+    order: 0,
+    z: 0,
+    outline: {
+        color: [0, 0, 0, 0],
+        width: 0
+    },
+    material: {
+        ambient: 1,
+        diffuse: 1
+    }
+};
+
+// Style macros
+StyleParser.macros = {
+    // pseudo-random color by geometry id
+    'Style.color.pseudoRandomColor': function() {
+        return [
+            0.7 * (parseInt(feature.id, 16) / 100 % 1),     // eslint-disable-line no-undef
+            0.7 * (parseInt(feature.id, 16) / 10000 % 1),   // eslint-disable-line no-undef
+            0.7 * (parseInt(feature.id, 16) / 1000000 % 1), // eslint-disable-line no-undef
+            1
+        ];
+    },
+
+    // random color
+    'Style.color.randomColor': function() {
+        return [0.7 * Math.random(), 0.7 * Math.random(), 0.7 * Math.random(), 1];
+    }
+};
+
+// A context object that is passed to style parsing functions to provide a scope of commonly used values
+StyleParser.getFeatureParseContext = function (feature, tile, global) {
+    return {
+        feature,
+        id: feature.id,
+        tile,
+        global,
+        zoom: tile.style_z,
+        geometry: Geo.geometryType(feature.geometry.type),
+        meters_per_pixel: tile.meters_per_pixel,
+        meters_per_pixel_sq: tile.meters_per_pixel_sq,
+        units_per_meter_overzoom: tile.units_per_meter_overzoom
+    };
+};
+
+// Build a style param cache object
+// `value` is a raw value, cache methods will add other properties as needed
+// `transform` is an optional, one-time transform function to run on values during setup
+// `dynamic_transform` is an optional post-processing function applied to the result of function-based properties
+const CACHE_TYPE = {
+    STATIC: 0,
+    DYNAMIC: 1,
+    ZOOM: 2
+};
+StyleParser.CACHE_TYPE = CACHE_TYPE;
+
+StyleParser.createPropertyCache = function (obj, transform = null, dynamic_transform = null) {
+    if (obj == null) {
+        return;
+    }
+
+    if ((obj as PropertyCache).value) {
+        return { value: (obj as PropertyCache).value, zoom: ((obj as PropertyCache).zoom ? {} : null), type: (obj as PropertyCache).type }; // clone existing cache object
+    }
+
+    let c: PropertyCache = { value: obj, type: CACHE_TYPE.STATIC };
+
+    // does value contain zoom stops to be interpolated?
+    if (Array.isArray(c.value) && Array.isArray(c.value[0])) {
+        c.zoom = {}; // will hold values interpolated by zoom
+        c.type = CACHE_TYPE.ZOOM;
+    }
+    else if (typeof c.value === 'function') {
+        c.type = CACHE_TYPE.DYNAMIC;
+        c.dynamic_transform = (typeof dynamic_transform === 'function' ? dynamic_transform : null);
+    }
+
+    // apply optional transform function - usually a parsing function
+    if (typeof transform === 'function') {
+        if (c.zoom) { // apply to each zoom stop value
+            c.value = (c.value as PropertyStop[]).map((v, i) => [v[0], transform(v[1], i)]);
+        }
+        else if (typeof c.value !== 'function') { // don't transform functions
+            c.value = transform(c.value, 0); // single value, 0 = the first and only item in the array
+        }
+    }
+
+    return c;
+};
+
+// Convert old-style color macro into a function
+// TODO: deprecate this macro syntax
+StyleParser.createColorPropertyCache = function (obj) {
+    return StyleParser.createPropertyCache(obj, v => {
+        if (v === 'Style.color.pseudoRandomColor') {
+            return compileFunctionString(StyleParser.wrapFunction(StyleParser.macros['Style.color.pseudoRandomColor']));
+        }
+        else if (v === 'Style.color.randomColor') {
+            return StyleParser.macros['Style.color.randomColor'];
+        }
+
+        return v;
+    });
+};
+
+// Parse point sizes, which include optional %-based or aspect-ratio-constrained scaling from sprite size
+// Returns a cache object if successful, otherwise throws error message
+const isPercent = (v: unknown) => typeof v === 'string' && v[v.length-1] === '%'; // size computed by %
+const isRatio = (v: unknown) => v === 'auto'; // size derived from aspect ratio of one dimension
+const isComputed = (v: unknown) => isPercent(v) || isRatio(v);
+const dualRatioError = '\'size\' can specify either width or height as derived from aspect ratio, but not both';
+StyleParser.createPointSizePropertyCache = function (obj, texture) {
+    // obj is the value to be parsed eg "64px" "100%" "auto"
+    // mimics the structure of the size value (at each zoom stop if applicable),
+    // stores flags indicating if each element is a %-based size or not, or derived from aspect
+    let has_pct: PointSizeFlags | null = null;
+    let has_ratio: PointSizeFlags | null = null;
+    if (isPercent(obj)) { // 1D size
+        has_pct = [true];
+    }
+    else if (Array.isArray(obj)) {
+        // track which fields are % vals
+        if (Array.isArray(obj[0])) { // zoom stops
+            // could be a 1D value (that could be a %), or a 2D value (either width or height or both could be a %)
+            if (obj.some(v => Array.isArray(v[1]) ? v[1].some(w => isComputed(w)) : isPercent(v[1]))) {
+                has_pct = obj.map(v => Array.isArray(v[1]) ? v[1].map(w => isPercent(w)) : isPercent(v[1]));
+                has_ratio = obj.map(v => Array.isArray(v[1]) && v[1].map(w => isRatio(w)));
+                if (has_ratio.some(v => Array.isArray(v) && v.every(c => c))) {
+                    throw dualRatioError; // invalid case where both dims are ratios
+                }
+            }
+        }
+        else if (obj.some(isComputed)) { // 2D size
+            has_pct = [obj.map(isPercent)];
+            has_ratio = [obj.map(isRatio)];
+            if ((has_ratio[0] as boolean[]).every(c => c)) {
+                throw dualRatioError; // invalid case where both dims are ratios
+            }
+        }
+    }
+    else if (isRatio(obj)) {
+        throw 'this value only allowed as half of an array, eg [16px, auto]:';
+        // TODO: add this error check for zoom stop parsing above
+    }
+
+    if (has_pct || has_ratio) {
+        // texture is required when % or ratio sizes are used
+        if (!texture) {
+            throw '% or \'auto\' keywords can only be used to specify point size when a texture is defined';
+        }
+
+        // per-sprite based evaluation
+        obj = { value: obj };
+        (obj as PointSizeCache).has_pct = has_pct;
+        (obj as PointSizeCache).has_ratio = has_ratio;
+        (obj as PointSizeCache).sprites = {}; // cache by sprite
+    }
+    else {
+        // no % or aspect ratio sizing, one cache for texture or all sprites
+        obj = StyleParser.createPropertyCache(obj, parsePositiveNumber);
+    }
+
+    return obj as PointSizeCache | undefined;
+};
+
+StyleParser.evalCachedPointSizeProperty = function (val, sprite_info, texture_info, context) {
+    if (val == null) {
+        return;
+    }
+
+    // no percentage-based calculation, one cache for all sprites
+    if (!val.has_pct && !val.has_ratio) {
+        return StyleParser.evalCachedProperty(val, context);
+    }
+
+    if (sprite_info) {
+        // per-sprite based evaluation, cache sizes per sprite
+        if (!val.sprites![sprite_info.sprite!]) {
+            val.sprites![sprite_info.sprite!] = createPointSizeCacheEntry(val, sprite_info);
+        }
+        return StyleParser.evalCachedProperty(val.sprites![sprite_info.sprite!], context);
+    }
+    else {
+        // texture-based evaluation
+        // apply percentage or ratio sizing to a texture
+        val.texture = val.texture || createPointSizeCacheEntry(val, texture_info!);
+        return StyleParser.evalCachedProperty(val.texture, context);
+    }
+};
+
+function createPointSizeCacheEntry (val: PointSizeCache, image_info: PointSizeImage): PropertyCache | undefined {
+    // the cache property transform function needs access to the image in `val`
+    // so it's accessed via a closure here
+    return StyleParser.createPropertyCache(val.value, (v, i) => {
+        if (Array.isArray(v)) { // 2D size
+            // either width or height or both could be a %
+            v = v.
+                map((c, j) => (val.has_ratio![i] as boolean[])[j] ? c : parsePositiveNumber(c)). // convert non-ratio values to px
+                map((c, j) => (val.has_pct![i] as boolean[])[j] ? image_info.css_size[j] * (c as number) / 100 : c); // apply % scaling as needed
+
+            // either width or height could be a ratio
+            if ((val.has_ratio![i] as boolean[])[0]) {
+                (v as number[])[0] = (v as number[])[1] * image_info.aspect;
+            }
+            else if ((val.has_ratio![i] as boolean[])[1]) {
+                (v as number[])[1] = (v as number[])[0] / image_info.aspect;
+            }
+        }
+        else { // 1D size
+            v = parsePositiveNumber(v);
+            if (val.has_pct![i]) {
+                v = image_info.css_size.map(c => c * (v as number) / 100); // set size as % of image
+            }
+            else {
+                v = [v, v]; // expand 1D size to 2D
+            }
+        }
+        return v;
+    });
+}
+
+// Interpolation and caching for a generic property (not a color or distance)
+// { value: original, static: val, zoom: { 1: val1, 2: val2, ... }, dynamic: function(){...} }
+StyleParser.evalCachedProperty = function(val, context) {
+    if (val == null) {
+        return;
+    }
+    else if (val.dynamic) { // function, compute each time (no caching)
+        return tryEval(val.dynamic, context);
+    }
+    else if (val.static) { // single static value
+        return val.static;
+    }
+    else if (val.zoom && val.zoom[context.zoom!]) { // interpolated, cached
+        return val.zoom[context.zoom!];
+    }
+    else { // not yet evaulated for cache
+        // Dynamic function-based
+        if (typeof val.value === 'function') {
+            if (val.dynamic_transform) {
+                // apply an optional post-eval transform function
+                // e.g. apply device pixel ratio to font sizes, unit conversions, etc.
+                val.dynamic = function(context) {
+                    return val.dynamic_transform!((val.value as PropertyFunction)(context));
+                };
+            }
+            else {
+                val.dynamic = val.value as PropertyFunction;
+            }
+            return tryEval(val.dynamic, context);
+        }
+        // Array of zoom-interpolated stops, e.g. [zoom, value] pairs
+        else if (Array.isArray(val.value) && Array.isArray(val.value[0])) {
+            // Calculate value for current zoom
+            val.zoom = val.zoom || {};
+            val.zoom[context.zoom!] = Utils.interpolate(context.zoom!, val.value);
+            return val.zoom[context.zoom!];
+        }
+        // Single static value
+        else {
+            val.static = val.value;
+            return val.static;
+        }
+    }
+};
+
+StyleParser.convertUnits = function(val, context) {
+    // pre-parsed units
+    if ((val as UnitValue).value != null) {
+        if ((val as UnitValue).units === 'px') { // convert from pixels
+            return ((val as UnitValue).value as number) * Geo.metersPerPixel(context.zoom!);
+        }
+        return (val as UnitValue).value;
+    }
+    // un-parsed unit string
+    else if (typeof val === 'string') {
+        if (val.trim().slice(-2) === 'px') {
+            val = parseNumber(val);
+            (val as number) *= Geo.metersPerPixel(context.zoom!); // convert from pixels
+        }
+        else {
+            val = parseNumber(val);
+        }
+    }
+    // multiple values or stops
+    else if (Array.isArray(val)) {
+        // Array of arrays, e.g. zoom-interpolated stops
+        if (Array.isArray(val[0])) {
+            return val.map(v => [v[0], StyleParser.convertUnits(v[1], context)]);
+        }
+        // Array of values
+        else {
+            return val.map(v => StyleParser.convertUnits(v, context));
+        }
+    }
+    return val;
+};
+
+// Pre-parse units from string values
+StyleParser.parseUnits = function (value) {
+    var obj: UnitValue = { value: parseNumber(value) };
+    if (obj.value !== 0 && typeof value === 'string' && value.trim().slice(-2) === 'px') {
+        obj.units = 'px';
+    }
+    return obj;
+};
+
+/** Keep invalid projected heights visible to validation, including wrapped scene functions. */
+StyleParser.createProjectedHeightPropertyCache = function (value) {
+    if (typeof value === 'function' && 'source' in value && typeof value.source === 'string') {
+        // Recompile from the authored body, not the legacy NaN-to-null wrapper.
+        // Leave the shared compiled function untouched for other style properties.
+        value = compileFunctionString(`function(context) {${value.source}}`,
+            source => StyleParser.wrapFunction(source, true));
+    }
+    return StyleParser.createPropertyCache(value, height => {
+        const parsedHeight = typeof height === 'string' ? parseFloat(height) : height;
+        if (typeof parsedHeight !== 'number' || !Number.isFinite(parsedHeight)) {
+            throw new Error('Projected annotation height must be a finite number');
+        }
+        return StyleParser.parseUnits(height);
+    });
+};
+
+/** Dynamic projected heights must reach packing validation without legacy error fallback. */
+StyleParser.evalProjectedHeightProperty = function (value, context) {
+    return typeof value?.value === 'function' ? value.value(context) :
+        StyleParser.evalCachedDistanceProperty(value, context);
+};
+
+// Takes a distance cache object and returns a distance value for this zoom
+// (caching the result for future use)
+// { value: original, zoom: { z: meters }, dynamic: function(){...} }
+StyleParser.evalCachedDistanceProperty = function(val, context) {
+    if (val == null) {
+        return;
+    }
+    else if (val.dynamic) {
+        return tryEval(val.dynamic, context);
+    }
+    else if (val.zoom && val.zoom[context.zoom!]) {
+        return val.zoom[context.zoom!];
+    }
+    else {
+        // Dynamic function-based
+        if (typeof val.value === 'function') {
+            val.dynamic = val.value as PropertyFunction;
+            return tryEval(val.dynamic, context);
+        }
+        // Array of zoom-interpolated stops, e.g. [zoom, value] pairs
+        else if (val.zoom) {
+            // Calculate value for current zoom
+            // Do final unit conversion as late as possible, when interpolation values have been determined
+            val.zoom[context.zoom!] = Utils.interpolate(context.zoom!, val.value as PropertyStop[],
+                v => StyleParser.convertUnits(v, context) as number);
+
+            return val.zoom[context.zoom!];
+        }
+        else {
+            return StyleParser.convertUnits(val.value, context);
+        }
+    }
+};
+
+// Cache previously parsed color strings
+StyleParser.string_colors = {};
+StyleParser.colorForString = function(string) {
+    // Cached
+    if (StyleParser.string_colors[string]) {
+        return StyleParser.string_colors[string];
+    }
+
+    // Calculate and cache
+    let color: number[] | undefined = parseCSSColor.parseCSSColor(string);
+    if (color && color.length === 4) {
+        color[0] /= 255;
+        color[1] /= 255;
+        color[2] /= 255;
+    }
+    else {
+        color = StyleParser.defaults.color;
+    }
+    StyleParser.string_colors[string] = color;
+    return color;
+};
+
+// Takes a color cache object and returns a color value for this zoom
+// (caching the result for future use)
+// { value: original, static: [r,g,b,a], zoom: { z: [r,g,b,a] }, dynamic: function(){...} }
+StyleParser.evalCachedColorProperty = function(val, context = {}) {
+    if (val == null) {
+        return;
+    }
+    else if (val.dynamic) {
+        let v = tryEval(val.dynamic, context) as number[] | string | undefined;
+
+        if (typeof v === 'string') {
+            v = StyleParser.colorForString(v);
+        }
+
+        if (v && v[3] == null) {
+            v[3] = 1; // default alpha
+        }
+        return v;
+    }
+    else if (val.static) {
+        return val.static as number[];
+    }
+    else if (val.zoom && val.zoom[context.zoom!]) {
+        return val.zoom[context.zoom!] as number[];
+    }
+    else {
+        // Dynamic function-based color
+        if (typeof val.value === 'function') {
+            val.dynamic = val.value as PropertyFunction;
+            let v = tryEval(val.dynamic, context) as number[] | string | undefined;
+
+            if (typeof v === 'string') {
+                v = StyleParser.colorForString(v);
+            }
+
+            if (v && v[3] == null) {
+                v[3] = 1; // default alpha
+            }
+            return v;
+        }
+        // Single string color
+        else if (typeof val.value === 'string') {
+            val.static = StyleParser.colorForString(val.value);
+            return val.static as number[];
+        }
+        // Array of zoom-interpolated stops, e.g. [zoom, color] pairs
+        else if (val.zoom) {
+            // Parse any string colors inside stops, the first time we encounter this property
+            if (!val.zoom_preprocessed) {
+                for (let i=0; i < (val.value as PropertyStop[]).length; i++) {
+                    let v = (val.value as PropertyStop[])[i];
+                    if (v && typeof v[1] === 'string') {
+                        v[1] = StyleParser.colorForString(v[1]);
+                    }
+                }
+                val.zoom_preprocessed = true;
+            }
+
+            // Calculate color for current zoom
+            val.zoom[context.zoom!] = Utils.interpolate(context.zoom!, val.value as PropertyStop[]);
+            (val.zoom[context.zoom!] as number[])[3] = (val.zoom[context.zoom!] as number[])[3] || 1; // default alpha
+            return val.zoom[context.zoom!] as number[];
+        }
+        // Single array color
+        else {
+            val.static = (val.value as number[]).map(x => x); // copy to avoid modifying
+            if (val.static && (val.static as number[])[3] == null) {
+                (val.static as number[])[3] = 1; // default alpha
+            }
+            return val.static as number[];
+        }
+    }
+};
+
+// Evaluate color cache object and apply optional alpha override (alpha arg is a single value cache object)
+StyleParser.evalCachedColorPropertyWithAlpha = function (val, alpha_prop, context) {
+    const color = StyleParser.evalCachedColorProperty(val, context);
+    if (color != null && alpha_prop != null) {
+        const alpha = StyleParser.evalCachedProperty(alpha_prop, context);
+        if (alpha != null) {
+            return [color[0], color[1], color[2], alpha];
+        }
+    }
+    return color;
+};
+
+StyleParser.parseColor = function(val, context = {}) {
+    if (typeof val === 'function') {
+        val = tryEval(val as PropertyFunction, context);
+    }
+
+    // Parse CSS-style colors
+    // TODO: change all colors to use 0-255 range internally to avoid dividing and then re-multiplying in geom builder
+    if (typeof val === 'string') {
+        val = StyleParser.colorForString(val);
+    }
+    else if (Array.isArray(val) && Array.isArray(val[0])) {
+        // Array of zoom-interpolated stops, e.g. [zoom, color] pairs
+        for (let i=0; i < val.length; i++) {
+            let v = val[i];
+            if (typeof v[1] === 'string') {
+                v[1] = StyleParser.colorForString(v[1]);
+            }
+        }
+
+        if (context.zoom) {
+            val = Utils.interpolate(context.zoom, val);
+        }
+    }
+
+    // Defaults
+    if (Array.isArray(val)) {
+        val = val.map(x => x); // copy to avoid modifying
+        // alpha
+        if ((val as number[])[3] == null) {
+            (val as number[])[3] = 1;
+        }
+    }
+    else {
+        val = [0, 0, 0, 1];
+    }
+
+    return val as number[];
+};
+
+StyleParser.calculateOrder = function(order, context) {
+    // Computed order
+    if (typeof order === 'function') {
+        order = tryEval(order as PropertyFunction, context);
+    }
+    else if (typeof order === 'string') {
+        // Order tied to feature property
+        if (context.feature!.properties[order]) {
+            order = context.feature!.properties[order];
+        }
+        // Explicit order value
+        else {
+            order = parsePositiveNumber(order);
+        }
+    }
+
+    return order;
+};
+
+// Evaluate a function-based property, or pass-through static value
+StyleParser.evalProperty = function(prop, context) {
+    if (typeof prop === 'function') {
+        return tryEval(prop as PropertyFunction, context);
+    }
+    return prop;
+};
+
+// eval property function with try/catch
+function tryEval (func: PropertyFunction, context: PropertyContext): unknown {
+    try {
+        return func(context);
+    } catch(e) {
+        log('warn',
+            `Property function in layer '${context.layers![context.layers!.length-1]}' failed with\n`,
+            `error ${(e as Error).stack}\n`,
+            `function '${func.source}'\n`,
+            context.feature, context);
+    }
+}