@scoova/mgl 1.0.0

package/src/data/bucket.ts

@@ -0,0 +1,123 @@
+import type {CollisionBoxArray} from './array_types.g';
+import type {Style} from '../style/style';
+import type {TypedStyleLayer} from '../style/style_layer/typed_style_layer';
+import type {FeatureIndex} from './feature_index';
+import type {Context} from '../gl/context';
+import type {FeatureStates} from '../source/source_state';
+import type {ImagePosition} from '../render/image_atlas';
+import type {CanonicalTileID} from '../source/tile_id';
+import type {VectorTileFeature, VectorTileLayer} from '@mapbox/vector-tile';
+import Point from '@mapbox/point-geometry';
+
+export type BucketParameters<Layer extends TypedStyleLayer> = {
+    index: number;
+    layers: Array<Layer>;
+    zoom: number;
+    pixelRatio: number;
+    overscaling: number;
+    collisionBoxArray: CollisionBoxArray;
+    sourceLayerIndex: number;
+    sourceID: string;
+};
+
+export type PopulateParameters = {
+    featureIndex: FeatureIndex;
+    iconDependencies: {};
+    patternDependencies: {};
+    glyphDependencies: {};
+    availableImages: Array<string>;
+};
+
+export type IndexedFeature = {
+    feature: VectorTileFeature;
+    id: number | string;
+    index: number;
+    sourceLayerIndex: number;
+};
+
+export type BucketFeature = {
+    index: number;
+    sourceLayerIndex: number;
+    geometry: Array<Array<Point>>;
+    properties: any;
+    type: 0 | 1 | 2 | 3;
+    id?: any;
+    readonly patterns: {
+        [_: string]: {
+            'min': string;
+            'mid': string;
+            'max': string;
+        };
+    };
+    sortKey?: number;
+};
+
+/**
+ * The `Bucket` interface is the single point of knowledge about turning vector
+ * tiles into WebGL buffers.
+ *
+ * `Bucket` is an abstract interface. An implementation exists for each style layer type.
+ * Create a bucket via the `StyleLayer#createBucket` method.
+ *
+ * The concrete bucket types, using layout options from the style layer,
+ * transform feature geometries into vertex and index data for use by the
+ * vertex shader.  They also (via `ProgramConfiguration`) use feature
+ * properties and the zoom level to populate the attributes needed for
+ * data-driven styling.
+ *
+ * Buckets are designed to be built on a worker thread and then serialized and
+ * transferred back to the main thread for rendering.  On the worker side, a
+ * bucket's vertex, index, and attribute data is stored in `bucket.arrays: ArrayGroup`.
+ * When a bucket's data is serialized and sent back to the main thread,
+ * is gets deserialized (using `new Bucket(serializedBucketData)`, with
+ * the array data now stored in `bucket.buffers: BufferGroup`. BufferGroups
+ * hold the same data as ArrayGroups, but are tuned for consumption by WebGL.
+ */
+export interface Bucket {
+    layerIds: Array<string>;
+    hasPattern: boolean;
+    readonly layers: Array<any>;
+    readonly stateDependentLayers: Array<any>;
+    readonly stateDependentLayerIds: Array<string>;
+    populate(features: Array<IndexedFeature>, options: PopulateParameters, canonical: CanonicalTileID): void;
+    update(states: FeatureStates, vtLayer: VectorTileLayer, imagePositions: {[_: string]: ImagePosition}): void;
+    isEmpty(): boolean;
+    upload(context: Context): void;
+    uploadPending(): boolean;
+    /**
+     * Release the WebGL resources associated with the buffers. Note that because
+     * buckets are shared between layers having the same layout properties, they
+     * must be destroyed in groups (all buckets for a tile, or all symbol buckets).
+     */
+    destroy(): void;
+}
+
+export function deserialize(input: Array<Bucket>, style: Style): {[_: string]: Bucket} {
+    const output = {};
+
+    // Guard against the case where the map's style has been set to null while
+    // this bucket has been parsing.
+    if (!style) return output;
+
+    for (const bucket of input) {
+        const layers = bucket.layerIds
+            .map((id) => style.getLayer(id))
+            .filter(Boolean);
+
+        if (layers.length === 0) {
+            continue;
+        }
+
+        // look up StyleLayer objects from layer ids (since we don't
+        // want to waste time serializing/copying them from the worker)
+        (bucket as any).layers = layers;
+        if (bucket.stateDependentLayerIds) {
+            (bucket as any).stateDependentLayers = bucket.stateDependentLayerIds.map((lId) => layers.filter((l) => l.id === lId)[0]);
+        }
+        for (const layer of layers) {
+            output[layer.id] = bucket;
+        }
+    }
+
+    return output;
+}

