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

package/src/sources/decoded_tile_store.ts

@@ -0,0 +1,245 @@
+// tangram-layers
+// SPDX-License-Identifier: MIT
+// Copyright (c) vis.gl contributors
+
+/** One consumer's interest in a decoded tile; releasing it cannot cancel another consumer. */
+export interface DecodedTileLease<ValueT> {
+    /** Independent completion, rejected promptly when this lease is released before completion. */
+    readonly promise: Promise<ValueT>;
+    /** Whether this consumer still owns a lease, including after synchronous source invalidation. */
+    isActive(): boolean;
+    /** Idempotently release this consumer's residency and request ownership. */
+    release(): void;
+}
+
+/** Source revision and unwrapped normalized data identity, never a mesh/style key. */
+export interface DecodedTileAcquisition<ValueT> {
+    /** Opaque source-instance revision, owned by the worker adapter. */
+    readonly source: object;
+    /** Normalized data coordinate key, preserving world-copy distinctions. */
+    readonly key: string;
+    /** Original acquisition/decode procedure; invoked once for compatible concurrent leases. */
+    load(signal: AbortSignal): Promise<ValueT>;
+}
+
+/** Detached diagnostics; missing allocation estimates never masquerade as zero decoded bytes. */
+export interface DecodedTileStatistics {
+    /** Pending unique acquisitions, including queued work. */
+    loadingTiles: number;
+    /** Unique acquisitions waiting for a source-procedure slot. */
+    queuedTiles: number;
+    /** Running source procedures, including cancelled procedures that have not settled. */
+    activeAcquisitions: number;
+    /** Configured source-procedure limit; undefined means unlimited. */
+    maxConcurrentLoads: number | undefined;
+    /** Ready records protected by live leases; there is no unreferenced warm cache. */
+    readyTiles: number;
+    /** Live consumer leases across pending and ready records. */
+    consumers: number;
+    /** Actual acquisition attempts since store creation. */
+    acquisitions: number;
+    /** Acquisitions served by an existing pending or ready record. */
+    sharedAcquisitions: number;
+    /** Requests cancelled when their final lease or source revision was released. */
+    cancelledAcquisitions: number;
+    /** Rejected acquisition attempts, excluding invalidated late completions. */
+    failedAcquisitions: number;
+    /** Ready payload bytes, undefined if any live ready record has unknown size. */
+    decodedBytes: number | undefined;
+}
+
+/** Request capacity is independent of styled mesh-build scheduling and residency. */
+export interface DecodedTileStoreOptions {
+    /** Positive safe integer; omission preserves unlimited acquisition. */
+    maxConcurrentLoads?: number;
+}
+
+/** Validate an optional load budget before creating resources or worker state. */
+export function validateConcurrentTileLoads(value: unknown): number | undefined {
+    if (value === undefined) return undefined;
+    if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+        throw new Error('maxConcurrentTileLoadsPerWorker must be a positive safe integer');
+    }
+    return value;
+}
+
+/** Consumer settlement hooks do not contain renderer or worker tile objects. */
+interface LeaseSettlement<ValueT> {
+    /** Resolve only this lease. */
+    resolve(value: ValueT): void;
+    /** Reject only this lease. */
+    reject(error: unknown): void;
+}
+
+/** One source/data acquisition, independent of styled meshes and build generations. */
+interface DecodedRecord<ValueT> {
+    /** Cancellation belongs to the unique acquisition, not its first consumer. */
+    readonly controller: AbortController;
+    /** Live consumers, including ready records retained for overzoom/rebuild reuse. */
+    readonly consumers: Set<LeaseSettlement<ValueT>>;
+    /** Successful content publication, absent while acquisition is pending. */
+    result?: {value: ValueT};
+}
+
+/** Portable cancellation error for leases, source invalidation, and stale publication. */
+export function createTileLeaseAbortError(): Error {
+    const error = new Error('Decoded tile lease released');
+    error.name = 'AbortError';
+    return error;
+}
+
+/** Worker-local shared acquisition with source-instance revisions and zero warm retention. */
+export default class DecodedTileStore<ValueT> {
+    /** Source revisions stay retained only while they have live records. */
+    private readonly sources = new Map<object, Map<string, DecodedRecord<ValueT>>>();
+    /** Optional decoded allocation estimator; encoded network bytes are not a substitute. */
+    private readonly getByteLength: (value: ValueT) => number | undefined;
+    /** FIFO unique-content queue; duplicate leases never consume another slot. */
+    private readonly queued = new Map<DecodedRecord<ValueT>, DecodedTileAcquisition<ValueT>>();
+    /** Fixed worker-local source-procedure limit, unrelated to GPU mesh ownership. */
+    private readonly maxConcurrentLoads: number | undefined;
+    /** Settling an aborted but non-cooperative procedure still releases exactly one slot. */
+    private activeAcquisitions = 0;
+    /** Batch synchronous leases and cancellation before starting their providers. */
+    private scheduled = false;
+    /** Actual unique acquisition attempts. */
+    private acquisitions = 0;
+    /** Reused pending/ready acquisitions. */
+    private sharedAcquisitions = 0;
+    /** Underlying requests cancelled at final release or invalidation. */
+    private cancelledAcquisitions = 0;
+    /** Underlying acquisition failures. */
+    private failedAcquisitions = 0;
+
+    /** Create an empty store without fetch, decode, traversal, or GPU dependencies. */
+    constructor(getByteLength: (value: ValueT) => number | undefined = () => undefined, options: DecodedTileStoreOptions = {}) {
+        this.getByteLength = getByteLength;
+        this.maxConcurrentLoads = validateConcurrentTileLoads(options.maxConcurrentLoads);
+    }
+
+    /** Acquire one consumer lease, sharing only the exact source revision and data key. */
+    acquireTile(request: DecodedTileAcquisition<ValueT>): DecodedTileLease<ValueT> {
+        let records = this.sources.get(request.source);
+        if (!records) { records = new Map(); this.sources.set(request.source, records); }
+        let record = records.get(request.key);
+        const created = !record;
+        if (!record) {
+            record = {controller: new AbortController(), consumers: new Set()};
+            records.set(request.key, record);
+        } else this.sharedAcquisitions++;
+        const current = record;
+        let resolveLease: (value: ValueT) => void = () => {};
+        let rejectLease: (error: unknown) => void = () => {};
+        const promise = new Promise<ValueT>((resolve, reject) => {
+            resolveLease = resolve;
+            rejectLease = reject;
+        });
+        const consumer = {resolve: resolveLease, reject: rejectLease};
+        current.consumers.add(consumer);
+        if (current.result) consumer.resolve(current.result.value);
+        if (created) {
+            this.queued.set(current, request);
+            this.scheduleAcquisitions();
+        }
+        return {promise, isActive: () => current.consumers.has(consumer), release: () => {
+            if (!current.consumers.delete(consumer)) return;
+            if (!current.result) consumer.reject(createTileLeaseAbortError());
+            if (current.consumers.size === 0) {
+                this.forgetRecord(request.source, request.key, current);
+                this.cancelRecord(current);
+            }
+        }};
+    }
+
+    /** Release one obsolete source revision without touching a successor source instance. */
+    invalidateSource(source: object): void {
+        const records = this.sources.get(source);
+        if (!records) return;
+        this.sources.delete(source);
+        for (const record of records.values()) {
+            for (const lease of record.consumers) lease.reject(createTileLeaseAbortError());
+            record.consumers.clear();
+            this.cancelRecord(record);
+        }
+    }
+
+    /** Return unique content and consumer counts without retaining or exposing internal records. */
+    getStatistics(): DecodedTileStatistics {
+        let loadingTiles = 0, readyTiles = 0, consumers = 0, decodedBytes: number | undefined = 0;
+        for (const records of this.sources.values()) for (const record of records.values()) {
+            consumers += record.consumers.size;
+            if (!record.result) { loadingTiles++; continue; }
+            readyTiles++;
+            const bytes = this.getByteLength(record.result.value);
+            if (bytes === undefined || !Number.isFinite(bytes) || bytes < 0) decodedBytes = undefined;
+            else if (decodedBytes !== undefined) decodedBytes += bytes;
+        }
+        return {loadingTiles, queuedTiles: this.queued.size, activeAcquisitions: this.activeAcquisitions,
+            maxConcurrentLoads: this.maxConcurrentLoads, readyTiles, consumers, decodedBytes, acquisitions: this.acquisitions,
+            sharedAcquisitions: this.sharedAcquisitions, cancelledAcquisitions: this.cancelledAcquisitions,
+            failedAcquisitions: this.failedAcquisitions};
+    }
+
+    /** Cancel all pending work and release content; subsequent use starts from an empty store. */
+    finalize(): void { for (const source of this.sources.keys()) this.invalidateSource(source); }
+
+    /** Drain only when a source procedure settles, not when its styled mesh finishes. */
+    private scheduleAcquisitions(): void {
+        if (this.scheduled || this.queued.size === 0) return;
+        this.scheduled = true;
+        void Promise.resolve().then(() => {
+            this.scheduled = false;
+            for (const [record, request] of this.queued) {
+                if (this.activeAcquisitions >= (this.maxConcurrentLoads ?? Infinity)) break;
+                this.queued.delete(record);
+                if (!this.isCurrent(request.source, request.key, record)) continue;
+                this.startAcquisition(request, record);
+            }
+        });
+    }
+
+    /** A slot follows the original procedure even if all consumer leases are released early. */
+    private startAcquisition(request: DecodedTileAcquisition<ValueT>, record: DecodedRecord<ValueT>): void {
+        this.activeAcquisitions++;
+        this.acquisitions++;
+        let loading: Promise<ValueT>;
+        try { loading = request.load(record.controller.signal); }
+        catch (error) { loading = Promise.reject(error); }
+        void Promise.resolve(loading).then(value => {
+            if (!this.isCurrent(request.source, request.key, record)) return;
+            record.result = {value};
+            for (const lease of record.consumers) lease.resolve(value);
+        }, error => {
+            if (!this.isCurrent(request.source, request.key, record)) return;
+            this.failedAcquisitions++;
+            this.forgetRecord(request.source, request.key, record);
+            for (const lease of record.consumers) lease.reject(error);
+            record.consumers.clear();
+        }).finally(() => {
+            this.activeAcquisitions--;
+            this.scheduleAcquisitions();
+        });
+    }
+
+    /** A late completion cannot publish over a replacement attempt for the same coordinate. */
+    private isCurrent(source: object, key: string, record: DecodedRecord<ValueT>): boolean {
+        return !record.controller.signal.aborted && this.sources.get(source)?.get(key) === record;
+    }
+
+    /** Forget only the matching attempt and release empty source maps immediately. */
+    private forgetRecord(source: object, key: string, record: DecodedRecord<ValueT>): void {
+        const records = this.sources.get(source);
+        if (records?.get(key) !== record) return;
+        records.delete(key);
+        if (records.size === 0) this.sources.delete(source);
+    }
+
+    /** Ready content has no pending request; cancellation is issued at most once. */
+    private cancelRecord(record: DecodedRecord<ValueT>): void {
+        if (!record.result && !record.controller.signal.aborted) {
+            this.cancelledAcquisitions++;
+            record.controller.abort();
+            this.queued.delete(record);
+        }
+    }
+}

