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

package/src/sources/mvt.ts

@@ -0,0 +1,247 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import DataSource, {NetworkTileSource} from './data_source';
+import Geo from '../utils/geo';
+import log from '../utils/log';
+import {
+    convertMvtTileWithLegacy,
+    decodeMultiPolygon,
+    parseMvtWithLegacy,
+    type MvtTile
+} from '../procedures/mvt-legacy';
+import {parseMvt, registerMvtDecoder} from '../procedures/mvt-parser';
+import {getMvtTileProvider} from '../procedures/mvt-tile-provider';
+import type {MvtTileProviderSource} from '../procedures/mvt-tile-provider';
+import {parseMvtJsonProperties} from '../procedures/mvt-properties';
+import {createTileSourceMetadata} from './tile_source_metadata';
+import type {TangramTileSourceMetadata} from './tile_source_metadata';
+import {updateTileSourceRequest} from './tile_source_state';
+
+const PARSE_JSON_TYPE = {
+    NONE: 0,
+    ALL: 1,
+    SOME: 2
+};
+
+type MvtSourceConfig = {
+    decoder?: string;
+    tile_provider?: string;
+    parse_json?: boolean | readonly string[];
+    name?: string;
+    [key: string]: unknown;
+};
+
+type TileData = {
+    /** Worker cancellation may precede deferred TileJSON URL resolution. */
+    canceled?: boolean;
+    min: Record<string, unknown>;
+    max: Record<string, unknown>;
+    coords: Record<string, unknown> & {x: number; y: number; z: number};
+    source_data?: SourceData;
+    debug?: Record<string, any>;
+};
+
+type SourceData = {
+    layers?: Record<string, unknown>;
+    url?: string;
+    error?: string | null;
+};
+
+/**
+ Mapbox Vector Tile format
+ @class MVTSource
+*/
+export class MVTSource extends NetworkTileSource {
+
+    decoder!: string;
+    tile_provider?: string;
+    parse_json_type!: number;
+    parse_json_prop_list?: readonly string[];
+    /** Archive handles belong to this source instance, never a global URL cache. */
+    private providerSources = new Map<string, MvtTileProviderSource>();
+    /** Source replacement cancels every live tile request, including custom function providers. */
+    private providerRequests = new Set<AbortController>();
+    /** Additional archive credits are retained separately from scene-authored attribution. */
+    private providerAttributions: string[] = [];
+    /** Disposed instances cannot reopen an archive after asynchronous URL resolution. */
+    private disposed = false;
+
+    /** Resolve a factory once per effective URL; stateless registered functions stay unchanged. */
+    private getProviderSource(url: string): MvtTileProviderSource | undefined {
+        if (this.disposed) throw new Error('MVT source is disposed');
+        const provider = this.tile_provider && getMvtTileProvider(this.tile_provider);
+        if (!provider) throw new Error(`MVT tile provider '${this.tile_provider}' is not registered in this worker`);
+        if (typeof provider === 'function') return undefined;
+        let source = this.providerSources.get(url);
+        if (!source) {
+            source = provider.createSource(url, {headers: this.request_headers});
+            this.providerSources.set(url, source);
+        }
+        return source;
+    }
+
+    /** Include provider credits alongside authored and TileJSON attribution. */
+    getAttributions(): string[] { return [...new Set([...super.getAttributions(), ...this.providerAttributions])]; }
+
+    /** Normalize TileJSON and archive capabilities without changing authored layout or decoder choice. */
+    async getMetadata(): Promise<TangramTileSourceMetadata> {
+        if (!this.tile_provider) return super.getMetadata();
+        const url = await this.resolveURL();
+        const provider = this.getProviderSource(url);
+        const metadata = await provider?.getMetadata?.();
+        if (this.disposed) throw new Error('MVT source is disposed');
+        this.providerAttributions = (metadata?.attributions ?? []).filter(value => typeof value === 'string' && value.trim()).map(value => value.trim());
+        return createTileSourceMetadata(this, {...this.tile_metadata, ...metadata});
+    }
+
+    /** Dispose source-owned archive resources and cancel requests on replacement/removal/worker reset. */
+    dispose(): void {
+        super.dispose();
+        this.disposed = true;
+        for (const controller of this.providerRequests) controller.abort();
+        this.providerRequests.clear();
+        for (const provider of this.providerSources.values()) provider.dispose();
+        this.providerSources.clear();
+    }
+
+    constructor (source: MvtSourceConfig, sources?: Record<string, unknown>) {
+        super(source, sources);
+        this.response_type = 'arraybuffer'; // binary data
+        this.decoder = source.decoder || 'tangram';
+        this.tile_provider = source.tile_provider;
+
+        // Optionally parse some or all properties from JSON strings
+        if (source.parse_json === true) {
+            // try to parse all properties (least efficient)
+            this.parse_json_type = PARSE_JSON_TYPE.ALL;
+        }
+        else if (Array.isArray(source.parse_json)) {
+            // try to parse a specific list of property names (more efficient)
+            this.parse_json_type = PARSE_JSON_TYPE.SOME;
+            this.parse_json_prop_list = source.parse_json;
+        }
+        else {
+            if (source.parse_json != null) {
+                let msg = `Data source '${this.name}': 'parse_json' parameter should be 'true', or an array of ` +
+                    `property names (was '${JSON.stringify(source.parse_json)}')`;
+                log({ level: 'warn', once: true }, msg);
+            }
+
+            // skip parsing entirely (default behavior)
+            this.parse_json_type = PARSE_JSON_TYPE.NONE;
+        }
+    }
+
+    loadURL (dest: TileData, url_template: string): Promise<any> {
+        if (!this.tile_provider) {
+            return super.loadURL(dest, url_template);
+        }
+
+        const tileProvider = getMvtTileProvider(this.tile_provider);
+        if (!tileProvider) {
+            return Promise.reject(new Error(`MVT tile provider '${this.tile_provider}' is not registered in this worker`));
+        }
+
+        const url = this.formatURL(url_template, dest);
+        const sourceData = dest.source_data as SourceData;
+        dest.debug = dest.debug || {};
+        const debug = dest.debug;
+        debug.network = +new Date();
+        sourceData.url = url;
+        sourceData.error = null;
+
+        const providerTileIndex = Geo.wrapTile(dest.coords, {x: true, y: false});
+        if (this.tms) {
+            providerTileIndex.y = Math.pow(2, providerTileIndex.z) - 1 - providerTileIndex.y;
+        }
+
+        const controller = new AbortController();
+        if (dest.canceled) controller.abort();
+        this.providerRequests.add(controller);
+        updateTileSourceRequest(dest, {cancel: () => controller.abort()});
+        const checkActive = (): void => {
+            if (controller.signal.aborted || this.disposed) {
+                const error = new Error('MVT provider request aborted');
+                error.name = 'AbortError';
+                throw error;
+            }
+        };
+        return Promise.resolve().then(() => {
+            checkActive();
+            return typeof tileProvider === 'function' ? tileProvider(url, providerTileIndex) :
+                this.getProviderSource(url)?.getTile(providerTileIndex, controller.signal);
+        }).then(response => {
+            checkActive();
+            debug.network = +new Date() - debug.network;
+            debug.parsing = +new Date();
+            const preprocessedResponse = response != null && typeof this.preprocess === 'function'
+                ? this.preprocess(response)
+                : response;
+            return Promise.resolve(preprocessedResponse).then(processedResponse => {
+                checkActive();
+                if (processedResponse != null) {
+                    this.parseSourceData(dest, sourceData, processedResponse);
+                }
+                else {
+                    sourceData.layers = {};
+                }
+                debug.parsing = +new Date() - debug.parsing;
+                return dest;
+            });
+        }).catch(error => {
+            sourceData.error = error instanceof Error ? error.stack || error.message : String(error);
+            return dest;
+        }).finally(() => {
+            this.providerRequests.delete(controller);
+            updateTileSourceRequest(dest, {cancel: undefined});
+        });
+    }
+
+    parseSourceData (tile?: TileData, source?: SourceData, response?: ArrayBuffer | Uint8Array): void {
+        if (!tile || !source || !response) {
+            throw new Error('MVT source parsing requires a tile, source data and response');
+        }
+        source.layers = parseMvt(this.decoder, response, {parseJson: this.parseJsonOption()});
+
+        // 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)
+            };
+            source.layers = this.transform(source.layers, this.extra_data, tile_data);
+        }
+
+    }
+
+    // Loop through layers/features using Mapbox lib API, convert to GeoJSON features
+    // Returns an object with keys for each layer, e.g. { layer: geojson }
+    toGeoJSON (tile: MvtTile) {
+        return convertMvtTileWithLegacy(tile, {parseJson: this.parseJsonOption()});
+    }
+
+    // Optionally parse some or all feature properties from JSON strings
+    parseJSONProperties (feature: {properties: Record<string, unknown>}): void {
+        parseMvtJsonProperties(feature, this.parseJsonOption());
+    }
+
+    parseJsonOption (): boolean | readonly string[] | undefined {
+        if (this.parse_json_type === PARSE_JSON_TYPE.ALL) {
+            return true;
+        }
+        if (this.parse_json_type === PARSE_JSON_TYPE.SOME) {
+            return this.parse_json_prop_list;
+        }
+        return undefined;
+    }
+}
+
+export {decodeMultiPolygon};
+
+DataSource.register('MVT', () => MVTSource);
+
+registerMvtDecoder('tangram', parseMvtWithLegacy);