package/src/data/dem_data.test.ts

@@ -0,0 +1,237 @@
+import {DEMData} from './dem_data';
+import {RGBAImage} from '../util/image';
+import {serialize, deserialize} from '../util/web_worker_transfer';
+
+function createMockImage(height, width) {
+    // RGBAImage passed to constructor has uniform 1px padding on all sides.
+    height += 2;
+    width += 2;
+    const pixels = new Uint8Array(height * width * 4);
+    for (let i = 0; i < pixels.length; i++) {
+        pixels[i] = (i + 1) % 4 === 0 ? 1 : Math.floor(Math.random() * 256);
+    }
+    return new RGBAImage({height, width}, pixels);
+}
+
+function createMockClampImage(height, width) {
+    const pixels = new Uint8ClampedArray(height * width * 4);
+    for (let i = 0; i < pixels.length; i++) {
+        pixels[i] = (i + 1) % 4 === 0 ? 1 : Math.floor(Math.random() * 256);
+    }
+    return new RGBAImage({height, width}, pixels);
+}
+
+describe('DEMData', () => {
+    describe('constructor', () => {
+        test('Uint8Array', () => {
+            const imageData0 = createMockImage(4, 4);
+            const dem = new DEMData('0', imageData0, 'mapbox');
+            expect(dem.uid).toBe('0');
+            expect(dem.dim).toBe(4);
+            expect(dem.stride).toBe(6);
+        });
+
+        test('Uint8ClampedArray', () => {
+            const imageData0 = createMockClampImage(4, 4);
+            const dem = new DEMData('0', imageData0, 'mapbox');
+            expect(dem).not.toBeNull();
+            expect(dem['uid']).toBe('0');
+            expect(dem['dim']).toBe(2);
+            expect(dem['stride']).toBe(4);
+        });
+
+        test('otherEncoding', () => {
+            const spyOnWarnConsole = jest.spyOn(console, 'warn').mockImplementation();
+
+            const imageData0 = createMockImage(4, 4);
+            new DEMData('0', imageData0, 'otherEncoding' as any);
+
+            expect(spyOnWarnConsole).toHaveBeenCalledTimes(1);
+            expect(spyOnWarnConsole.mock.calls).toEqual([['\"otherEncoding\" is not a valid encoding type. Valid types include \"mapbox\", \"terrarium\" and \"custom\".']]);
+        });
+    });
+});
+
+function testDEMBorderRegion(dem: DEMData) {
+    return () => {
+        let nonempty = true;
+        for (let x = -1; x < 5; x++) {
+            for (let y = -1; y < 5; y++) {
+                if (dem.get(x, y) === -65536) {
+                    nonempty = false;
+                    break;
+                }
+            }
+        }
+        expect(nonempty).toBeTruthy();
+
+        let verticalBorderMatch = true;
+        for (const x of [-1, 4]) {
+            for (let y = 0; y < 4; y++) {
+                if (dem.get(x, y) !== dem.get(x < 0 ? x + 1 : x - 1, y)) {
+                    verticalBorderMatch = false;
+                    break;
+                }
+            }
+        }
+        expect(verticalBorderMatch).toBeTruthy();
+
+        // horizontal borders empty
+        let horizontalBorderMatch = true;
+        for (const y of [-1, 4]) {
+            for (let x = 0; x < 4; x++) {
+                if (dem.get(x, y) !== dem.get(x, y < 0 ? y + 1 : y - 1)) {
+                    horizontalBorderMatch = false;
+                    break;
+                }
+            }
+        }
+        expect(horizontalBorderMatch).toBeTruthy();
+
+        expect(dem.get(-1, 4) === dem.get(0, 3)).toBeTruthy();
+        expect(dem.get(4, 4) === dem.get(3, 3)).toBeTruthy();
+        expect(dem.get(-1, -1) === dem.get(0, 0)).toBeTruthy();
+        expect(dem.get(4, -1) === dem.get(3, 0)).toBeTruthy();
+    };
+}
+
+function testDEMBackfill(dem0: DEMData, dem1: DEMData) {
+    return  () => {
+        dem0.backfillBorder(dem1, -1, 0);
+        for (let y = 0; y < 4; y++) {
+            // dx = -1, dy = 0, so the left edge of dem1 should equal the right edge of dem0
+            expect(dem0.get(-1, y) === dem1.get(3, y)).toBeTruthy();
+        }
+
+        dem0.backfillBorder(dem1, 0, -1);
+        for (let x = 0; x < 4; x++) {
+            expect(dem0.get(x, -1) === dem1.get(x, 3)).toBeTruthy();
+        }
+
+        dem0.backfillBorder(dem1, 1, 0);
+        for (let y = 0; y < 4; y++) {
+            expect(dem0.get(4, y) === dem1.get(0, y)).toBeTruthy();
+        }
+
+        dem0.backfillBorder(dem1, 0, 1);
+        for (let x = 0; x < 4; x++) {
+            expect(dem0.get(x, 4) === dem1.get(x, 0)).toBeTruthy();
+        }
+
+        dem0.backfillBorder(dem1, -1, 1);
+        expect(dem0.get(-1, 4) === dem1.get(3, 0)).toBeTruthy();
+
+        dem0.backfillBorder(dem1, 1, 1);
+        expect(dem0.get(4, 4) === dem1.get(0, 0)).toBeTruthy();
+
+        dem0.backfillBorder(dem1, -1, -1);
+        expect(dem0.get(-1, -1) === dem1.get(3, 3)).toBeTruthy();
+
+        dem0.backfillBorder(dem1, 1, -1);
+        expect(dem0.get(4, -1) === dem1.get(0, 3)).toBeTruthy();
+    };
+}
+
+describe('DEMData#backfillBorder with encoding', () => {
+    describe('mapbox encoding', () => {
+        const dem0 = new DEMData('0', createMockImage(4, 4), 'mapbox');
+        const dem1 = new DEMData('1', createMockImage(4, 4), 'mapbox');
+
+        test('border region is initially populated with neighboring data', testDEMBorderRegion(dem0));
+        test('backfillBorder correctly populates borders with neighboring data', testDEMBackfill(dem0, dem1));
+    });
+
+    describe('terrarium encoding', () => {
+        const dem0 = new DEMData('0', createMockImage(4, 4), 'terrarium');
+        const dem1 = new DEMData('1', createMockImage(4, 4), 'terrarium');
+
+        test('border region is initially populated with neighboring data', testDEMBorderRegion(dem0));
+        test('backfillBorder correctly populates borders with neighboring data', testDEMBackfill(dem0, dem1));
+    });
+});
+
+function testSerialization(dem0: DEMData, redFactor: number, greenFactor: number, blueFactor: number, baseShift: number) {
+    return () => {
+        const serialized = serialize(dem0);
+
+        // calculate min/max values
+        let min = Number.MAX_SAFE_INTEGER;
+        let max = Number.MIN_SAFE_INTEGER;
+        for (let x = 0; x < 4; x++) {
+            for (let y = 0; y < 4; y++) {
+                const ele = dem0.get(x, y);
+                if (ele > max) max = ele;
+                if (ele < min) min = ele;
+            }
+        }
+
+        expect(serialized).toEqual({
+            $name: 'DEMData',
+            uid: '0',
+            dim: 4,
+            stride: 6,
+            data: dem0.data,
+            redFactor,
+            greenFactor,
+            blueFactor,
+            baseShift,
+            max,
+            min,
+        });
+
+        const transferrables = [];
+        serialize(dem0, transferrables);
+        expect(new Uint32Array(transferrables[0])).toEqual(dem0.data);
+    };
+}
+
+function testDeserialization(dem0: DEMData) {
+    return () => {
+        const serialized = serialize(dem0);
+
+        const deserialized = deserialize(serialized);
+        expect(deserialized).toEqual(dem0);
+    };
+}
+
+describe('DEMData is correctly serialized and deserialized', () => {
+    const mapboxDEM = new DEMData('0', createMockImage(4, 4), 'mapbox');
+    const terrariumDEM = new DEMData('0', createMockImage(4, 4), 'terrarium');
+    const customDEM = new DEMData('0', createMockImage(4, 4), 'custom', 1.0, 2.0, 3.0, 4.0);
+    test('serialized - mapbox', testSerialization(mapboxDEM, 6553.6, 25.6, 0.1, 10000));
+    test('serialized - terrarium', testSerialization(terrariumDEM, 256.0, 1.0, 1.0 / 256.0, 32768.0));
+    test('serialized - custom', testSerialization(customDEM, 1.0, 2.0, 3.0, 4.0));
+
+    test('deserialized - mapbox', testDeserialization(mapboxDEM));
+    test('deserialized - terrarium', testDeserialization(terrariumDEM));
+    test('deserialized - custom', testDeserialization(customDEM));
+});
+
+describe('UnpackVector is correctly returned', () => {
+    test('terrarium, mapbox and custom', () => {
+        const mapboxDEM = new DEMData('0', createMockImage(4, 4), 'mapbox');
+        const terrariumDEM = new DEMData('0', createMockImage(4, 4), 'terrarium');
+        const customDEM = new DEMData('0', createMockImage(4, 4), 'custom', 1.0, 2.0, 3.0, 4.0);
+
+        expect(terrariumDEM.getUnpackVector()).toEqual([256.0, 1.0, 1.0 / 256.0, 32768.0]);
+        expect(mapboxDEM.getUnpackVector()).toEqual([6553.6, 25.6, 0.1, 10000.0]);
+        expect(customDEM.getUnpackVector()).toEqual([1.0, 2.0, 3.0, 4.0]);
+    });
+});
+
+function testGetPixels(dem: DEMData, imageData: RGBAImage) {
+    return () => {
+        expect(dem.getPixels()).toEqual(imageData);
+    };
+}
+
+describe('DEMData#getImage', () => {
+    const imageData = createMockImage(4, 4);
+    const mapboxDEM = new DEMData('0', imageData, 'terrarium');
+    const terrariumDEM = new DEMData('0', imageData, 'terrarium');
+    const customDEM = new DEMData('0', imageData, 'terrarium');
+
+    test('Image is correctly returned - mapbox', testGetPixels(mapboxDEM, imageData));
+    test('Image is correctly returned - terrarium', testGetPixels(terrariumDEM, imageData));
+    test('Image is correctly returned - custom', testGetPixels(customDEM, imageData));
+});