package/src/sources/geojson.ts

@@ -0,0 +1,300 @@
+// 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 DataSource, {NetworkSource, NetworkTileSource} from './data_source';
+import {decodeMultiPolygon} from './mvt';
+import Geo from '../utils/geo';
+
+// For tiling GeoJSON client-side
+import geojsonvt from 'geojson-vt';
+
+type SourceConfig = Record<string, any>;
+
+/**
+ GeoJSON standalone (non-tiled) source
+ Uses geojson-vt split into tiles client-side
+*/
+
+export class GeoJSONSource extends NetworkSource {
+
+    load_data: Promise<any> | null = null;
+    tile_indexes!: Record<string, any>;
+    loaded = false;
+
+    constructor(source: SourceConfig, sources?: Record<string, unknown>) {
+        super(source, sources);
+        this.load_data = null;
+        this.tile_indexes = {}; // geojson-vt tile indices, by layer name
+        this.setTileSize(512); // auto-tile to 512px tiles for fewer internal tiles
+        this.pad_scale = 0; // we don't want padding on auto-tiled sources
+    }
+
+    _load(dest?: any): Promise<any> {
+        if (!dest) {
+            throw new Error('GeoJSON source loading requires a destination tile');
+        }
+        if (!this.load_data) {
+            this.load_data = super._load({ source_data: { layers: {} } }).then(data => {
+                // Warn and continue on data source error
+                if (data.source_data.error) {
+                    log('warn', `data source load error(s) for source '${this.name}', URL '${this.url}': ${data.source_data.error}`);
+                }
+
+                let layers = data.source_data.layers;
+                for (let layer_name in layers) {
+                    this.tile_indexes[layer_name] = geojsonvt(layers[layer_name], {
+                        maxZoom: this.max_zoom,  // max zoom to preserve detail on
+                        tolerance: 1.5, // simplification tolerance (higher means simpler) NB: half the default to accomodate 512px tiles
+                        extent: Geo.tile_scale, // tile extent (both width and height)
+                        buffer: 0.0001     // tile buffer on each side
+                    });
+                }
+
+                this.loaded = true;
+                return data;
+            });
+        }
+
+        return this.load_data.then(() => {
+            for (let layer_name in this.tile_indexes) {
+                dest.source_data.layers[layer_name] = this.getTileFeatures(dest, layer_name);
+            }
+            return dest;
+        });
+    }
+
+    getTileFeatures(tile: any, layer_name: string): any {
+        let coords = Geo.wrapTile(tile.coords, {x: true, y: false});
+
+        // request a particular tile
+        let t = this.tile_indexes[layer_name].getTile(coords.z, coords.x, coords.y);
+
+        // Convert from MVT-style JSON struct to GeoJSON
+        let collection;
+        if (t && t.features) {
+            collection = {
+                type: 'FeatureCollection',
+                features: [] as any[]
+            };
+
+            for (let i=0; i < t.features.length; i++) {
+                const feature = t.features[i];
+
+                // GeoJSON feature
+                let f: any = {
+                    type: 'Feature',
+                    geometry: {},
+                    id: feature.id,
+                    properties: feature.tags
+                };
+
+                if (feature.type === 1) {
+                    f.geometry.coordinates = feature.geometry.map((coord: any) => [coord[0], coord[1]]);
+                    f.geometry.type = 'MultiPoint';
+                }
+                else if (feature.type === 2 || feature.type === 3) {
+                    f.geometry.coordinates = feature.geometry.map((ring: any[]) =>
+                        ring.map((coord: any) => [coord[0], coord[1]])
+                    );
+
+                    if (feature.type === 2) {
+                        f.geometry.type = 'MultiLineString';
+                    }
+                    else  {
+                        f.geometry = decodeMultiPolygon(f.geometry); // un-flatten rings
+                        if (f.geometry == null) { // skip polys that couldn't be decoded (e.g. degenerate)
+                            continue;
+                        }
+                    }
+                }
+                else {
+                    continue;
+                }
+
+                collection.features.push(f);
+            }
+        }
+
+        return collection;
+    }
+
+    formatURL () {
+        return this.url;
+    }
+
+    parseSourceData (tile?: any, source?: any, response?: any): void {
+        if (!tile || !source) {
+            throw new Error('GeoJSON source parsing requires a tile and source data');
+        }
+        let data = typeof response === 'string' ? JSON.parse(response) : response;
+        let layers = this.getLayers(data);
+        source.layers = this.preprocessLayers(layers, tile);
+    }
+
+    preprocessLayers (layers: any, tile: any): any {
+        for (let key in layers) {
+            let layer = layers[key];
+            layer.features = this.preprocessFeatures(layer.features);
+        }
+
+        // Apply optional data transform
+        if (typeof this.transform === 'function') {
+            const tile_data = {
+                min: Object.assign({}, tile.min),
+                max: Object.assign({}, tile.max),
+                coords: Object.assign({}, tile.coords)
+            };
+            if (Object.keys(layers).length === 1 && layers._default) {
+                layers._default = this.transform(layers._default, this.extra_data, tile_data); // single-layer
+            }
+            else {
+                layers = this.transform(layers, this.extra_data, tile_data); // multiple layers
+            }
+        }
+
+        return layers;
+    }
+
+    // Preprocess features. Currently used to add a new "centroid" feature for polygon labeling
+    preprocessFeatures (features: any[]): any[] {
+        // Remove features without geometry (which is valid GeoJSON)
+        features = features.filter(f => f.geometry != null);
+
+        // Define centroids for polygons for centroid label placement
+        // Avoids redundant label placement for each generated tile at higher zoom levels
+        if (this.config.generate_label_centroids){
+            let features_centroid: any[] = [];
+            let centroid_properties = {'label_placement' : true};
+
+            features.forEach(feature => {
+                let coordinates, centroid_feature;
+                if (feature.geometry.type === 'Polygon') {
+                    coordinates = feature.geometry.coordinates;
+                    centroid_feature = getCentroidFeatureForPolygon(coordinates, feature.id, feature.properties, centroid_properties);
+                    features_centroid.push(centroid_feature);
+                }
+                else if (feature.geometry.type === 'MultiPolygon') {
+                    // Add centroid feature for largest polygon
+                    coordinates = feature.geometry.coordinates;
+                    let max_area = -Infinity;
+                    let max_area_index = 0;
+                    for (let index = 0; index < coordinates.length; index++) {
+                        let area = Geo.polygonArea(coordinates[index]) || 0;
+                        if (area > max_area) {
+                            max_area = area;
+                            max_area_index = index;
+                        }
+                    }
+                    centroid_feature = getCentroidFeatureForPolygon(coordinates[max_area_index], feature.id, feature.properties, centroid_properties);
+                    features_centroid.push(centroid_feature);
+                }
+            });
+
+            // append centroid features to features array
+            features_centroid = features_centroid.filter(x => x); // remove null features
+            Array.prototype.push.apply(features, features_centroid);
+        }
+
+        return features;
+    }
+
+    // Detect single or multiple layers in returned data
+    getLayers (data: any): any {
+        if (data.type === 'Feature') {
+            return {
+                _default: {
+                    type: 'FeatureCollection',
+                    features: [data]
+                }
+            };
+        }
+        else if (data.type === 'FeatureCollection') {
+            return {
+                _default: data
+            };
+        }
+        else {
+            return data;
+        }
+    }
+
+}
+
+/**
+ GeoJSON vector tiles
+ @class GeoJSONTileSource
+*/
+export class GeoJSONTileSource extends NetworkTileSource {
+
+    constructor(source: SourceConfig, sources?: Record<string, unknown>) {
+        super(source, sources);
+    }
+
+    parseSourceData (tile?: any, source?: any, response?: any): void {
+        if (!tile || !source) {
+            throw new Error('GeoJSON tile parsing requires a tile and source data');
+        }
+        let data = typeof response === 'string' ? JSON.parse(response) : response;
+        this.prepareGeoJSON(data, tile, source);
+    }
+
+    prepareGeoJSON (data: any, tile: any, source: any): void {
+        // Apply optional data transform
+        if (typeof this.transform === 'function') {
+            const tile_data = {
+                min: Object.assign({}, tile.min),
+                max: Object.assign({}, tile.max),
+                coords: Object.assign({}, tile.coords)
+            };
+            data = this.transform(data, this.extra_data, tile_data);
+        }
+
+        source.layers = GeoJSONSource.prototype.getLayers(data);
+
+        // A "synthetic" tile that adjusts the tile min anchor to account for tile longitude wrapping
+        let anchor = {
+            coords: tile.coords,
+            min: Geo.metersForTile(Geo.wrapTile(tile.coords, {x: true, y: false}))
+        };
+
+        DataSource.projectData(source); // mercator projection
+        DataSource.scaleData(source, anchor); // re-scale from meters to local tile coords
+    }
+
+}
+
+// Check for URL tile pattern, if not found, treat as standalone GeoJSON/TopoJSON object
+DataSource.register('GeoJSON', (source: SourceConfig) => {
+    return GeoJSONTileSource.urlHasTilePattern(source.url) ? GeoJSONTileSource : GeoJSONSource;
+});
+
+
+// Helper function to create centroid point feature from polygon coordinates and provided feature meta-data
+function getCentroidFeatureForPolygon (
+    coordinates: any,
+    id: string | number | undefined,
+    properties: Record<string, unknown>,
+    newProperties: Record<string, unknown>
+): any {
+    let centroid = Geo.centroid(coordinates);
+    if (!centroid) {
+        return;
+    }
+
+    // clone properties and mixix newProperties
+    let centroid_properties = {};
+    Object.assign(centroid_properties, properties, newProperties);
+
+    return {
+        type: 'Feature',
+        id,
+        properties: centroid_properties,
+        geometry: {
+            type: 'Point',
+            coordinates: centroid
+        }
+    };
+}