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

package/src/scene/camera_base.ts

@@ -0,0 +1,116 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import {Matrix3, Matrix4} from '@math.gl/core';
+import type {HostProjection} from '../types';
+
+export type Matrix = Float32Array | Float64Array;
+export type Vector = number[] | Float32Array | Float64Array;
+export type CameraType = 'external' | 'isometric' | 'flat' | 'perspective';
+export type CameraConfiguration = {
+    type?: CameraType;
+    position?: number[];
+    zoom?: number;
+    focal_length?: number | number[][];
+    fov?: number | number[][];
+    vanishing_point?: number[];
+    axis?: {x: number; y: number} | number[];
+};
+export type CameraView = {
+    /** Host geographic projection; omitted by classic planar cameras. */
+    projection?: HostProjection;
+    setView(view: {lng?: number; lat?: number; zoom?: number}): void;
+    scene: {requestRedraw(): void};
+    size: {
+        css: {width: number; height: number};
+        meters: {x: number; y: number};
+    };
+    aspect: number;
+    meters_per_pixel: number;
+    zoom: number;
+    center: {meters: {x: number; y: number}};
+};
+export type Program = {uniform(type: string, name: string, value: Vector | Matrix): void};
+export type UniformBuffer = {setUniforms(uniforms: Record<string, Vector | Matrix | number | boolean>): void};
+export type MatrixSet = {
+    model_view32: Matrix;
+    model: Matrix;
+    normal32: Matrix;
+    inverse_normal32: Matrix;
+};
+
+// Abstract base class
+export default class Camera {
+    readonly view: CameraView;
+    readonly position?: number[];
+    readonly zoom?: number;
+    private readonly matrix3 = new Matrix3();
+    protected readonly matrix4 = new Matrix4();
+    type?: CameraType;
+    view_matrix: Matrix = new Float64Array(16);
+    projection_matrix: Matrix = new Float32Array(16);
+    position_meters: Vector = [0, 0, 0];
+
+    constructor(name: string, view: CameraView, options: CameraConfiguration = {}) {
+        this.view = view;
+        this.position = options.position;
+        this.zoom = options.zoom;
+    }
+
+    // Update method called once per frame
+    update(): void {
+    }
+
+    // Called once per frame per program (e.g. for main render pass, then for each additional pass for feature selection, etc.)
+    setupProgram(/*program*/ _program?: Program, _uniformBuffer?: UniformBuffer): void {
+    }
+
+    // Sync camera position/zoom to scene view
+    updateView (): void {
+        if (this.position || this.zoom) {
+            let view: {lng?: number; lat?: number; zoom?: number} = {};
+            if (this.position) {
+                view = { lng: this.position[0], lat: this.position[1], zoom: this.position[2] };
+            }
+            if (this.zoom) {
+                view.zoom = this.zoom;
+            }
+            this.view.setView(view);
+        }
+    }
+
+    // Set model-view and normal matrices
+    setupMatrices (matrices: MatrixSet, program: Program, uniform_buffer?: UniformBuffer): void {
+        // Model view matrix - transform tile space into view space (meters, relative to camera)
+        this.matrix4.copy(this.view_matrix).multiplyRight(matrices.model).toArray(matrices.model_view32);
+
+        // Normal matrices - transforms surface normals into view space
+        const normal_matrix = this.matrix3.set(
+            matrices.model_view32[0], matrices.model_view32[1], matrices.model_view32[2],
+            matrices.model_view32[4], matrices.model_view32[5], matrices.model_view32[6],
+            matrices.model_view32[8], matrices.model_view32[9], matrices.model_view32[10]
+        );
+        if (normal_matrix.determinant() !== 0) {
+            normal_matrix.invert().transpose().toArray(matrices.normal32);
+            normal_matrix.copy(matrices.normal32);
+            if (normal_matrix.determinant() !== 0) {
+                normal_matrix.invert().toArray(matrices.inverse_normal32);
+            }
+        }
+        if (uniform_buffer) {
+            uniform_buffer.setUniforms({
+                u_modelView: matrices.model_view32,
+                u_normalMatrix: matrices.normal32,
+                u_inverseNormalMatrix: matrices.inverse_normal32
+            });
+        }
+        else {
+            program.uniform('Matrix4fv', 'u_modelView', matrices.model_view32);
+            program.uniform('Matrix3fv', 'u_normalMatrix', matrices.normal32);
+            program.uniform('Matrix3fv', 'u_inverseNormalMatrix', matrices.inverse_normal32);
+        }
+    }
+
+}

