mvt

    Mapbox Vector Tile decoder in MoonBit, reading tiles as @mapbox/vector-tile does

    mvt
    vector-tile
    mapbox
    gis
    decoder
    Download zip
    Author
    Version
    0.1.0
    License
    Apache-2.0
    Last updated
    5 hours ago
    Downloads
    3

    #mvt

    A Mapbox Vector Tile (2.1) decoder in MoonBit, reading tiles as @mapbox/vector-tile does. Pure MoonBit on every backend (wasm, wasm-gc, js, native); it depends only on t-ujiie-g/pbf.

    Part of mbt-map, a WebGIS library, whose display worker decodes its tiles with it; published on its own.

    moon add t-ujiie-g/mvt

    /// The points of every polygon feature of the layer `name` whose `class` is "park".
    fn park_points(bytes : Bytes, name : String) -> Int raise @mvt.MvtError {
    let tile = @mvt.Tile::parse(bytes[:])
    guard tile.layer(name) is Some(layer) else { return 0 }
    guard layer.key_index("class") is Some(class) else { return 0 }
    let geometry = @mvt.Geometry::new()
    let mut points = 0
    for i in 0..<layer.length() {
    guard layer.geom_type(i) is Polygon else { continue }
    guard layer.property(i, class) is Some(String("park")) else { continue }
    if layer.decode_geometry(i, geometry) {
    points += geometry.num_points()
    }
    }
    points
    }

    #What it gives

    • Tile::parse(bytes): the layers, with their key and value tables, feature headers and tags decoded and checked. Geometry stays encoded until asked for. Tile::layer(name) gives the last layer of that name, as other decoders resolve duplicates.
    • Layer: name, version, extent (4096 if the tile gives none), keys, values, and the features by index in 0..<length(), stored in columns (no object per feature): geom_type(i), id(i), property(i, key_index) (no allocation; resolve key_index(key) once per layer), tag_count(i) / tag(i, k), properties(i) (a map).
    • Layer::decode_geometry(i, out): feature i's geometry into a reusable Geometry (coords as x, y pairs in tile units, ring_ends), with the rings @mapbox/vector-tile's loadGeometry gives. It returns false on a malformed command stream and Geometry::error() says why. Layer::load_geometry(i) is the allocating form, one array of points per ring.
    • Value: String, Float, Double, Int, UInt, SInt, Bool, and Null for a value message with no field set (the spec forbids it, other decoders accept it).
    • MvtError: Malformed (the protobuf error), InvalidCommand, IndexOutOfRange, OddTagCount, each with the byte offset, and message().

    There is no encoder, and polygon rings are not classified into polygons (their winding gives that; mbt-map does it while tessellating).

    The tile is treated as untrusted: tag indices are checked against the tables, command counts against the bytes left, and no input loops forever.

    #Matching @mapbox/vector-tile

    The repository compares the decoder with @mapbox/vector-tile on real tiles (mvt:golden): layer version and extent, and every feature's id, type, properties and geometry are the same on the js backend; the wasm-gc build is checked by point counts, property counts and coordinate sums.

    #License

    Apache-2.0. The module is written from the Vector Tile Specification and contains no third-party code (see NOTICE).

    MvtError

    pub(all) suberror MvtError {
    Malformed(
    PbfError
    )
    InvalidCommand(pos~ : Int, Int)
    IndexOutOfRange(pos~ : Int, Int)
    OddTagCount(pos~ : Int)
    } derive(Eq,
    Debug
    )

    Malformed vector tile. pos is the absolute byte offset in the tile.

    MvtError::equal

    fn MvtError::equal(MvtError, MvtError) -> Bool

    MvtError::message

    fn MvtError::message(self : MvtError) -> String

    A one-line description with the byte offset.

    MvtError::not_equal

    fn MvtError::not_equal(x : MvtError, y : MvtError) -> Bool

    MvtError::to_repr

    GeomType

    pub(all) enum GeomType {
    Unknown
    Point
    LineString
    Polygon
    } derive(Eq,
    Debug
    )

    A feature's geometry type, as the MVT spec numbers them from 0 (§4.3.4).

    GeomType::equal

    fn GeomType::equal(GeomType, GeomType) -> Bool

    GeomType::not_equal

    fn GeomType::not_equal(x : GeomType, y : GeomType) -> Bool

    GeomType::to_repr

    Geometry

    pub struct Geometry {
    coords : Array[Int]
    ring_ends : Array[Int]
    // private fields
    }

    Reusable decode buffer: coords holds x, y pairs in tile units and ring_ends[i] is the point index one past ring i. After a failed decode the contents are partial and error says why.

    Geometry::error

    fn Geometry::error(self : Geometry) -> MvtError?

    Why the last decode_geometry into this buffer failed, if it did.

    Geometry::new

    fn Geometry::new() -> Geometry

    Geometry::num_points

    fn Geometry::num_points(self : Geometry) -> Int

    Geometry::num_rings

    fn Geometry::num_rings(self : Geometry) -> Int

    Geometry::ring_start

    fn Geometry::ring_start(self : Geometry, i : Int) -> Int

    First point index of ring i; the ring ends at ring_ends[i].

    Layer

    pub struct Layer {
    name : String
    version : Int
    extent : Int
    keys : Array[String]
    values : Array[Value]
    // private fields
    }

    A tile layer; keys and values are the tables feature tags index into. Features are addressed by index in 0..<length() (others panic) and stored column-wise, so no per-feature object is allocated.

    Layer::decode_geometry

    fn Layer::decode_geometry(self : Layer, i : Int, out : Geometry) -> Bool

    Decodes feature i's geometry into out; false on failure (see Geometry::error). Rings match @mapbox/vector-tile's loadGeometry.

    Layer::geom_type

    fn Layer::geom_type(self : Layer, i : Int) -> GeomType

    Layer::id

    fn Layer::id(self : Layer, i : Int) -> UInt64?

    Layer::key_index

    fn Layer::key_index(self : Layer, key : String) -> Int?

    Index of key in keys, for property; resolve it once per layer.

    Layer::length

    fn Layer::length(self : Layer) -> Int

    Layer::load_geometry

    fn Layer::load_geometry(self : Layer, i : Int) -> Array[Array[(Int, Int)]] raise MvtError

    Allocating convenience: one array of (x, y) per ring of feature i.

    Layer::properties

    fn Layer::properties(self : Layer, i : Int) -> Map[String, Value]

    Feature i's tags as a key → value map; a repeated key keeps its last value.

    Layer::property

    fn Layer::property(self : Layer, i : Int, key_index : Int) -> Value?

    Feature i's value for the key at key_index, without allocating. A repeated key yields its last value.

    Layer::tag

    fn Layer::tag(self : Layer, i : Int, k : Int) -> (String, Value)

    Feature i's tag k (0 <= k < tag_count(i)) as key and value, in the order the tile lists them.

    Layer::tag_count

    fn Layer::tag_count(self : Layer, i : Int) -> Int

    How many tags (key and value pairs) feature i has.

    Tile

    pub struct Tile {
    layers : Array[Layer]
    }

    A decoded tile. Layer tables, feature headers and tags are decoded and validated by Tile::parse; feature geometry stays encoded until requested.

    Tile::layer

    fn Tile::layer(self : Tile, name : String) -> Layer?

    The last layer called name, as other decoders resolve duplicates.

    Tile::parse

    fn Tile::parse(bytes : BytesView) -> Tile raise MvtError

    Value

    pub(all) enum Value {
    String(String)
    Float(Float)
    Double(Double)
    Int(Int64)
    UInt(UInt64)
    SInt(Int64)
    Bool(Bool)
    Null
    } derive(Eq,
    Debug
    )

    A feature property value. Null stands for a value message with no field set, which the spec forbids but other decoders accept.

    Value::equal

    fn Value::equal(Value, Value) -> Bool

    Value::not_equal

    fn Value::not_equal(x : Value, y : Value) -> Bool

    Value::to_repr