mvt

README

encoding/mvt

Package mvt provides functions for encoding and decoding Mapbox Vector Tiles. The interface is defined as:

type Layer struct {
	Name     string
	Version  uint32
	Extent   uint32
	Features []*geojson.Feature
}

func MarshalGzipped(layers Layers) ([]byte, error)
func Marshal(layers Layers) ([]byte, error)

func UnmarshalGzipped(data []byte) (Layers, error)
func Unmarshal(data []byte) (Layers, error)

These function decode the geometry and leave it in the "tile coordinates". To project it to and from WGS84 (standard lon/lat) use:

func (l Layer) ProjectToTile(tile maptile.Tile)
func (l Layer) ProjectToWGS84(tile maptile.Tile)

Encoding example

// Start with a set of feature collections defining each layer in lon/lat (WGS84).
collections := map[string]*geojson.FeatureCollection{}

// Convert to a layers object and project to tile coordinates.
layers := mvt.NewLayers(collections)
layers.ProjectToTile(maptile.New(x, y, z))

// In order to be used as source for MapboxGL geometries need to be clipped
// to max allowed extent. (uncomment next line)
// layers.Clip(mvt.MapboxGLDefaultExtentBound)

// Simplify the geometry now that it's in the tile coordinate space.
layers.Simplify(simplify.DouglasPeucker(1.0))

// Depending on use-case remove empty geometry, those two small to be
// represented in this tile space.
// In this case lines shorter than 1, and areas smaller than 1.
layers.RemoveEmpty(1.0, 1.0)

// encoding using the Mapbox Vector Tile protobuf encoding.
data, err := layers.Marshal() // this data is NOT gzipped.

// Sometimes MVT data is stored and transfered gzip compressed. In that case:
data, err := layers.MarshalGzipped()

Feature IDs

Since GeoJSON ids can be any number or string they won't necessarily map to vector tile uint64 ids. This is a common incompatibility between the two types.

During marshaling the code tries to convert the geojson.Feature.ID to a positive integer, possibly parsing a string. If the number is negative, the id is omitted. If the number is a positive decimal the number is truncated.

For unmarshaling the id will be converted into a float64 to be consistent with how the encoding/json package decodes numbers.

Documentation

Index

• Constants
• Variables
• func Marshal(layers Layers) ([]byte, error)
• func MarshalGzipped(layers Layers) ([]byte, error)
• type Layer
  • func NewLayer(name string, fc *geojson.FeatureCollection) *Layer
  • func (l *Layer) Clip(box orb.Bound)
  • func (l *Layer) ProjectToTile(tile maptile.Tile)
  • func (l *Layer) ProjectToWGS84(tile maptile.Tile)
  • func (l *Layer) RemoveEmpty(lineLimit, areaLimit float64)
  • func (l *Layer) Simplify(s orb.Simplifier)
• type Layers
  • func NewLayers(layers map[string]*geojson.FeatureCollection) Layers
  • func Unmarshal(data []byte) (Layers, error)
  • func UnmarshalGzipped(data []byte) (Layers, error)
  • func (ls Layers) Clip(box orb.Bound)
  • func (ls Layers) ProjectToTile(tile maptile.Tile)
  • func (ls Layers) ProjectToWGS84(tile maptile.Tile)
  • func (ls Layers) RemoveEmpty(lineLimit, areaLimit float64)
  • func (ls Layers) Simplify(s orb.Simplifier)
  • func (ls Layers) ToFeatureCollections() map[string]*geojson.FeatureCollection

Examples

• Marshal

Constants

const (
	// DefaultExtent for mapbox vector tiles. (https://www.mapbox.com/vector-tiles/specification/)
	DefaultExtent = 4096
)

Variables

var (
	// MapboxGLDefaultExtentBound holds the default mapbox vector tile bounds used by mapbox-gl.
	// (https://www.mapbox.com/mapbox-gl-js/style-spec/#sources-vector)
	MapboxGLDefaultExtentBound = orb.Bound{
		Min: orb.Point{-1 * DefaultExtent, -1 * DefaultExtent},
		Max: orb.Point{2*DefaultExtent - 1, 2*DefaultExtent - 1},
	}
)

Functions

func Marshal

func Marshal(layers Layers) ([]byte, error)

Marshal will take a set of layers and encode them into a Mapbox Vector Tile format.

Example

package main