package/src/scene/classic_scene.ts

@@ -0,0 +1,20 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import CoreScene from './scene';
+import Camera from './camera';
+import type {RendererOptions, SceneDefinition} from '../types';
+
+/** Standalone Scene with classic camera construction; host renderers use CoreScene. */
+export default class Scene extends CoreScene {
+    /** Constructs a standalone scene without changing explicitly external camera mode. */
+    constructor(config: SceneDefinition, options: RendererOptions = {}) {
+        super(config, {...options, cameraFactory: Camera.create});
+    }
+
+    /** Creates a scene with Tangram's perspective, isometric, and flat cameras. */
+    static create(config: SceneDefinition, options: RendererOptions = {}): Scene {
+        return new Scene(config, options);
+    }
+}

package/src/scene/external_camera.ts

@@ -0,0 +1,101 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import ShaderProgram from '../gl/shader_program';
+import Camera, {type CameraView, type CameraConfiguration, type Matrix, type Vector, type Program, type UniformBuffer} from './camera_base';
+import type {Matrix4 as HostMatrix} from '../types';
+
+/**
+    Camera whose view and projection matrices are supplied by an embedding renderer.
+
+    This lets hosts such as deck.gl remain authoritative for camera projection while
+    Tangram continues to manage scene loading, tile selection, and drawing.
+*/
+export default class ExternalCamera extends Camera {
+    readonly vanishing_point: number[];
+
+    constructor(name: string, view: CameraView, options: CameraConfiguration = {}) {
+        super(name, view, options);
+        this.type = 'external';
+        this.position_meters = [0, 0, 0];
+        this.vanishing_point = [0, 0];
+        this.view_matrix = new Float64Array(16);
+        this.projection_matrix = new Float32Array(16);
+        this.matrix4.identity().toArray(this.view_matrix);
+        this.matrix4.identity().toArray(this.projection_matrix);
+
+        ShaderProgram.replaceBlock('camera', `
+            uniform mat4 u_projection;
+            uniform vec3 u_eye;
+            uniform vec2 u_vanishing_point;
+
+            void cameraProjection (inout vec4 position) {
+                position = u_projection * position;
+            }`
+        );
+    }
+
+    setMatrices({view, projection, position = [0, 0, 0]}: {view: HostMatrix; projection: HostMatrix; position?: ArrayLike<number>}): boolean {
+        if (!view || view.length !== 16 || !projection || projection.length !== 16) {
+            throw new Error('ExternalCamera requires 4x4 view and projection matrices');
+        }
+        const changed = !matrixEquals(this.view_matrix, view) ||
+            !matrixEquals(this.projection_matrix, projection) ||
+            !vectorEquals(this.position_meters, position);
+        if (!changed) {
+            return false;
+        }
+        this.view_matrix.set(view);
+        this.projection_matrix.set(projection);
+        this.position_meters = Array.from(position);
+        this.view.scene.requestRedraw();
+        return true;
+    }
+
+    setupProgram(program: Program, uniform_buffer?: UniformBuffer): void {
+        if (uniform_buffer) {
+            uniform_buffer.setUniforms({
+                u_projection: this.projection_matrix,
+                u_eye: this.position_meters,
+                u_vanishing_point: this.vanishing_point
+            });
+        }
+        else {
+            program.uniform('Matrix4fv', 'u_projection', this.projection_matrix);
+            program.uniform('3fv', 'u_eye', this.position_meters);
+            program.uniform('2fv', 'u_vanishing_point', this.vanishing_point);
+        }
+    }
+
+    /** Keep globe directional lights in common space; planar lights remain view-relative. */
+    transformVector(vector: Vector): number[] {
+        if (this.view.projection?.type === 'globe') {
+            const length = Math.hypot(...vector);
+            return length === 0 ? Array.from(vector) : Array.from(vector, value => value / length);
+        }
+        const matrix = this.view_matrix;
+        const transformed = [
+            matrix[0] * vector[0] + matrix[4] * vector[1] + matrix[8] * vector[2],
+            matrix[1] * vector[0] + matrix[5] * vector[1] + matrix[9] * vector[2],
+            matrix[2] * vector[0] + matrix[6] * vector[1] + matrix[10] * vector[2]
+        ];
+        const length = Math.hypot(...transformed);
+        return length === 0 ? transformed : transformed.map(value => value / length);
+    }
+
+}
+
+function matrixEquals(left: Matrix, right: ArrayLike<number>): boolean {
+    for (let index = 0; index < 16; index++) {
+        if (left[index] !== right[index]) {
+            return false;
+        }
+    }
+    return true;
+}
+
+function vectorEquals(left: Vector, right: ArrayLike<number>): boolean {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/src/scene/globals.ts

@@ -0,0 +1,120 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import log from '../utils/log';
+import { getPropertyPathTarget } from '../utils/props';
+
+// prefix used to identify global property references
+const GLOBAL_PREFIX = 'global.';
+const GLOBAL_PREFIX_LENGTH = GLOBAL_PREFIX.length;
+
+// name of 'hidden' (non-enumerable) property used to track global property references on an object
+const GLOBAL_REGISTRY = '__global_prop';
+
+/** Authored globals may contain scalars, functions, arrays, or opaque application values. */
+type GlobalObject = Record<string, unknown>;
+/** Non-enumerable provenance attached to objects/arrays after substitution. */
+type GlobalTarget = Record<PropertyKey, unknown> & {
+    [GLOBAL_REGISTRY]?: Record<PropertyKey, string>;
+};
+
+// Property name references a global property?
+/** Identify URL/global-reference strings while retaining omitted resource values. */
+export function isGlobalReference (val: string | null | undefined): boolean {
+    return val?.slice(0, GLOBAL_PREFIX_LENGTH) === GLOBAL_PREFIX;
+}
+
+// Has object property been substitued with a value from a global reference?
+// Property provided as a single-depth string name, or nested path array (`a.b.c` => ['a', 'b', 'c'])
+/** Inspect substitution provenance for a named property or nested object/array path. */
+export function isGlobalSubstitution (object: object, prop_or_path: string | (string | number)[]): boolean {
+    const path = Array.isArray(prop_or_path) ? prop_or_path : [prop_or_path];
+    const target = getPropertyPathTarget(object, path) as GlobalTarget | undefined;
+    const prop = path[path.length - 1];
+    return target?.[GLOBAL_REGISTRY]?.[prop] !== undefined;
+}
+
+// Flatten nested global properties for simpler string look-ups
+/** Flatten global records without discarding their original nested values. */
+export function flattenGlobalProperties (obj: GlobalObject, prefix: string | null = null, globals: GlobalObject = {}): GlobalObject {
+    prefix = prefix ? (prefix + '.') : GLOBAL_PREFIX;
+
+    for (const p in obj) {
+        const key = prefix + p;
+        const val = obj[p];
+        globals[key] = val;
+
+        if (typeof val === 'object' && !Array.isArray(val)) {
+            flattenGlobalProperties(val as GlobalObject, key, globals);
+        }
+    }
+    return globals;
+}
+
+// Find and apply new global properties (and re-apply old ones)
+/** Reapply globals using hidden provenance, retaining the input object's identity and type. */
+export function applyGlobalProperties<Value>(globals: GlobalObject, obj: Value, target?: object, key?: string | number): Value {
+    let prop: string | undefined;
+    const targetRecord = target as GlobalTarget | undefined;
+
+    // Check for previously applied global substitution
+    if (targetRecord?.[GLOBAL_REGISTRY]?.[key!]) {
+        prop = targetRecord[GLOBAL_REGISTRY][key!];
+    }
+    // Check string for new global substitution
+    else if (typeof obj === 'string' && obj.slice(0, GLOBAL_PREFIX_LENGTH) === GLOBAL_PREFIX) {
+        prop = obj;
+    }
+
+    // Found global property to substitute
+    if (prop) {
+        // Mark property as global substitution
+        if (targetRecord![GLOBAL_REGISTRY] == null) {
+            Object.defineProperty(targetRecord!, GLOBAL_REGISTRY, { value: {} });
+        }
+        targetRecord![GLOBAL_REGISTRY]![key!] = prop;
+
+        // Get current global value
+        let val = globals[prop];
+        let stack: string[] | undefined;
+        while (typeof val === 'string' && val.slice(0, GLOBAL_PREFIX_LENGTH) === GLOBAL_PREFIX) {
+            // handle globals that refer to other globals, detecting any cyclical references
+            stack = stack || [prop];
+            if (stack.indexOf(val) > -1) {
+                log({ level: 'warn', once: true }, 'Global properties: cyclical reference detected', stack);
+                val = null;
+                break;
+            }
+            stack.push(val);
+            val = globals[val];
+        }
+
+        // Create getter/setter
+        Object.defineProperty(targetRecord!, key!, {
+            enumerable: true,
+            get: function () {
+                return val; // return substituted value
+            },
+            set: function (v: unknown) {
+                // clear the global substitution and remove the getter/setter
+                delete targetRecord![GLOBAL_REGISTRY]![key!];
+                delete targetRecord![key!];
+                targetRecord![key!] = v; // save the new value
+            }
+        });
+    }
+    // Loop through object keys or array indices
+    else if (Array.isArray(obj)) {
+        for (let p = 0; p < obj.length; p++) {
+            applyGlobalProperties(globals, obj[p], obj, p);
+        }
+    }
+    else if (typeof obj === 'object') {
+        for (const p in obj) {
+            applyGlobalProperties(globals, obj[p], obj as object, p);
+        }
+    }
+    return obj;
+}

package/src/scene/ground_footprint.ts

@@ -0,0 +1,139 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+import {Matrix4} from '@math.gl/core';
+import type {HostCamera} from '../types';
+import type {Bounds} from '../utils/geo';
+
+type Point = [number, number];
+
+/**
+ * Intersects all twelve edges of a finite host frustum with EPSG:3857 ground.
+ * Optional meter-space limits clip the resulting convex polygon before bounds
+ * are calculated. Null means no ground area, not an unknown footprint.
+ * Matrices use column-major OpenGL clip coordinates, also on the WebGPU path.
+ */
+export function calculatePlanarGroundBounds(camera: HostCamera, limits?: Bounds): Bounds | null {
+    return calculatePlanarVolumeBounds(camera, [0, 0], limits);
+}
+
+/**
+ * Bounds the finite frustum intersected with a closed elevation slab. Heights
+ * are physical meters; XY uses EPSG:3857 meters. This conservative candidate
+ * footprint includes elevated-only geometry, not terrain surface intersections.
+ * Optional horizontal limits clip the convex footprint, not its bounding box.
+ */
+export function calculatePlanarVolumeBounds(camera: HostCamera,
+    elevationRange: readonly [number, number], limits?: Bounds): Bounds | null {
+    const [minimumElevation, maximumElevation] = elevationRange;
+    if (elevationRange.length !== 2 || !Number.isFinite(minimumElevation) ||
+        !Number.isFinite(maximumElevation) || minimumElevation > maximumElevation) {
+        throw new Error('Elevation range requires two finite ordered heights');
+    }
+    if (camera.view.length !== 16 || camera.projection.length !== 16 ||
+        !Array.from(camera.view).every(Number.isFinite) || !Array.from(camera.projection).every(Number.isFinite)) {
+        throw new Error('Ground footprint requires finite camera matrices');
+    }
+    if (limits && (![limits.sw.x, limits.sw.y, limits.ne.x, limits.ne.y].every(Number.isFinite) ||
+        limits.sw.x > limits.ne.x || limits.sw.y > limits.ne.y)) {
+        throw new Error('Ground footprint limits must be finite ordered bounds');
+    }
+    const inverse = new Matrix4().copy(camera.projection).multiplyRight(camera.view);
+    if (!Number.isFinite(inverse.determinant()) || inverse.determinant() === 0) {
+        throw new Error('Ground footprint camera is singular');
+    }
+    inverse.invert();
+    const corners: number[][] = [];
+    for (const depth of [-1, 1]) {
+        for (const vertical of [-1, 1]) {
+            for (const horizontal of [-1, 1]) {
+                const homogeneous = inverse.transform([horizontal, vertical, depth, 1]);
+                const point = Array.from(homogeneous).slice(0, 3).map(value => value / homogeneous[3]);
+                if (!point.every(Number.isFinite) || homogeneous[3] <= 0) {
+                    throw new Error('Ground footprint requires a finite near and far frustum');
+                }
+                corners.push(point);
+            }
+        }
+    }
+    const points: Point[] = corners.filter(point => point[2] >= minimumElevation &&
+        point[2] <= maximumElevation).map(point => [point[0], point[1]]);
+    for (let index = 0; index < corners.length; index++) {
+        for (const bit of [1, 2, 4]) {
+            const adjacent = index ^ bit;
+            if (adjacent < index) continue;
+            const start = corners[index];
+            const end = corners[adjacent];
+            for (const elevation of [minimumElevation, maximumElevation]) {
+                if (start[2] === elevation) points.push([start[0], start[1]]);
+                if (end[2] === elevation) points.push([end[0], end[1]]);
+                if ((start[2] < elevation && end[2] > elevation) ||
+                    (start[2] > elevation && end[2] < elevation)) {
+                    const parameter = (elevation - start[2]) / (end[2] - start[2]);
+                    points.push([start[0] + parameter * (end[0] - start[0]),
+                        start[1] + parameter * (end[1] - start[1])]);
+                }
+            }
+        }
+    }
+    let polygon = convexHull(points);
+    if (polygon.length < 3) return null;
+    if (limits) {
+        polygon = clipPolygon(polygon, 0, limits.sw.x, true);
+        polygon = clipPolygon(polygon, 0, limits.ne.x, false);
+        polygon = clipPolygon(polygon, 1, limits.sw.y, true);
+        polygon = clipPolygon(polygon, 1, limits.ne.y, false);
+    }
+    if (polygon.length < 3) return null;
+    // Use a local origin to avoid cancellation for meter coordinates near the antimeridian.
+    const origin = polygon[0];
+    const twiceArea = polygon.reduce((area, point, index) => {
+        const next = polygon[(index + 1) % polygon.length];
+        return area + (point[0] - origin[0]) * (next[1] - origin[1]) -
+            (point[1] - origin[1]) * (next[0] - origin[0]);
+    }, 0);
+    if (twiceArea === 0) return null;
+    const bounds = {
+        sw: {x: Math.min(...polygon.map(point => point[0])), y: Math.min(...polygon.map(point => point[1]))},
+        ne: {x: Math.max(...polygon.map(point => point[0])), y: Math.max(...polygon.map(point => point[1]))}
+    };
+    return bounds.ne.x > bounds.sw.x && bounds.ne.y > bounds.sw.y ? bounds : null;
+}
+
+/** Monotone-chain hull removes duplicate/interior projected frustum corners. */
+function convexHull(points: Point[]): Point[] {
+    const sorted = points.sort((left, right) => left[0] - right[0] || left[1] - right[1])
+        .filter((point, index, list) => index === 0 || point[0] !== list[index - 1][0] || point[1] !== list[index - 1][1]);
+    const cross = (origin: Point, first: Point, second: Point): number =>
+        (first[0] - origin[0]) * (second[1] - origin[1]) - (first[1] - origin[1]) * (second[0] - origin[0]);
+    const half = (list: Point[]): Point[] => {
+        const hull: Point[] = [];
+        for (const point of list) {
+            while (hull.length >= 2 && cross(hull[hull.length - 2], hull[hull.length - 1], point) <= 0) hull.pop();
+            hull.push(point);
+        }
+        return hull;
+    };
+    const lower = half(sorted), upper = half([...sorted].reverse());
+    return [...lower.slice(0, -1), ...upper.slice(0, -1)];
+}
+
+/** Clips a convex ground polygon against one axis-aligned half-plane. */
+function clipPolygon(polygon: Point[], axis: 0 | 1, boundary: number, keepGreater: boolean): Point[] {
+    const result: Point[] = [];
+    const inside = (point: Point) => keepGreater ? point[axis] >= boundary : point[axis] <= boundary;
+    for (let index = 0; index < polygon.length; index++) {
+        const start = polygon[index];
+        const end = polygon[(index + 1) % polygon.length];
+        if (inside(start)) result.push(start);
+        if (inside(start) !== inside(end)) {
+            const parameter = (boundary - start[axis]) / (end[axis] - start[axis]);
+            const point: Point = [start[0] + parameter * (end[0] - start[0]),
+                start[1] + parameter * (end[1] - start[1])];
+            point[axis] = boundary;
+            result.push(point);
+        }
+    }
+    return result;
+}