@react-x11/components 0.3.0 → 0.5.0

package/dist/maps/mvt.d.ts

@@ -0,0 +1,244 @@
+/** What a feature's geometry is. The numbers are the specification's. */
+export declare const enum GeomType {
+    Unknown = 0,
+    Point = 1,
+    LineString = 2,
+    Polygon = 3
+}
+/** A tag value. MVT's seven value types collapse to these three in
+ *  JavaScript; which of the four numeric ones it was is not information a
+ *  style can use. */
+export type FeatureValue = string | number | boolean;
+/**
+ * Decoded geometry, as flat typed arrays.
+ *
+ * `coords` is `[x0, y0, x1, y1, …]` in **tile-local integers** — the space
+ * `extent` divides, not pixels and not degrees. `starts` indexes it in
+ * *points*: part `i` covers `coords[2 * starts[i] .. 2 * starts[i + 1])`,
+ * and `starts` has `parts + 1` entries so the last part needs no special
+ * case.
+ *
+ * `areas[i]` is part `i`'s signed area by the surveyor's formula, and is
+ * meaningful for {@link GeomType.Polygon} only: positive is an exterior
+ * ring, negative an interior one. It is filled during the same pass that
+ * reads the vertices, because a second pass over 4,000 points to learn one
+ * sign is the sort of thing that turns a 6 ms tile into an 11 ms one.
+ */
+export interface GeometryData {
+    coords: Int32Array;
+    starts: Uint32Array;
+    areas: Float64Array;
+    parts: number;
+    points: number;
+}
+/**
+ * A growable {@link GeometryData} a caller keeps between features.
+ *
+ * The rasterizer allocates one of these per tile — or per element, since it
+ * is only scratch — and every feature reads into it. Capacity ratchets up
+ * to the largest feature seen and then stops moving, which for a tile means
+ * two or three grows in total rather than two per feature.
+ */
+export declare class GeometryBuffer implements GeometryData {
+    coords: Int32Array;
+    starts: Uint32Array;
+    areas: Float64Array;
+    parts: number;
+    points: number;
+    constructor(points?: number, parts?: number);
+    /** Room for `points` vertices, keeping what is already written. */
+    reserveCoords(points: number): void;
+    /**
+     * Per-part bounding boxes, four numbers each: `minX, minY, maxX, maxY`.
+     *
+     * The feature-wide box is not enough, and the case that proves it is the
+     * one that dominates a low-zoom frame: OSM's `land` layer at zoom 8 is a
+     * **single feature** whose geometry is thousands of separate rings, most
+     * of them a fraction of a pixel across. Culled as one feature it is never
+     * culled; culled per part, almost all of it goes.
+     */
+    partBounds: Float64Array;
+    /** Room for `parts` parts, keeping what is already written. */
+    reserveParts(parts: number): void;
+    /** The bounding box of everything written, in tile-local integers.
+     *  Free here — the read already touches every vertex — and what lets a
+     *  painter skip a building that is a third of a pixel across, which at a
+     *  country-wide zoom is most of what a tile contains. */
+    minX: number;
+    minY: number;
+    maxX: number;
+    maxY: number;
+    reset(): void;
+}
+/** A malformed tile. Thrown rather than tolerated: a truncated protobuf is
+ *  a transport bug, and silently rendering the half of a tile that parsed
+ *  is how a map ends up missing a river nobody can explain. */
+export declare class MvtError extends Error {
+    constructor(message: string);
+}
+declare class Reader {
+    buf: Uint8Array;
+    pos: number;
+    end: number;
+    constructor(buf: Uint8Array, pos?: number, end?: number);
+    /**
+     * A varint, as a JavaScript number.
+     *
+     * Unrolled to seven bytes — 2^49, which covers every field MVT puts in a
+     * varint except a feature `id` that used the full 64 bits. Past that the
+     * slow path accumulates in floating point and loses the low bits above
+     * 2^53; the alternative is a BigInt per id, which costs every tile
+     * something to be exact about a case that does not occur in tiles cut
+     * from OSM (whose largest ids are ~2^33).
+     */
+    varint(): number;
+    /** A zigzag-encoded signed varint. */
+    svarint(): number;
+    skip(wire: number): void;
+    /** One view over the whole buffer rather than one per read: only a
+     *  layer's `values` use these, but a dense tile has thousands of them. */
+    private _view;
+    private view;
+    float(): number;
+    double(): number;
+    string(): string;
+}
+/** A decoded tile: its layers, by name. Layers are ordered as the tile
+ *  ordered them, which is the order a producer means them to be drawn in
+ *  when a style says nothing. */
+export interface VectorTile {
+    layers: Map<string, VectorTileLayer>;
+    /** Layer names in tile order. */
+    order: string[];
+}
+/**
+ * One layer of a tile.
+ *
+ * `keys` and `values` are decoded eagerly because MVT **deduplicates**
+ * them — a tile with 12,000 features has perhaps 40 keys and 2,000 distinct
+ * values, so decoding them once is cheaper than decoding a feature's tags
+ * lazily would be. Features are the other way round: their byte ranges are
+ * collected on construction and nothing inside one is touched until it is
+ * asked for.
+ */
+export declare class VectorTileLayer {
+    readonly name: string;
+    readonly version: number;
+    /** Tile-local coordinate units across the tile's square. 4096 unless the
+     *  producer said otherwise. */
+    readonly extent: number;
+    readonly keys: string[];
+    readonly values: FeatureValue[];
+    /** How many features. */
+    readonly length: number;
+    private readonly _buf;
+    /** Byte offset of feature `i`, with a sentinel: `[starts[i], starts[i+1])`
+     *  is not a valid span (features are not contiguous), so both ends are
+     *  stored. */
+    private readonly _at;
+    private readonly _to;
+    private _keyIndex;
+    constructor(reader: Reader, end: number);
+    /** Which tag index a key name has, or -1. Built on first use, because a
+     *  style usually reads two or three of a layer's forty keys. */
+    keyIndex(key: string): number;
+    /** Feature `i`, as a fresh cursor. */
+    feature(i: number): FeatureCursor;
+    /**
+     * Point an existing cursor at feature `i`.
+     *
+     * The whole reason the cursor is a separate object: a rasterizer walks
+     * twelve thousand features and wants none of them to be an allocation.
+     */
+    seek(i: number, cursor: FeatureCursor): FeatureCursor;
+    /** Every feature, as fresh cursors. Convenience — the allocation-free
+     *  path is {@link seek}. */
+    features(): Generator<FeatureCursor>;
+}
+/** A position on a cursor's feature. */
+export interface TilePoint {
+    x: number;
+    y: number;
+}
+/**
+ * One feature, as a movable cursor over the tile's bytes.
+ *
+ * Nothing inside the feature is decoded until it is asked for, and a
+ * cursor's own state is four numbers, so `layer.seek(i, cursor)` in a loop
+ * allocates nothing.
+ */
+export declare class FeatureCursor {
+    /** The feature's `id`, or undefined when it carries none. Ids above 2^53
+     *  lose their low bits — see {@link Reader.varint}. */
+    id: number | undefined;
+    type: GeomType;
+    layer: VectorTileLayer | null;
+    private _buf;
+    private _tagAt;
+    private _tagTo;
+    private _geomAt;
+    private _geomTo;
+    /**
+     * The feature's tags as key/value **indices**, decoded on the first
+     * {@link get} and reused for every one after it.
+     *
+     * The reason this exists rather than a scan of the bytes per call: a
+     * style asks the same feature about the same two or three keys once per
+     * style layer over that source layer, and a road network is fourteen
+     * such layers (seven classes, a casing pass and a fill pass). Re-decoding
+     * a feature's varints fourteen times over is, on the corpus, most of the
+     * cost of a zoom-12 tile. Decoded once, a lookup is a scan over a dozen
+     * integers.
+     */
+    private _tagKeys;
+    private _tagValues;
+    private _tagCount;
+    /** @internal */
+    _bind(layer: VectorTileLayer, buf: Uint8Array, at: number, to: number): void;
+    /** Tile-local units across this feature's tile. */
+    get extent(): number;
+    /**
+     * One tag, by key name.
+     *
+     * A linear scan of the tag pairs rather than a materialized object: a
+     * feature has five to fifteen tags and a style filter reads one or two of
+     * them, so the scan is quicker than the object it would have built and
+     * costs nothing to throw away.
+     */
+    get(key: string): FeatureValue | undefined;
+    /** Decode the tag pairs into the cursor's own arrays. Grown, never
+     *  shrunk, so a cursor walking a layer settles on one allocation. */
+    private _loadTags;
+    has(key: string): boolean;
+    /** Every tag, as an object. For a hover readout or a click payload — not
+     *  for a filter, which should use {@link get}. */
+    properties(): Record<string, FeatureValue>;
+    /**
+     * Read this feature's geometry into `into`, in tile-local integers.
+     *
+     * The one hot loop in the decoder. Everything about its shape is about
+     * not allocating: the cursor deltas accumulate in two locals, the
+     * vertices go into a typed array the caller owns, and a polygon's ring
+     * areas and the whole feature's bounding box are accumulated in the same
+     * pass rather than in two more over the same points.
+     */
+    readGeometry(into: GeometryBuffer): GeometryData;
+    /** Geometry as arrays of its own — the convenience form. */
+    geometry(): GeometryData;
+}
+/**
+ * Decode a tile.
+ *
+ * Cheap: it walks the tile's top-level fields and each layer's, which is
+ * the layer names, their key and value tables, and one byte range per
+ * feature. No geometry is touched, so a style that draws four of a tile's
+ * fourteen layers pays for four.
+ *
+ * The bytes must be the raw protobuf. Tiles are almost always served
+ * `Content-Encoding: gzip` and sometimes gzipped *inside* that, which is a
+ * transport concern and deliberately not this function's — a source adapter
+ * un-gzips (`src/maps/sources.ts` does).
+ */
+export declare function parseTile(bytes: Uint8Array): VectorTile;
+export {};
+//# sourceMappingURL=mvt.d.ts.map

package/dist/maps/mvt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mvt.d.ts","sourceRoot":"","sources":["../../src/maps/mvt.ts"],"names":[],"mappings":"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"}