A layer, which could contain any number of Features of any Geometry type.
A layer, which could contain any number of Features of any Geometry type. Here, "Feature" and "Geometry" refer specifically to the GeoTrellis classes of the same names.
A Layer decoded from Protobuf data.
A Layer decoded from Protobuf data. All of its Features are decoded lazily, making for very fast extraction of single features/geometries.
A Layer crafted through some strict ingest process.
A Layer crafted through some strict ingest process.
A wrapper for Boolean
to allow all Value
subtypes to be stored in
the same Map.
A wrapper for Double
to allow all Value
subtypes to be stored in
the same Map.
A wrapper for Float
to allow all Value
subtypes to be stored in
the same Map.
A wrapper for Long
to allow all Value
subtypes to be stored in
the same Map.
A wrapper for zig-zag encoded ints to allow all Value
subtypes to be
stored in the same Map.
A wrapper for String
to allow all Value
subtypes to be stored in
the same Map.
A wrapper for unsigned, 64-bit ints to allow all Value
subtypes to be
stored in the same Map.
Feature metadata key/value Maps are completely untyped.
Feature metadata key/value Maps are completely untyped. All keys and values used by Features across a common parent Layer are stored in that parent. Raw Features themselves only store indices into the parent's key/value lists. So, for an example MultiPoint Feature of fire hydrant locations, its metadata could look like:
{ name: "Hydrants", colour: "red", model: 5 }
That's fine if interpreted as JSON, but bad as Scala, as it doesn't give us
a clean Map[String, ConcreteTypeHere]
. Furthermore, Features within the
same Layer don't have to agree on the Value type for the same key:
{ name: "Stop lights", colour: 1, model: "ABC-123" }
Nor, actually, do Layers have to agree on key sets for their Features.
The sealed trait Value
here and its extensions aim to provide some
type safety in light of the situation described here.
A concrete representation of a VectorTile, as one decoded from Protobuf bytes.
A concrete representation of a VectorTile, as one decoded from Protobuf bytes. At its simplest, a Tile is just a collection of Layers. We opt to expose each Layer name at the Tile level, as the keys of a Map. This way, if the layer names are known by the user ahead of time, they can search through the Tile quickly.
import geotrellis.vectortile._ val bytes: Array[Byte] = ... // from some `.mvt` file val key: SpatialKey = ... // preknown val layout: LayoutDefinition = ... // preknown val tileExtent: Extent = layout.mapTransform(key) val tile: VectorTile = VectorTile.fromBytes(bytes, tileExtent)
This package is experimental. Expect API flux.
Invented by Mapbox, VectorTiles are a combination of the ideas of finite-sized tiles and vector geometries. Mapbox maintains the official implementation spec for VectorTile codecs. The specification is free and open source.
VectorTiles are advantageous over raster tiles in that:
Raw VectorTile data is stored in the protobuf format. Any codec implementing the spec must decode and encode data according to this .proto schema.
What is this package?
geotrellis-vectortile is a high-performance implementation of Version 2.1 of the VectorTile spec. It features:
Using this Package
Modules
Users of this library need only pay attention to geotrellis.vectortile. Any classes in the internal.* submodules are unique to the machinery of VectorTile {de,en}coding, and can be safely ignored.
Types
The central type is the VectorTile class. Its companion object can be used to construct VectorTiles from raw byte data:
The V* types form a small sum type and are used to represent usually untyped Feature-level metadata. This metadata is equivalent to a JSON Object, where String keys index values of any type. A Scala Map requires more rigidity (for the better), and so we use geotrellis.vectortile.Value to guarantee type safety.
Implementation Assumptions
This particular implementation of the VectorTile spec makes the following assumptions:
id
field in VectorTile Features doesn't matter.UNKNOWN
geometries are safe to ignore.geometry
list marked asPOINT
has only one pair of coordinates, it will be decoded as a GeoTrellisPoint
. If it has more than one pair, it will be decoded as aMultiPoint
. Likewise for theLINESTRING
andPOLYGON
types. A complaint has been made about the spec regarding this, and future versions may include a difference between single and multi geometries.2.1