package/src/data/dem_data.ts

@@ -0,0 +1,171 @@
+import {RGBAImage} from '../util/image';
+
+import {warnOnce} from '../util/util';
+import {register} from '../util/web_worker_transfer';
+
+/**
+ * The possible DEM encoding types
+ */
+export type DEMEncoding = 'mapbox' | 'terrarium' | 'custom'
+
+/**
+ * DEMData is a data structure for decoding, backfilling, and storing elevation data for processing in the hillshade shaders
+ * data can be populated either from a pngraw image tile or from serialized data sent back from a worker. When data is initially
+ * loaded from a image tile, we decode the pixel values using the appropriate decoding formula, but we store the
+ * elevation data as an Int32 value. we add 65536 (2^16) to eliminate negative values and enable the use of
+ * integer overflow when creating the texture used in the hillshadePrepare step.
+ *
+ * DEMData also handles the backfilling of data from a tile's neighboring tiles. This is necessary because we use a pixel's 8
+ * surrounding pixel values to compute the slope at that pixel, and we cannot accurately calculate the slope at pixels on a
+ * tile's edge without backfilling from neighboring tiles.
+ */
+export class DEMData {
+    uid: string | number;
+    data: Uint32Array;
+    stride: number;
+    dim: number;
+    min: number;
+    max: number;
+    redFactor: number;
+    greenFactor: number;
+    blueFactor: number;
+    baseShift: number;
+
+    /**
+     * Constructs a `DEMData` object
+     * @param uid - the tile's unique id
+     * @param data - RGBAImage data has uniform 1px padding on all sides: square tile edge size defines stride
+    // and dim is calculated as stride - 2.
+     * @param encoding - the encoding type of the data
+     * @param redFactor - the red channel factor used to unpack the data, used for `custom` encoding only
+     * @param greenFactor - the green channel factor used to unpack the data, used for `custom` encoding only
+     * @param blueFactor - the blue channel factor used to unpack the data, used for `custom` encoding only
+     * @param baseShift - the base shift used to unpack the data, used for `custom` encoding only
+     */
+    constructor(uid: string | number, data: RGBAImage | ImageData, encoding: DEMEncoding, redFactor = 1.0, greenFactor = 1.0, blueFactor = 1.0, baseShift = 0.0) {
+        this.uid = uid;
+        if (data.height !== data.width) throw new RangeError('DEM tiles must be square');
+        if (encoding && !['mapbox', 'terrarium', 'custom'].includes(encoding)) {
+            warnOnce(`"${encoding}" is not a valid encoding type. Valid types include "mapbox", "terrarium" and "custom".`);
+            return;
+        }
+        this.stride = data.height;
+        const dim = this.dim = data.height - 2;
+        this.data = new Uint32Array(data.data.buffer);
+        switch (encoding) {
+            case 'terrarium':
+                // unpacking formula for mapzen terrarium:
+                // https://aws.amazon.com/public-datasets/terrain/
+                this.redFactor = 256.0;
+                this.greenFactor = 1.0;
+                this.blueFactor = 1.0 / 256.0;
+                this.baseShift = 32768.0;
+                break;
+            case 'custom':
+                this.redFactor = redFactor;
+                this.greenFactor = greenFactor;
+                this.blueFactor = blueFactor;
+                this.baseShift = baseShift;
+                break;
+            case 'mapbox':
+            default:
+                // unpacking formula for mapbox.terrain-rgb:
+                // https://www.mapbox.com/help/access-elevation-data/#mapbox-terrain-rgb
+                this.redFactor = 6553.6;
+                this.greenFactor = 25.6;
+                this.blueFactor = 0.1;
+                this.baseShift = 10000.0;
+                break;
+        }
+
+        // in order to avoid flashing seams between tiles, here we are initially populating a 1px border of pixels around the image
+        // with the data of the nearest pixel from the image. this data is eventually replaced when the tile's neighboring
+        // tiles are loaded and the accurate data can be backfilled using DEMData#backfillBorder
+        for (let x = 0; x < dim; x++) {
+            // left vertical border
+            this.data[this._idx(-1, x)] = this.data[this._idx(0, x)];
+            // right vertical border
+            this.data[this._idx(dim, x)] = this.data[this._idx(dim - 1, x)];
+            // left horizontal border
+            this.data[this._idx(x, -1)] = this.data[this._idx(x, 0)];
+            // right horizontal border
+            this.data[this._idx(x, dim)] = this.data[this._idx(x, dim - 1)];
+        }
+        // corners
+        this.data[this._idx(-1, -1)] = this.data[this._idx(0, 0)];
+        this.data[this._idx(dim, -1)] = this.data[this._idx(dim - 1, 0)];
+        this.data[this._idx(-1, dim)] = this.data[this._idx(0, dim - 1)];
+        this.data[this._idx(dim, dim)] = this.data[this._idx(dim - 1, dim - 1)];
+
+        // calculate min/max values
+        this.min = Number.MAX_SAFE_INTEGER;
+        this.max = Number.MIN_SAFE_INTEGER;
+        for (let x = 0; x < dim; x++) {
+            for (let y = 0; y < dim; y++) {
+                const ele = this.get(x, y);
+                if (ele > this.max) this.max = ele;
+                if (ele < this.min) this.min = ele;
+            }
+        }
+    }
+
+    get(x: number, y: number) {
+        const pixels = new Uint8Array(this.data.buffer);
+        const index = this._idx(x, y) * 4;
+        return this.unpack(pixels[index], pixels[index + 1], pixels[index + 2]);
+    }
+
+    getUnpackVector() {
+        return [this.redFactor, this.greenFactor, this.blueFactor, this.baseShift];
+    }
+
+    _idx(x: number, y: number) {
+        if (x < -1 || x >= this.dim + 1 ||  y < -1 || y >= this.dim + 1) throw new RangeError('out of range source coordinates for DEM data');
+        return (y + 1) * this.stride + (x + 1);
+    }
+
+    unpack(r: number, g: number, b: number) {
+        return (r * this.redFactor + g * this.greenFactor + b * this.blueFactor - this.baseShift);
+    }
+
+    getPixels() {
+        return new RGBAImage({width: this.stride, height: this.stride}, new Uint8Array(this.data.buffer));
+    }
+
+    backfillBorder(borderTile: DEMData, dx: number, dy: number) {
+        if (this.dim !== borderTile.dim) throw new Error('dem dimension mismatch');
+
+        let xMin = dx * this.dim,
+            xMax = dx * this.dim + this.dim,
+            yMin = dy * this.dim,
+            yMax = dy * this.dim + this.dim;
+
+        switch (dx) {
+            case -1:
+                xMin = xMax - 1;
+                break;
+            case 1:
+                xMax = xMin + 1;
+                break;
+        }
+
+        switch (dy) {
+            case -1:
+                yMin = yMax - 1;
+                break;
+            case 1:
+                yMax = yMin + 1;
+                break;
+        }
+
+        const ox = -dx * this.dim;
+        const oy = -dy * this.dim;
+        for (let y = yMin; y < yMax; y++) {
+            for (let x = xMin; x < xMax; x++) {
+                this.data[this._idx(x, y)] = borderTile.data[this._idx(x + ox, y + oy)];
+            }
+        }
+    }
+}
+
+register('DEMData', DEMData);

