package vectortile

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


Users of this library need only pay attention to geotrellis.vectortile and geotrellis.vectortile.protobuf. Any classes in the internal.* submodules are unique to the machinery of VectorTile {de,en}coding, and can be safely ignored.


The central type is the VectorTile trait. At current, it is only backed by one backend, the default Protobuf implementation that follows the original spec. The accompanying type is geotrellis.vectortile.protobuf.ProtobufTile, and its companion object can be used to actually construct VectorTiles from raw byte data:

import geotrellis.spark.SpatialKey
import geotrellis.spark.tiling.LayoutDefinition
import geotrellis.vector.Extent
import geotrellis.vectortile.VectorTile
import geotrellis.vectortile.protobuf._

val bytes: Array[Byte] = ...  // from some `.mvt` file
val key: SpatialKey = ...  // preknown
val layout: LayoutDefinition = ...  // preknown
val tileExtent: Extent = layout.mapTransform(key)

/* Decode Protobuf bytes. */
val tile: VectorTile = ProtobufTile.fromBytes(bytes, tileExtent)

/* Encode a VectorTile back into bytes. */
val encodedBytes: Array[Byte] = tile match {
  case t: ProtobufTile => t.toBytes
  case _ => ???  // Handle other backends or throw errors.

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.protobuf.Value to guarantee type safety.

Implementation Assumptions

This particular implementation of the VectorTile spec makes the following assumptions:



Linear Supertypes
AnyRef, Any
  1. Alphabetic
  2. By Inheritance
  1. vectortile
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
  1. Public
  2. All

Type Members

  1. trait Layer extends Serializable


    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.

  2. trait VectorTile extends Serializable


    A high-level representation of a Vector Tile.

    A high-level representation of a Vector Tile. 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.

    Traditionally, VectorTiles are encoded as Protobuf data, which this library provides a codec for. However, by making this top-level type a trait, we are able to define alternative backends (GeoJson, for instance. Yet unimplemented.).

    See geotrellis.vectortile.protobuf.ProtobufTile for more information on how to decode and encode VectorTiles.

Value Members

  1. package protobuf


Inherited from AnyRef

Inherited from Any