package/src/sources/raster.ts

@@ -0,0 +1,341 @@
+// Tangram
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2013-2016 Brett Camper and Mapzen
+// Copyright (c) 2026 vis.gl contributors
+
+import DataSource, {NetworkTileSource} from './data_source';
+import {TileID} from '../tile/tile_id';
+import Geo from '../utils/geo';
+import Texture from '../gl/texture';
+import Utils from '../utils/utils';
+import hashString from '../utils/hash';
+import log from '../utils/log';
+
+type SourceConfig = Record<string, any>;
+type Tile = any;
+type RasterImage = {url: string | null; bounds: any; alpha: number | null};
+
+export class RasterTileSource extends NetworkTileSource {
+
+    filtering: any;
+    textures!: Record<string, any>;
+
+    constructor (source: SourceConfig, sources?: Record<string, unknown>) {
+        super(source, sources);
+
+        if (this.rasters.indexOf(this.name) === -1) {
+            this.rasters.unshift(this.name); // add this raster as the first
+        }
+        this.filtering = source.filtering; // optional texture filtering (nearest, linear, mipmap)
+
+        // save texture objects by tile key, so URL remains stable if tile is built multiple times,
+        // e.g. avoid re-loading the same tile texture under a different subdomain when using tile hosts
+        this.textures = {};
+    }
+
+    async load (tile: Tile): Promise<Tile> {
+        tile.source_data = {};
+        tile.source_data.layers = {};
+        tile.pad_scale = this.pad_scale;
+        tile.rasters = [...this.rasters]; // copy list of rasters to load for tile
+
+        // Generate a single quad that fills the entire tile
+        let scale = Geo.tile_scale;
+        tile.source_data.layers = {
+            _default: {
+                type: 'FeatureCollection',
+                features: [{
+                    geometry: {
+                        type: 'Polygon',
+                        coordinates: [[
+                            [0, 0], [scale, 0],
+                            [scale, -scale], [0, -scale], [0, 0]
+                        ]]
+                    },
+                    properties: {}
+                }]
+            }
+        };
+
+        tile.default_winding = 'CW';
+        return tile;
+    }
+
+    // Return texture info for a raster tile
+    async tileTexture (tile: Tile, _options: {blend?: string; generation?: number} = {}): Promise<any> {
+        let coords = this.adjustRasterTileZoom(tile);
+        let key = coords.key;
+        // texture definitions are cached to avoid loading the same raster tile multiple times,
+        // e.g. due to slightly different URLs when subdomain pattern is used (a.tile.com vs. b.tile.com)
+        if (!this.textures[key]) {
+            let url = this.formatURL(this.url as string, { coords });
+            this.textures[key] = {
+                name: url,
+                url,
+                filtering: this.filtering,
+                coords
+            };
+        }
+        return this.textures[key];
+    }
+
+    // If the raster is attached to another source, we need to compare their levels of zoom detail
+    // to see if any adjustments are needed. Both the `tile_size` and `zoom_offset` data source params
+    // cause the zoom level to be downsampled relative to the "base" zoom level of the map view.
+    // The attaching source has already applied its own zoom downsampling. If this source has a lower
+    // level of detail, we apply the remaining differential here.
+    adjustRasterTileZoom (tile: Tile): any {
+        let coords = tile.coords;
+        const tile_source = this.sources[tile.source];
+        if (tile_source !== this) { // no-op if the raster source isn't being rendered as an attachment
+            let zdiff = this.zoom_bias - tile_source.zoom_bias; // difference in zoom detail between the sources
+            if (zdiff > 0) { // raster source is less detailed
+                // do extra zoom adjustment and apply this raster source's max zoom
+                coords = TileID.normalizedCoord(tile.coords, {
+                    zoom_bias: zdiff,
+                    zooms: this.zooms || []
+                } as any);
+            }
+            else {
+                // raster source supports higher detail, but was downsampled to match (the downsampling already
+                // happened upstream, when the attaching source calculated its own tile coordinate)
+                if (zdiff < 0) {
+                    log({ level: 'warn', once: true},
+                        `Raster source '${this.name}' supports higher zoom detail than source '${tile_source.name}' ` +
+                        `it's attached to. Downsampling this source ${-zdiff} extra zoom levels to match.`
+                    );
+                }
+
+                // no extra zoom adjustment needed, but still need to apply this raster source's max zoom
+                coords = TileID.coordForTileZooms(coords, this.zooms || []);
+            }
+        }
+        return coords;
+    }
+
+}
+
+// Data source for loading standalone, geo-referenced raster images
+// The `bounds` parameter is used to position the raster image on the map
+// Currently, only axis-aligned, rectangular North-up images are supported
+// TODO: add support for arbitrarily rotated images and quadrangle control points
+export class RasterSource extends RasterTileSource {
+
+    load_image!: Record<string, Promise<HTMLImageElement | null>>;
+    alpha: number | null;
+    mask_alpha!: boolean;
+    preserve_tiles_within_zoom!: number;
+    max_display_density?: number;
+    images!: RasterImage[];
+
+    constructor (source: SourceConfig, sources?: Record<string, unknown>) {
+        super(source, sources);
+
+        this.load_image = {}; // resolves to image, cached for life of data source
+
+        // alpha factor applied at time raster images are loaded and tiled (*not* at shader render-time)
+        this.alpha = (source.alpha != null) ? Math.max(Math.min(source.alpha, 1), 0) : null;
+
+        // non-full-alpha pixels should be discarded (for rendering rasters w/opaque blend)
+        this.mask_alpha = true;
+
+        // don't retain tiles for this source from nearby zooms (to improve memory usage)
+        this.preserve_tiles_within_zoom = 0;
+
+        // optionally set a max pixel density used for generated raster tiles (to improve memory usage)
+        this.max_display_density = source.max_display_density;
+
+        // Optionally composite multiple images into one raster layer
+        if (Array.isArray(source.composite)) {
+            // TODO: calculate enclosing bounding box to speed tile intersection checks
+            this.images = source.composite.map((s: SourceConfig) => {
+                return {
+                    url: s.url,
+                    bounds: this.parseBounds(s),
+                    alpha: (s.alpha != null) ? Math.max(Math.min(s.alpha, 1), 0) : null
+                };
+            });
+        }
+        // Single image raster layer
+        else {
+            this.images = [{
+                url: this.url,
+                bounds: this.bounds,
+                alpha: this.alpha
+            }];
+        }
+    }
+
+    // Render the sub-rectangle of the source raster image for the given tile, to a texture.
+    // Clipping the source image to individual raster tiles naturally partitions images
+    // (which may be large or only have a small portion in current view), and maintains
+    // consistency with the raster tile pipeline allowing for sampling within the fragment shader,
+    // and clipping the raster against vector source data.
+    async tileTexture (tile: Tile, options: {blend?: string; generation?: number} = {}): Promise<any> {
+        const {blend, generation} = options;
+        let coords = this.adjustRasterTileZoom(tile);
+        const use_alpha = (blend !== 'opaque'); // ignore source alpha multiplier with opaque blending
+        const name = `raster-${this.name}-${coords.key}-${use_alpha ? 'alpha' : 'opaque'}-${generation}`; // unique texture name
+
+        // only render each raster tile once (per scene generation)
+        if ((Texture as any).textures[name]) {
+            return {
+                name,
+                coords,
+
+                // tell style to skip re-creating this texture
+                // we have an explicit flag for this because element-based (e.g. canvas) textures
+                // are usually considered dynamic and always re-created when a new tile needs them
+                // (because the user could have updated the canvas pixel contents outside of Tangram)
+                skip_create: true
+            };
+        }
+
+        // Display density, with extra 2x for better intra-zoom scaling, because raster tiles
+        // can be scaled up to 100% before next zoom level is loaded
+        let dpr = Utils.device_pixel_ratio || 1;
+        if (this.max_display_density) {
+            dpr = Math.min(dpr, this.max_display_density); // optionally cap pixel density
+        }
+        dpr *= 2;
+
+        const canvas = document.createElement('canvas');
+        const ctx = canvas.getContext('2d');
+        if (!ctx) {
+            throw new Error('Raster source requires a 2D canvas context');
+        }
+        canvas.width = this.tile_size * dpr; // adjusted for display density
+        canvas.height = this.tile_size * dpr;
+
+        // Applies nearest neighbor filtering to the canvas image rendering when data source requests it
+        // NB: does not work on IE11 (image will be blurry when scaled)
+        ctx.imageSmoothingEnabled = (this.filtering !== 'nearest');
+
+        // Draw one or more images
+        const images = this.images.filter((r: RasterImage) => this.checkBounds(tile.coords, r.bounds));
+        await Promise.all(images.map((i: RasterImage) => {
+            // TODO: log warning if alpha specified but will be ignored (in opaque mode)?
+            const alpha = (use_alpha ? (i.alpha != null ? i.alpha : this.alpha) : 1);
+            if (!i.url) {
+                return Promise.resolve();
+            }
+            return this.drawImage(i.url, i.bounds, alpha, tile, dpr, ctx);
+        }));
+
+        // texture config
+        return {
+            name,
+            element: canvas,
+            filtering: this.filtering,
+            coords
+        };
+    }
+
+    // Draw a single image to the tile canvas based on on its bounds
+    async drawImage (
+        url: string,
+        bounds: any,
+        alpha: number | null,
+        tile: Tile,
+        dpr: number,
+        ctx: CanvasRenderingContext2D
+    ): Promise<void> {
+        // Get source raster image
+        const key = hashString(url); // use hash of URL for shorter keys
+        this.load_image[key] = this.load_image[key] || this.loadImage(url);
+        const image = await this.load_image[key];
+
+        // Meters per pixel for this zoom, adjusted for display density and source tile size (e.g. 512px tiles)
+        const mpp = Geo.metersPerPixel(tile.coords.z) / dpr / (this.tile_size / Geo.tile_size);
+
+        // Raster origin relative to tile origin (get delta in meters, then convert to pixels)
+        const dx = (bounds.meters.min[0] - tile.min.x) / mpp;
+        const dy = -(bounds.meters.min[1] - tile.min.y) / mpp;
+
+        // Raster size in pixels for current zoom
+        const sx = (bounds.meters.max[0] - bounds.meters.min[0]) / mpp;
+        const sy = -(bounds.meters.max[1] - bounds.meters.min[1]) / mpp;
+
+        // Draw the raster, clipped to the current tile
+        // NB: this is drawing the *whole* raster, no matter how large, and relying on the native Canvas clipping.
+        // May want to benchmark with a pre-clipped draw area, though the native implementation is likely fast,
+        // and has to apply its own clipping check anyway.
+        ctx.globalAlpha = (alpha != null) ? alpha : 1;
+        if (image) {
+            ctx.drawImage(image, dx, dy, sx, sy);
+        }
+    }
+
+    // Load source raster image
+    loadImage (url: string): Promise<HTMLImageElement | null> {
+        return new Promise(resolve => {
+            let image = new Image();
+            image.onload = () => resolve(image);
+            image.onerror = e => {
+                // Warn and resolve on error
+                log('warn', `Raster source '${this.name}': failed to load url: '${url}'`, e);
+                resolve(null);
+            };
+
+            // Safari has a bug loading data-URL images with CORS enabled, so it must be disabled in that case
+            // https://bugs.webkit.org/show_bug.cgi?id=123978
+            if (!(Utils.isSafari() && url.slice(0, 5) === 'data:')) {
+                image.crossOrigin = 'anonymous';
+            }
+
+            image.src = url;
+        });
+    }
+
+    // Checks if tile interects any rasters in this source
+    includesTile (coords: any, style_z: number): boolean {
+        // Checks zoom range and dependent rasters
+        if (!DataSource.prototype.includesTile.call(this, coords, style_z)) {
+            return false;
+        }
+
+        return this.images.some((r: RasterImage) => this.checkBounds(coords, r.bounds)); // check if any images intersect
+    }
+
+    validate (source: SourceConfig): void {
+        const is_composite = Array.isArray(source.composite);
+
+        let url_msg = 'Raster data source must provide a string `url` parameter, or an array of `composite` raster ';
+        url_msg += 'image objects that each have a `url` parameter';
+
+        let bounds_msg = 'Raster data source must provide a `bounds` parameter, or an array of `composite` raster ';
+        bounds_msg += 'image objects that each have a `bounds` parameter';
+
+        let mutex_msg = 'Raster data source must have *either* a single image specified as `url` and `bounds `';
+        mutex_msg += 'parameters, or an array of `composite` raster image objects, each with `url` and `bounds`.';
+
+        if (is_composite) {
+            if (source.composite.some((s: SourceConfig) => typeof s.url !== 'string')) {
+                throw Error(url_msg);
+            }
+
+            if (source.composite.some((s: SourceConfig) => !(Array.isArray(s.bounds) && s.bounds.length === 4))) {
+                throw Error(bounds_msg);
+            }
+
+            if (source.url != null || source.bounds != null) {
+                throw Error(mutex_msg);
+            }
+        }
+        else {
+            if (typeof source.url !== 'string') {
+                throw Error(url_msg);
+            }
+
+            if (!(Array.isArray(source.bounds) && source.bounds.length === 4)) {
+                throw Error(bounds_msg);
+            }
+        }
+    }
+
+}
+
+// Check for URL tile pattern, if not found, treat as geo-referenced raster layer
+DataSource.register('Raster', (source: SourceConfig) => {
+    return RasterTileSource.urlHasTilePattern(source.url) ? RasterTileSource : RasterSource;
+});