Packages

  • package root
    Definition Classes
    root
  • package geotrellis
    Definition Classes
    root
  • package vector
    Definition Classes
    geotrellis
  • package vectortile

    This package is experimental. Expect API flux.

    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:

    • 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` file
    val key: SpatialKey = ...  // preknown
    val layout: LayoutDefinition = ...  // preknown
    val 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.
    Definition Classes
    geotrellis
    Version

    2.1

  • package internal

    Users need not concern themselves with this subpackage; it handles the details internal to the VectorTile encoding/decoding process.

  • Layer
  • LazyLayer
  • MVTFeature
  • StrictLayer
  • VBool
  • VDouble
  • VFloat
  • VInt64
  • VSint64
  • VString
  • VWord64
  • Value
  • VectorTile
p

geotrellis

vectortile

package vectortile

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:

  • 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` file
val key: SpatialKey = ...  // preknown
val layout: LayoutDefinition = ...  // preknown
val 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.
Version

2.1

Linear Supertypes
Ordering
  1. Alphabetic
  2. By Inheritance
Inherited
  1. vectortile
  2. AnyRef
  3. Any
  1. Hide All
  2. Show All
Visibility
  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.

    Annotations
    @experimental()
  2. case class LazyLayer(rawLayer: PBLayer, tileExtent: Extent) extends Layer with Product with Serializable

    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.

    Annotations
    @experimental()
  3. case class MVTFeature[+G <: Geometry](id: Option[Long], geom: G, data: Map[String, Value]) extends Product with Serializable

    A case class that conforms to the Mapbox Vector Tile 2.0 specification

    A case class that conforms to the Mapbox Vector Tile 2.0 specification

    Users are responsible for converting their geometries, features and other objects to MVTFeatures so that they can be written to mvts using VectorTile.

    https://docs.mapbox.com/vector-tiles/specification/

  4. case class StrictLayer(name: String, tileWidth: Int, version: Int, tileExtent: Extent, points: Seq[MVTFeature[Point]], multiPoints: Seq[MVTFeature[MultiPoint]], lines: Seq[MVTFeature[LineString]], multiLines: Seq[MVTFeature[MultiLineString]], polygons: Seq[MVTFeature[Polygon]], multiPolygons: Seq[MVTFeature[MultiPolygon]]) extends Layer with Product with Serializable

    A Layer crafted through some strict ingest process.

    A Layer crafted through some strict ingest process.

    Annotations
    @experimental()
  5. case class VBool(value: Boolean) extends Value with Product with Serializable

    A wrapper for Boolean to allow all Value subtypes to be stored in the same Map.

  6. case class VDouble(value: Double) extends Value with Product with Serializable

    A wrapper for Double to allow all Value subtypes to be stored in the same Map.

  7. case class VFloat(value: Float) extends Value with Product with Serializable

    A wrapper for Float to allow all Value subtypes to be stored in the same Map.

  8. case class VInt64(value: Long) extends Value with Product with Serializable

    A wrapper for Long to allow all Value subtypes to be stored in the same Map.

  9. case class VSint64(value: Long) extends Value with Product with Serializable

    A wrapper for zig-zag encoded ints to allow all Value subtypes to be stored in the same Map.

  10. case class VString(value: String) extends Value with Product with Serializable

    A wrapper for String to allow all Value subtypes to be stored in the same Map.

  11. case class VWord64(value: Long) extends Value with Product with Serializable

    A wrapper for unsigned, 64-bit ints to allow all Value subtypes to be stored in the same Map.

  12. sealed trait Value extends Serializable

    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.

  13. case class VectorTile(layers: Map[String, Layer], tileExtent: Extent, forcePolygonWinding: Boolean = true) extends Product with Serializable

    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)
    Annotations
    @experimental()

Value Members

  1. object MVTFeature extends Serializable
  2. object VectorTile extends Serializable
    Annotations
    @experimental()

Inherited from AnyRef

Inherited from Any

Ungrouped