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

package/package.json

@@ -1,6 +1,106 @@
 {
   "name": "@tangram.gl/tangram-renderer",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.0.1",
+  "description": "Tangram vector-tile scene renderer powered by luma.gl",
+  "homepage": "https://vis.gl/tangram.gl/",
+  "type": "module",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./dist/*": "./dist/*",
+    "./core": {
+      "types": "./dist/types/core.d.ts",
+      "import": "./dist/core.js",
+      "default": "./dist/core.js"
+    },
+    "./style-schema": {
+      "import": "./dist/style-schema.js"
+    },
+    "./map-logic": {
+      "types": "./dist/types/map-logic/index.d.ts",
+      "import": "./dist/map-logic.js",
+      "default": "./dist/map-logic.js"
+    },
+    "./experimental/shader-modules": {
+      "types": "./dist/types/shader-modules/index.d.ts",
+      "import": "./dist/shader-modules.js",
+      "default": "./dist/shader-modules.js"
+    },
+    "./tangram-style.schema.json": "./dist/tangram-style.schema.json"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": true,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/visgl/tangram.gl.git",
+    "directory": "modules/tangram-renderer"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "yarn build:types && node scripts/build.mjs && yarn build:entry && yarn build:map-logic && yarn build:shader-modules && yarn build:style-schema && yarn generate-style-schema && yarn build:loaders-gl-worker && yarn build:projection-worker && yarn build:size",
+    "build:types": "node ../../scripts/build-package-types.mjs modules/tangram-renderer index.d.ts core.d.ts types.ts map-logic/index.ts shader-modules/index.ts",
+    "build:shader-modules": "yarn --cwd ../.. ocular-bundle modules/tangram-renderer/src/shader-modules/index.ts --format=esm --output=modules/tangram-renderer/dist/shader-modules.js --externals=@tangram.gl/tangram-layers --sourcemap=true --sourcesContent=false",
+    "build:map-logic": "yarn --cwd ../.. ocular-bundle modules/tangram-renderer/src/map-logic/index.ts --format=esm --output=modules/tangram-renderer/dist/map-logic.js --externals=@tangram.gl/tangram-layers --sourcemap=true --sourcesContent=false",
+    "build:projection-worker": "yarn --cwd ../.. ocular-bundle modules/tangram-renderer/src/experimental/projected-basemaps-worker.ts --format=iife --globalName=TangramProjectedBasemaps --output=modules/tangram-renderer/dist/projected-basemaps-worker.js --externals=@tangram.gl/tangram-layers --sourcemap=true --sourcesContent=false",
+    "build:entry": "node scripts/write-package-entry.mjs",
+    "build:style-schema": "yarn --cwd ../.. ocular-bundle modules/tangram-renderer/src/styles/style-schema.ts --env=dev --format=esm --output=modules/tangram-renderer/dist/style-schema.js --externals=zod --sourcemap=true --sourcesContent=false",
+    "build:loaders-gl-worker": "yarn --cwd ../.. ocular-bundle modules/tangram-renderer/src/experimental/loaders-gl-worker.ts --format=iife --globalName=TangramLoadersGL --output=modules/tangram-renderer/dist/loaders-gl-worker.js --externals=@tangram.gl/tangram-layers --sourcemap=true --sourcesContent=false",
+    "generate-style-schema": "node scripts/generate-style-schema.mjs",
+    "build:size": "gzip dist/tangram.min.mjs -c | wc -c | awk '{kb=$1/1000; print kb}' OFMT='Renderer ESM:\\t%.0f KB (min/gzip)'",
+    "prepack": "yarn build",
+    "watch": "node scripts/build.mjs --watch",
+    "test-build-worker": "node scripts/build.mjs --test-worker"
+  },
+  "devDependencies": {
+    "@loaders.gl/config": "5.0.0-alpha.11",
+    "@loaders.gl/core": "5.0.0-alpha.11",
+    "@loaders.gl/loader-utils": "5.0.0-alpha.11",
+    "@loaders.gl/mlt": "5.0.0-alpha.11",
+    "@loaders.gl/mvt": "5.0.0-alpha.11",
+    "@loaders.gl/pmtiles": "5.0.0-alpha.11",
+    "@loaders.gl/tiles": "5.0.0-alpha.11",
+    "@math.gl/geospatial": "5.0.0-alpha.18",
+    "@math.gl/projection": "5.0.0-alpha.18",
+    "esbuild": "^0.28.1"
+  },
+  "dependencies": {
+    "@luma.gl/core": "^9.4.2",
+    "@luma.gl/shadertools": "^9.4.2",
+    "@mapbox/vector-tile": "1.3.0",
+    "@math.gl/core": "5.0.0-alpha.18",
+    "@math.gl/culling": "5.0.0-alpha.18",
+    "@math.gl/web-mercator": "5.0.0-alpha.18",
+    "core-js": "^3.39.0",
+    "csscolorparser": "1.0.3",
+    "earcut": "2.2.2",
+    "fontfaceobserver": "2.0.7",
+    "geojson-vt": "3.2.1",
+    "gl-shader-errors": "1.0.3",
+    "js-yaml": "https://github.com/tangrams/js-yaml.git#read-only",
+    "jszip": "^3.10.1",
+    "pbf": "3.1.0",
+    "quickselect": "3.0.0",
+    "topojson-client": "https://github.com/tangrams/topojson-client.git#read-only",
+    "zod": "^4.1.12"
+  },
+  "peerDependencies": {
+    "@math.gl/projection": "5.0.0-alpha.18"
+  },
+  "peerDependenciesMeta": {
+    "@math.gl/projection": {
+      "optional": true
+    }
+  }
 }

package/src/builders/common.ts

@@ -0,0 +1,41 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Geometry building functions
+import Geo from '../utils/geo';
+
+export const tile_bounds = [
+    { x: 0, y: 0},
+    { x: Geo.tile_scale, y: -Geo.tile_scale } // TODO: correct for flipped y-axis?
+];
+
+export const default_uvs = [0, 0, 1, 1];
+
+// Tests if a line segment (from point A to B) is outside the tile bounds
+// (within a certain tolerance to account for geometry nearly on tile edges)
+export function outsideTile (_a: number[], _b: number[], tolerance: number): boolean {
+    let tile_min = tile_bounds[0];
+    let tile_max = tile_bounds[1];
+
+    // TODO: fix flipped Y coords here, confusing with 'max' reference
+    if ((_a[0] <= tile_min.x + tolerance && _b[0] <= tile_min.x + tolerance) ||
+        (_a[0] >= tile_max.x - tolerance && _b[0] >= tile_max.x - tolerance) ||
+        (_a[1] >= tile_min.y - tolerance && _b[1] >= tile_min.y - tolerance) ||
+        (_a[1] <= tile_max.y + tolerance && _b[1] <= tile_max.y + tolerance)) {
+        return true;
+    }
+
+    return false;
+}
+
+export function isCoordOutsideTile (coord: number[], tolerance = 0): boolean {
+    let tile_min = tile_bounds[0];
+    let tile_max = tile_bounds[1];
+
+    return coord[0] <= tile_min.x + tolerance ||
+           coord[0] >= tile_max.x - tolerance ||
+           coord[1] >= tile_min.y - tolerance ||
+           coord[1] <= tile_max.y + tolerance;
+}

package/src/builders/earcut.d.ts

@@ -0,0 +1,15 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+declare module 'earcut' {
+    type EarcutResult = number[];
+
+    interface EarcutFunction {
+        (vertices: number[], holes?: number[], dimensions?: number): EarcutResult;
+        flatten(data: number[][][]): {vertices: number[]; holes: number[]; dimensions: number};
+    }
+
+    const earcut: EarcutFunction;
+    export default earcut;
+}

package/src/builders/geometry-types.ts

@@ -0,0 +1,60 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** Tile-local coordinates; additional height components are retained by builders. */
+export type GeometryCoordinate = number[];
+/** One ordered polyline or closed polygon ring. */
+export type GeometryLine = GeometryCoordinate[];
+/** Polygon rings may carry area metadata assigned during source preprocessing. */
+export type GeometryRing = GeometryLine & {area?: number};
+/** Polygon exterior followed by holes in source winding order. */
+export type GeometryPolygon = GeometryRing[];
+/** Builder sink shared by real packed buffers and deterministic geometry fixtures. */
+export interface GeometryVertexData {
+    vertex_count: number;
+    vertex_elements: {push(index: number): void};
+    addVertex(vertex: number[]): void;
+}
+/** Resolved line geometry parameters, independent of authored property caches. */
+export interface PolylineStyle {
+    width: number;
+    cap?: 'butt' | 'square' | 'round';
+    join?: 'miter' | 'bevel' | 'round';
+    miter_limit?: number;
+    texcoord_width: number;
+    offset: number;
+}
+/** Attribute component indices; portable untextured lines explicitly disable UV writes. */
+export interface PolylineVertexIndices {
+    a_extrude: number;
+    a_offset?: number;
+    a_texcoord?: number | null;
+    /** Optional CPU-projection source normals and authored stroke dimensions. */
+    a_projected_normals?: number;
+    a_projected_widths?: number;
+}
+/** Per-build mutable state; deferred segments retain the same geometry sink. */
+export interface PolylineBuildContext {
+    closed_polygon: boolean | undefined;
+    remove_tile_edges: boolean | undefined;
+    tile_edge_tolerance: number;
+    miter_len_sq: number | undefined;
+    join_type: number;
+    cap_type: number;
+    vertex_data: GeometryVertexData;
+    vertex_template: number[];
+    half_width: number;
+    extrude_index: number;
+    offset_index: number | undefined;
+    v_scale: number | undefined;
+    texcoord_index: number | null | undefined;
+    texcoord_width: number;
+    offset: number;
+    geom_count: number;
+    extra_lines?: GeometryLine[];
+    /** Adjacent source normals retained only by opt-in projected line layouts. */
+    projected_normals_index?: number;
+    projected_widths_index?: number;
+    projected_normals?: number[];
+}

package/src/builders/points.ts

@@ -0,0 +1,115 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+
+// Point builders
+
+import { default_uvs } from './common';
+import type VertexData from '../gl/vertex_data';
+
+type VertexIndex = Record<string, number>;
+
+// Scaling values to encode fractional values with fixed-point integer attributes
+const pre_angles_normalize = 128 / Math.PI;
+const angles_normalize = 16384 / Math.PI;
+const offsets_normalize = 64;
+const texcoord_normalize = 65535;
+const size_normalize = 128; // width/height are 8.8 fixed-point, but are halved (so multiply by 128 instead of 256)
+
+// These index values map a 4-element vertex position counter from this pattern (used for size and UVs):
+//  [min_x, min_y, max_x, max_y]
+// to this pattern:
+//  [min_x, min_y],
+//  [max_x, min_y],
+//  [max_x, max_y],
+//  [min_x, max_y]
+const ix = [0, 2, 2, 0];
+const iy = [1, 1, 3, 3];
+const shape = new Array(4); // single, reusable allocation
+
+// Build a billboard sprite quad centered on a point. Sprites are intended to be drawn in screenspace, and have
+// properties for width, height, angle, and texture UVs. Curved label segment sprites have additional properties
+// for interpolating their position and angle across zooms.
+export function buildQuadForPoint (
+    point: number[],
+    vertex_data: VertexData,
+    vertex_template: number[],
+    vindex: VertexIndex,
+    size: number[],
+    offset: number[],
+    offsets: number[] | null,
+    pre_angles: number[] | null,
+    angle: number,
+    angles: number[] | null,
+    texcoords: number[] | undefined,
+    curve: boolean) {
+
+    // Half-sized point dimensions in fixed point
+    const w2 = size[0] * size_normalize;
+    const h2 = size[1] * size_normalize;
+    shape[0] = -w2;
+    shape[1] = -h2;
+    shape[2] = w2;
+    shape[3] = h2;
+
+    const uvs = texcoords || default_uvs;
+
+    const vertex_elements = vertex_data.vertex_elements;
+    let element_offset = vertex_data.vertex_count;
+
+    for (let p=0; p < 4; p++) {
+        vertex_template[vindex.a_position + 0] = point[0];
+        vertex_template[vindex.a_position + 1] = point[1];
+
+        vertex_template[vindex.a_shape + 0] = shape[ix[p]];
+        vertex_template[vindex.a_shape + 1] = shape[iy[p]];
+        vertex_template[vindex.a_shape + 2] = angle;
+
+        vertex_template[vindex.a_offset + 0] = offset[0];
+        vertex_template[vindex.a_offset + 1] = offset[1];
+
+        // Add texcoords
+        if (vindex.a_texcoord) {
+            vertex_template[vindex.a_texcoord + 0] = uvs[ix[p]] * texcoord_normalize;
+            vertex_template[vindex.a_texcoord + 1] = uvs[iy[p]] * texcoord_normalize;
+        }
+
+        // Add curved label segment props
+        if (curve) {
+            if (!pre_angles || !angles || !offsets) throw new TypeError('Curved quads require per-segment angle and offset samples');
+            // 1 byte (signed) range: [-127, 128]
+            // actual range: [-2pi, 2pi]
+            // total: multiply by 128 / (2 PI)
+            vertex_template[vindex.a_pre_angles + 0] = pre_angles_normalize * pre_angles[0];
+            vertex_template[vindex.a_pre_angles + 1] = pre_angles_normalize * pre_angles[1];
+            vertex_template[vindex.a_pre_angles + 2] = pre_angles_normalize * pre_angles[2];
+            vertex_template[vindex.a_pre_angles + 3] = pre_angles_normalize * pre_angles[3];
+
+            // 2 byte (signed) of resolution [-32767, 32768]
+            // actual range: [-2pi, 2pi]
+            // total: multiply by 32768 / (2 PI) = 16384 / PI
+            vertex_template[vindex.a_angles + 0] = angles_normalize * angles[0];
+            vertex_template[vindex.a_angles + 1] = angles_normalize * angles[1];
+            vertex_template[vindex.a_angles + 2] = angles_normalize * angles[2];
+            vertex_template[vindex.a_angles + 3] = angles_normalize * angles[3];
+
+            // offset range can be [0, 65535]
+            // actual range: [0, 1024]
+            vertex_template[vindex.a_offsets + 0] = offsets_normalize * offsets[0];
+            vertex_template[vindex.a_offsets + 1] = offsets_normalize * offsets[1];
+            vertex_template[vindex.a_offsets + 2] = offsets_normalize * offsets[2];
+            vertex_template[vindex.a_offsets + 3] = offsets_normalize * offsets[3];
+        }
+
+        vertex_data.addVertex(vertex_template);
+    }
+
+    vertex_elements.push(element_offset + 0);
+    vertex_elements.push(element_offset + 1);
+    vertex_elements.push(element_offset + 2);
+    vertex_elements.push(element_offset + 2);
+    vertex_elements.push(element_offset + 3);
+    vertex_elements.push(element_offset + 0);
+
+    return 2; // geom count is always two triangles, for one quad
+}

package/src/builders/polygons.ts

@@ -0,0 +1,225 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+// Polygon builders
+
+import Geo from '../utils/geo';
+import Vector from '../utils/vector';
+import { default_uvs, outsideTile } from './common';
+
+import earcut from 'earcut';
+import quickselect from 'quickselect';
+import type {GeometryPolygon, GeometryVertexData} from './geometry-types';
+
+const up_vec3 = [0, 0, 1];
+
+type PolygonCoordinates = GeometryPolygon;
+type VertexData = GeometryVertexData;
+type PolygonBuildOptions = {
+    texcoord_index?: number;
+    texcoord_scale?: number[];
+    texcoord_normalize?: number;
+};
+
+
+/**
+ * To tesselate flat 2D polygons.
+ * The x & y coordinates will be set as first two elements of provided vertex_template.
+ * @param {Array.<Array.<Array.<Array.<number>>>>} polygons The polygons to tesselate.
+ * @param {VertexData} vertex_data The VertexData were to store the results
+ * @param {Array.<number>} vertex_template The vertex template to use
+ * @param {Object} options The texture coordinate options to apply
+ * @return {number} the number of the resulting geometries (triangles)
+ */
+export function buildPolygons (
+    polygons: PolygonCoordinates[], vertex_data: VertexData, vertex_template: number[],
+    { texcoord_index, texcoord_scale, texcoord_normalize }: PolygonBuildOptions) {
+    const normalizedTextureScale = texcoord_normalize || 1;
+
+    let vertex_elements = vertex_data.vertex_elements,
+        num_polygons = polygons.length,
+        geom_count = 0,
+        min_u = 0, min_v = 0, max_u = 0, max_v = 0,
+        min_x = 0, min_y = 0, max_x = 0, max_y = 0,
+        span_x = 0, span_y = 0, scale_u = 0, scale_v = 0;
+
+    if (texcoord_index) {
+        [min_u, min_v, max_u, max_v] = texcoord_scale || default_uvs;
+    }
+
+    for (let p = 0; p < num_polygons; p++) {
+
+        const max_rings = 500;
+        let polygon = polygons[p];
+
+        if (polygon.length > max_rings) {
+            polygon = [...polygon]; // copy to avoid modifying original
+            quickselect(polygon, max_rings, 1, polygon.length - 1, (a, b) => b.area! - a.area!);
+            polygon = polygon.slice(0, max_rings);
+        }
+
+        const indices = triangulatePolygon(earcut.flatten(polygon));
+        const num_indices = indices.length;
+        const element_offset = vertex_data.vertex_count;
+
+        // The vertices and vertex-elements must not be added if earcut returns no indices:
+        if (num_indices) {
+
+            // Find polygon extents to calculate UVs, fit them to the axis-aligned bounding box:
+            if (texcoord_index) {
+                [min_x, min_y, max_x, max_y] = Geo.findBoundingBox(polygon),
+                span_x = max_x - min_x,
+                span_y = max_y - min_y,
+                scale_u = (max_u - min_u) / span_x,
+                scale_v = (max_v - min_v) / span_y;
+            }
+
+            for (let ring_index = 0; ring_index < polygon.length; ring_index++) {
+                // Add vertex data:
+                let polygon_ring = polygon[ring_index];
+                for (let i = 0; i < polygon_ring.length; i++) {
+                    let vertex = polygon_ring[i];
+                    vertex_template[0] = vertex[0];
+                    vertex_template[1] = vertex[1];
+
+                    // Add UVs:
+                    if (texcoord_index) {
+                        vertex_template[texcoord_index + 0] = ((vertex[0] - min_x) * scale_u + min_u) * normalizedTextureScale;
+                        vertex_template[texcoord_index + 1] = ((vertex[1] - min_y) * scale_v + min_v) * normalizedTextureScale;
+                    }
+
+                    vertex_data.addVertex(vertex_template);
+                }
+            }
+
+            // Add element indices:
+            for (let i = 0; i < num_indices; i++) {
+                vertex_elements.push(element_offset + indices[i]);
+            }
+            geom_count += num_indices / 3;
+
+        }
+    }
+    return geom_count;
+}
+
+
+// Tesselate and extrude a flat 2D polygon into a simple 3D model with fixed height and add to GL vertex buffer
+export function buildExtrudedPolygons (
+    polygons: PolygonCoordinates[],
+    z: number, height: number, min_height: number,
+    vertex_data: VertexData, vertex_template: number[],
+    normal_index: number,
+    normal_normalize: number,
+    {
+        remove_tile_edges,
+        tile_edge_tolerance,
+        texcoord_index,
+        texcoord_scale,
+        texcoord_normalize,
+        winding
+    }: PolygonBuildOptions & {
+        remove_tile_edges?: boolean;
+        tile_edge_tolerance?: number;
+        normal_index?: number;
+        winding?: string;
+    }) {
+    const normalizedTextureScale = texcoord_normalize || 1;
+
+    // Top
+    var min_z = z + (min_height || 0);
+    var max_z = z + height;
+    vertex_template[2] = max_z;
+    var geom_count = buildPolygons(polygons, vertex_data, vertex_template, { texcoord_index, texcoord_scale, texcoord_normalize });
+
+    var vertex_elements = vertex_data.vertex_elements;
+    var element_offset = vertex_data.vertex_count;
+
+    // Walls
+    // Fit UVs to wall quad
+    let texcoords: number[][] = [];
+    if (texcoord_index) {
+        var [min_u, min_v, max_u, max_v] = texcoord_scale || default_uvs;
+        texcoords = [
+            [min_u, max_v],
+            [min_u, min_v],
+            [max_u, min_v],
+            [max_u, max_v]
+        ];
+    }
+
+    var num_polygons = polygons.length;
+    for (var p=0; p < num_polygons; p++) {
+        var polygon = polygons[p];
+
+        for (var q=0; q < polygon.length; q++) {
+            var contour = polygon[q];
+
+            for (var w=0; w < contour.length - 1; w++) {
+                if (remove_tile_edges && outsideTile(contour[w], contour[w+1], tile_edge_tolerance || 0)) {
+                    continue; // don't extrude tile edges
+                }
+
+                // Wall order is dependent on winding order, so that normals face outward
+                let w0, w1;
+                if (winding === 'CCW') {
+                    w0 = w;
+                    w1 = w+1;
+                }
+                else {
+                    w0 = w+1;
+                    w1 = w;
+                }
+
+                // Two triangles for the quad formed by each vertex pair, going from bottom to top height
+                var wall_vertices = [
+                    [contour[w1][0], contour[w1][1], max_z],
+                    [contour[w1][0], contour[w1][1], min_z],
+                    [contour[w0][0], contour[w0][1], min_z],
+                    [contour[w0][0], contour[w0][1], max_z]
+                ];
+
+                // Calc the normal of the wall from up vector and one segment of the wall triangles
+                let wall_vec = Vector.normalize([contour[w1][0] - contour[w0][0], contour[w1][1] - contour[w0][1], 0]);
+                let normal = Vector.cross(up_vec3, wall_vec) as number[]; // Three-dimensional inputs produce a vector, not a 2D scalar.
+
+                // Update vertex template with current surface normal
+                vertex_template[normal_index + 0] = normal[0] * normal_normalize;
+                vertex_template[normal_index + 1] = normal[1] * normal_normalize;
+                vertex_template[normal_index + 2] = normal[2] * normal_normalize;
+
+                for (var wv=0; wv < wall_vertices.length; wv++) {
+                    vertex_template[0] = wall_vertices[wv][0];
+                    vertex_template[1] = wall_vertices[wv][1];
+                    vertex_template[2] = wall_vertices[wv][2];
+
+                    if (texcoord_index) {
+                        vertex_template[texcoord_index + 0] = texcoords[wv][0] * normalizedTextureScale;
+                        vertex_template[texcoord_index + 1] = texcoords[wv][1] * normalizedTextureScale;
+                    }
+
+                    vertex_data.addVertex(vertex_template);
+                }
+
+                vertex_elements.push(element_offset + 0);
+                vertex_elements.push(element_offset + 1);
+                vertex_elements.push(element_offset + 2);
+                vertex_elements.push(element_offset + 2);
+                vertex_elements.push(element_offset + 3);
+                vertex_elements.push(element_offset + 0);
+
+                element_offset += 4;
+                geom_count += 2;
+            }
+        }
+    }
+    return geom_count;
+}
+
+// Triangulation using earcut
+// https://github.com/mapbox/earcut
+export function triangulatePolygon (data: {vertices: number[]; holes: number[]; dimensions: number}) {
+    return earcut(data.vertices, data.holes, data.dimensions);
+}