import (
	"log"

	"github.com/paulmach/orb/encoding/mvt"
	"github.com/paulmach/orb/geojson"
	"github.com/paulmach/orb/maptile"
	"github.com/paulmach/orb/simplify"
)

func main() {
	// Start with a set of feature collections defining each layer in lon/lat (WGS84).
	collections := map[string]*geojson.FeatureCollection{}

	// Convert to a layers object and project to tile coordinates.
	layers := mvt.NewLayers(collections)
	layers.ProjectToTile(maptile.New(17896, 24449, 16)) // x, y, z

	// Simplify the geometry now that it's in the tile coordinate space.
	layers.Simplify(simplify.DouglasPeucker(1.0))

	// Depending on use-case remove empty geometry, those two small to be
	// represented in this tile space.
	// In this case lines shorter than 1, and areas smaller than 1.
	layers.RemoveEmpty(1.0, 1.0)

	// encoding using the Mapbox Vector Tile protobuf encoding.
	data, err := mvt.Marshal(layers) // this data is NOT gzipped.

	// Sometimes MVT data is stored and transferred gzip compressed. In that case:
	data, err = mvt.MarshalGzipped(layers)

	// error checking
	if err != nil {
		log.Fatalf("marshal error: %v", err)
	}

	_ = data
}

func MarshalGzipped

func MarshalGzipped(layers Layers) ([]byte, error)

MarshalGzipped will marshal the layers into Mapbox Vector Tile format and gzip the result. A lot of times MVT data is gzipped at rest, e.g. in a mbtiles file.

Types

type Layer

type Layer struct {
	Name     string
	Version  uint32
	Extent   uint32
	Features []*geojson.Feature
}

Layer is intermediate MVT layer to be encoded/decoded or projected.

func NewLayer

func NewLayer(name string, fc *geojson.FeatureCollection) *Layer

NewLayer is a helper to create a Layer from a feature collection and a name, it sets the default extent and version to 1.

func (*Layer) Clip

func (l *Layer) Clip(box orb.Bound)

Clip will clip all geometries in this layer to the given bounds.

func (*Layer) ProjectToTile

func (l *Layer) ProjectToTile(tile maptile.Tile)

ProjectToTile will project all the geometries in the layer to tile coordinates based on the extent and the mercator projection.

func (*Layer) ProjectToWGS84

func (l *Layer) ProjectToWGS84(tile maptile.Tile)

ProjectToWGS84 will project all the geometries backed to WGS84 from the extent and mercator projection.

func (*Layer) RemoveEmpty

func (l *Layer) RemoveEmpty(lineLimit, areaLimit float64)

RemoveEmpty will remove line strings shorter/smaller than the limits.

func (*Layer) Simplify

func (l *Layer) Simplify(s orb.Simplifier)

Simplify will run the layer geometries through the simplifier.

type Layers

type Layers []*Layer

Layers is a set of layers.

func NewLayers

func NewLayers(layers map[string]*geojson.FeatureCollection) Layers

NewLayers creates a set of layers given a set of feature collections.

func Unmarshal

func Unmarshal(data []byte) (Layers, error)

Unmarshal takes Mapbox Vector Tile (MVT) data and converts into a set of layers, It does not project the coordinates.

func UnmarshalGzipped

func UnmarshalGzipped(data []byte) (Layers, error)

UnmarshalGzipped takes gzipped Mapbox Vector Tile (MVT) data and unzips it before decoding it into a set of layers, It does not project the coordinates.

func (Layers) Clip

func (ls Layers) Clip(box orb.Bound)

Clip will clip all geometries in all layers to the given bounds.

func (Layers) ProjectToTile

func (ls Layers) ProjectToTile(tile maptile.Tile)

ProjectToTile will project all the geometries in all layers to tile coordinates based on the extent and the mercator projection.

func (Layers) ProjectToWGS84

func (ls Layers) ProjectToWGS84(tile maptile.Tile)

ProjectToWGS84 will project all the geometries in all the layers backed to WGS84 from the extent and mercator projection.

func (Layers) RemoveEmpty

func (ls Layers) RemoveEmpty(lineLimit, areaLimit float64)

RemoveEmpty will remove line strings shorter/smaller than the limits.

func (Layers) Simplify

func (ls Layers) Simplify(s orb.Simplifier)

Simplify will run all the geometry of all the layers through the provided simplifer.

func (Layers) ToFeatureCollections

func (ls Layers) ToFeatureCollections() map[string]*geojson.FeatureCollection

ToFeatureCollections converts the layers to sets of geojson feature collections.