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:
They are typically smaller to store
They can be easily transformed (rotated, etc.) in real time
They allow for continuous (as opposed to step-wise) zoom in Slippy Maps.
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:
Decoding of Version 2 VectorTiles from Protobuf byte data into useful GeoTrellis types.
Lazy decoding of Geometries. Only parse what you need!
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 geotrellis.vectortile.VectorTile class. Its companion object can
be used to construct VectorTiles from raw byte data:
import geotrellis.spark.SpatialKey
import geotrellis.spark.tiling.LayoutDefinition
import geotrellis.vector.Extent
import geotrellis.vectortile.VectorTile
val bytes: Array[Byte] = ... // from some `.mvt` fileval key: SpatialKey = ... // preknownval layout: LayoutDefinition = ... // preknownval tileExtent: Extent = layout.mapTransform(key)
/* Decode Protobuf bytes. */val tile: VectorTile = VectorTile.fromBytes(bytes, tileExtent)
/* Encode a VectorTile back into bytes. */val encodedBytes: Array[Byte] = tile.toBytes
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:
Geometries are implicitly encoded in some Coordinate Reference
system. That is, there is no such thing as a "projectionless" VectorTile.
When decoding a VectorTile, we must provide a GeoTrellis geotrellis.vector.Extent that
represents the Tile's area on a map.
With this, the grid coordinates stored in the VectorTile's Geometry are
shifted from their
original [0,4096] range to actual world coordinates in the Extent's CRS.
The id field in VectorTile Features doesn't matter.
UNKNOWN geometries are safe to ignore.
If a VectorTile geometry list marked as POINT has only one pair
of coordinates, it will be decoded as a GeoTrellis Point. If it has
more than one pair, it will be decoded as a MultiPoint. Likewise for
the LINESTRING and POLYGON types. A complaint has been made about
the spec regarding this, and future versions may include a difference
between single and multi geometries.
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 geotrellis.vectortile.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