package/src/data/evaluation_feature.ts

@@ -0,0 +1,18 @@
+import {loadGeometry} from './load_geometry';
+import type Point from '@mapbox/point-geometry';
+import type {VectorTileFeature} from '@mapbox/vector-tile';
+import type {Feature} from '@maplibre/maplibre-gl-style-spec';
+
+type EvaluationFeature = Feature & { geometry: Array<Array<Point>> };
+/**
+ * Construct a new feature based on a VectorTileFeature for expression evaluation, the geometry of which
+ * will be loaded based on necessity.
+ * @param feature - the feature to evaluate
+ * @param needGeometry - if set to true this will load the geometry
+ */
+export function toEvaluationFeature(feature: VectorTileFeature, needGeometry: boolean): EvaluationFeature {
+    return {type: feature.type,
+        id: feature.id,
+        properties: feature.properties,
+        geometry: needGeometry ? loadGeometry(feature) : []};
+}

package/src/data/extent.ts

@@ -0,0 +1,13 @@
+/**
+ * The maximum value of a coordinate in the internal tile coordinate system. Coordinates of
+ * all source features normalized to this extent upon load.
+ *
+ * The value is a consequence of the following:
+ *
+ * * Vertex buffer store positions as signed 16 bit integers.
+ * * One bit is lost for signedness to support tile buffers.
+ * * One bit is lost because the line vertex buffer used to pack 1 bit of other data into the int.
+ * * One bit is lost to support features extending past the extent on the right edge of the tile.
+ * * This leaves us with 2^13 = 8192
+ */
+export const EXTENT = 8192;