MapComplete/Logic/FeatureSource/TiledFeatureSource/TiledFeatureSource.ts

import FeatureSource, { FeatureSourceForLayer, IndexedFeatureSource, Tiled } from "../FeatureSource"
import { Store, UIEventSource } from "../../UIEventSource"
import FilteredLayer from "../../../Models/FilteredLayer"
import TileHierarchy from "./TileHierarchy"
import { Tiles } from "../../../Models/TileRange"
import { BBox } from "../../BBox"

/**
 * Contains all features in a tiled fashion.
 * The data will be automatically broken down into subtiles when there are too much features in a single tile or if the zoomlevel is too high
 */
export default class TiledFeatureSource
    implements
        Tiled,
        IndexedFeatureSource,
        FeatureSourceForLayer,
        TileHierarchy<IndexedFeatureSource & FeatureSourceForLayer & Tiled>
{
    public readonly z: number
    public readonly x: number
    public readonly y: number
    public readonly parent: TiledFeatureSource
    public readonly root: TiledFeatureSource
    public readonly layer: FilteredLayer
    /* An index of all known tiles. allTiles[z][x][y].get('layerid') will yield the corresponding tile.
     * Only defined on the root element!
     */
    public readonly loadedTiles: Map<number, TiledFeatureSource & FeatureSourceForLayer> = undefined

    public readonly maxFeatureCount: number
    public readonly name
    public readonly features: UIEventSource<{ feature: any; freshness: Date }[]>
    public readonly containedIds: Store<Set<string>>

    public readonly bbox: BBox
    public readonly tileIndex: number
    private upper_left: TiledFeatureSource
    private upper_right: TiledFeatureSource
    private lower_left: TiledFeatureSource
    private lower_right: TiledFeatureSource
    private readonly maxzoom: number
    private readonly options: TiledFeatureSourceOptions

    private constructor(
        z: number,
        x: number,
        y: number,
        parent: TiledFeatureSource,
        options?: TiledFeatureSourceOptions
    ) {
        this.z = z
        this.x = x
        this.y = y
        this.bbox = BBox.fromTile(z, x, y)
        this.tileIndex = Tiles.tile_index(z, x, y)
        this.name = `TiledFeatureSource(${z},${x},${y})`
        this.parent = parent
        this.layer = options.layer
        options = options ?? {}
        this.maxFeatureCount = options?.maxFeatureCount ?? 250
        this.maxzoom = options.maxZoomLevel ?? 18
        this.options = options
        if (parent === undefined) {
            throw "Parent is not allowed to be undefined. Use null instead"
        }
        if (parent === null && z !== 0 && x !== 0 && y !== 0) {
            throw "Invalid root tile: z, x and y should all be null"
        }
        if (parent === null) {
            this.root = this
            this.loadedTiles = new Map()
        } else {
            this.root = this.parent.root
            this.loadedTiles = this.root.loadedTiles
            const i = Tiles.tile_index(z, x, y)
            this.root.loadedTiles.set(i, this)
        }
        this.features = new UIEventSource<any[]>([])
        this.containedIds = this.features.map((features) => {
            if (features === undefined) {
                return undefined
            }
            return new Set(features.map((f) => f.feature.properties.id))
        })

        // We register this tile, but only when there is some data in it
        if (this.options.registerTile !== undefined) {
            this.features.addCallbackAndRunD((features) => {
                if (features.length === 0) {
                    return
                }
                this.options.registerTile(this)
                return true
            })
        }
    }

    public static createHierarchy(
        features: FeatureSource,
        options?: TiledFeatureSourceOptions
    ): TiledFeatureSource {
        options = {
            ...options,
            layer: features["layer"] ?? options.layer,
        }
        const root = new TiledFeatureSource(0, 0, 0, null, options)
        features.features?.addCallbackAndRunD((feats) => root.addFeatures(feats))
        return root
    }

    private isSplitNeeded(featureCount: number) {
        if (this.upper_left !== undefined) {
            // This tile has been split previously, so we keep on splitting
            return true
        }
        if (this.z >= this.maxzoom) {
            // We are not allowed to split any further
            return false
        }
        if (this.options.minZoomLevel !== undefined && this.z < this.options.minZoomLevel) {
            // We must have at least this zoom level before we are allowed to start splitting
            return true
        }

        // To much features - we split
        return featureCount > this.maxFeatureCount
    }

    /***
     * Adds the list of features to this hierarchy.
     * If there are too much features, the list will be broken down and distributed over the subtiles (only retaining features that don't fit a subtile on this level)
     * @param features
     * @private
     */
    private addFeatures(features: { feature: any; freshness: Date }[]) {
        if (features === undefined || features.length === 0) {
            return
        }

        if (!this.isSplitNeeded(features.length)) {
            this.features.setData(features)
            return
        }

        if (this.upper_left === undefined) {
            this.upper_left = new TiledFeatureSource(
                this.z + 1,
                this.x * 2,
                this.y * 2,
                this,
                this.options
            )
            this.upper_right = new TiledFeatureSource(
                this.z + 1,
                this.x * 2 + 1,
                this.y * 2,
                this,
                this.options
            )
            this.lower_left = new TiledFeatureSource(
                this.z + 1,
                this.x * 2,
                this.y * 2 + 1,
                this,
                this.options
            )
            this.lower_right = new TiledFeatureSource(
                this.z + 1,
                this.x * 2 + 1,
                this.y * 2 + 1,
                this,
                this.options
            )
        }

        const ulf = []
        const urf = []
        const llf = []
        const lrf = []
        const overlapsboundary = []

        for (const feature of features) {
            const bbox = BBox.get(feature.feature)

            // There are a few strategies to deal with features that cross tile boundaries

            if (this.options.noDuplicates) {
                // Strategy 1: We put the feature into a somewhat matching tile
                if (bbox.overlapsWith(this.upper_left.bbox)) {
                    ulf.push(feature)
                } else if (bbox.overlapsWith(this.upper_right.bbox)) {
                    urf.push(feature)
                } else if (bbox.overlapsWith(this.lower_left.bbox)) {
                    llf.push(feature)
                } else if (bbox.overlapsWith(this.lower_right.bbox)) {
                    lrf.push(feature)
                } else {
                    overlapsboundary.push(feature)
                }
            } else if (this.options.minZoomLevel === undefined) {
                // Strategy 2: put it into a strictly matching tile (or in this tile, which is slightly too big)
                if (bbox.isContainedIn(this.upper_left.bbox)) {
                    ulf.push(feature)
                } else if (bbox.isContainedIn(this.upper_right.bbox)) {
                    urf.push(feature)
                } else if (bbox.isContainedIn(this.lower_left.bbox)) {
                    llf.push(feature)
                } else if (bbox.isContainedIn(this.lower_right.bbox)) {
                    lrf.push(feature)
                } else {
                    overlapsboundary.push(feature)
                }
            } else {
                // Strategy 3: We duplicate a feature on a boundary into every tile as we need to get to the minZoomLevel
                if (bbox.overlapsWith(this.upper_left.bbox)) {
                    ulf.push(feature)
                }
                if (bbox.overlapsWith(this.upper_right.bbox)) {
                    urf.push(feature)
                }
                if (bbox.overlapsWith(this.lower_left.bbox)) {
                    llf.push(feature)
                }
                if (bbox.overlapsWith(this.lower_right.bbox)) {
                    lrf.push(feature)
                }
            }
        }
        this.upper_left.addFeatures(ulf)
        this.upper_right.addFeatures(urf)
        this.lower_left.addFeatures(llf)
        this.lower_right.addFeatures(lrf)
        this.features.setData(overlapsboundary)
    }
}

export interface TiledFeatureSourceOptions {
    readonly maxFeatureCount?: number
    readonly maxZoomLevel?: number
    readonly minZoomLevel?: number
    /**
     * IF minZoomLevel is set, and if a feature runs through a tile boundary, it would normally be duplicated.
     * Setting 'dontEnforceMinZoomLevel' will assign to feature to some matching subtile.
     */
    readonly noDuplicates?: boolean
    readonly registerTile?: (tile: TiledFeatureSource & FeatureSourceForLayer & Tiled) => void
    readonly layer?: FilteredLayer
}