mvt

README

MVT

This package contains functions and types for encoding a geometry in Mapbox Vector Tiles. This package depends on the protbuf package.

In short, a Tiles has Layers, which have Feautures. The Feature type is what holds a single geom.Geometry and associated metadata.

To encode a geometry into a tile, you need:

• a geometry
• a tile's geom.Extent in the same projection as the geometry
• the size of the tile you want to output in pixels

note: the geometry must not go outside the tile extent. If this is unknown, use the clip package before encoding.

To encode:

1. Call PrepareGeomtry, it returns a geom.Geometry that is "reprojected" into pixel values relative to the tile
2. Add the returned geometry to a Feature, optionally with an ID and tags by calling NewFeatures.
3. Add the feature to a Layer with a name for the layer by calling (*Layer).AddFeatures
4. Add the layer to a Tile by calling (*Tile).AddLayers
5. Get the protobuf tile by calling (*Tile).VTile
6. Encode the protobuf into bytes with proto.Marshal

For an example, check the use of this package in tegola/atlas/map.go

Documentation

Overview

Package mvt is used to encode MVT tiles

In short, a `Tile`s has `Layer`s, which have `Feauture`s. The `Feature` type is what holds a single `geom.Geometry` and associated metadata.

To encode a geometry into a tile, you need:

• a geometry
• a tile's `geom.Extent` in the same projection as the geometry
• the size of the tile you want to output in pixels

note: the geometry must not go outside the tile extent. If this is unknown, use the clip package before encoding. (https://godoc.org/github.com/go-spatial/geom/planar/clip#Geometry)

To encode:

1. Call `PrepareGeomtry`, it returns a `geom.Geometry` that is "reprojected" into pixel values relative to the tile
2. Add the returned geometry to a `Feature`, optionally with an ID and tags by calling `NewFeatures`.
3. Add the feature to a `Layer` with a name for the layer by calling `(*Layer).AddFeatures`
4. Add the layer to a `Tile` by calling `(*Tile).AddLayers`
5. Get the `protobuf` tile by calling `(*Tile).VTile`
6. Encode the `protobuf` into bytes with `proto.Marshal`

For an example, check the use of this package in tegola/atlas/map.go (https://github.com/go-spatial/tegola/blob/master/atlas/map.go)

Index

• Constants
• Variables
• func DecodeGeometry(gtype vectorTile.Tile_GeomType, b []uint32) (geom.Geometry, error)
• func NewCursor() *cursor
• func PrepareGeo(geo geom.Geometry, tile *geom.Extent, pixelExtent float64) geom.Geometry
• func TileGeomCollection(tile *Tile) geom.Collection
• type Command
  • func NewCommand(cmd uint32, count int) Command
  • func (c Command) Count() int
  • func (c Command) ID() uint32
  • func (c Command) String() string
• type Feature
  • func NewFeatures(geo geom.Geometry, tags map[string]interface{}) (f []Feature)
  • func (f Feature) String() string
  • func (f *Feature) VTileFeature(ctx context.Context, keys []string, vals []interface{}) (tf *vectorTile.Tile_Feature, err error)
• type Layer
  • func (l *Layer) AddFeatures(features ...Feature)
  • func (l *Layer) Extent() int
  • func (l *Layer) Features() (f []Feature)
  • func (l *Layer) RemoveFeature(idxs ...int)
  • func (l *Layer) SetExtent(e int)
  • func (l *Layer) VTileLayer(ctx context.Context) (*vectorTile.Tile_Layer, error)
  • func (*Layer) Version() int
• type Tile
  • func Decode(r io.Reader) (*Tile, error)
  • func DecodeByte(b []byte) (*Tile, error)
  • func (t *Tile) AddLayers(layers ...*Layer) error
  • func (t *Tile) Layers() (l []Layer)
  • func (t *Tile) VTile(ctx context.Context) (vt *vectorTile.Tile, err error)

Constants

const (
	MimeType = "application/vnd.mapbox-vector-tile"
)

Variables

var (
	ErrNilFeature          = fmt.Errorf("feature is nil")
	ErrUnknownGeometryType = fmt.Errorf("unknown geometry type")
	ErrNilGeometryType     = fmt.Errorf("geometry is nil")
)

var (
	Version       uint32 = 2
	DefaultExtent uint32 = 4096
)

var ErrExtraData = errors.New("mvt: invalid extra data")

Functions

func DecodeGeometry

func DecodeGeometry(gtype vectorTile.Tile_GeomType, b []uint32) (geom.Geometry, error)

func NewCursor

func NewCursor() *cursor

NewCursor creates a new cursor for drawing and MVT tile

func PrepareGeo

func PrepareGeo(geo geom.Geometry, tile *geom.Extent, pixelExtent float64) geom.Geometry

PrepareGeo converts the geometry's coordinates to tile pixel coordinates. tile should be the extent of the tile, in the same projection as geo. pixelExtent is the dimension of the (square) tile in pixels usually 4096, see DefaultExtent. This function treats the tile extent elements as left, top, right, bottom. This is fine when working with a north-positive projection such as lat/long (epsg:4326) and web mercator (epsg:3857), but a south-positive projection (ie. epsg:2054) or west-postive projection would then flip the geomtery. To properly render these coordinate systems, simply swap the X's or Y's in the tile extent.

func TileGeomCollection

func TileGeomCollection(tile *Tile) geom.Collection

TileGeomCollection returns all geometries in a tile as a collection

Types

type Command

type Command uint32

func NewCommand

func NewCommand(cmd uint32, count int) Command

NewCommand return a new command encoder

func (Command) Count

func (c Command) Count() int

Count encode the count of elements in the command

func (Command) ID

func (c Command) ID() uint32

ID encodes the ID of the command

func (Command) String

func (c Command) String() string

type Feature

type Feature struct {
	ID       *uint64
	Tags     map[string]interface{}
	Geometry geom.Geometry
}

Feature describes a feature of a Layer. A layer will contain multiple features each of which has a geometry describing the interesting thing, and the metadata associated with it.

func NewFeatures

func NewFeatures(geo geom.Geometry, tags map[string]interface{}) (f []Feature)

NewFeatures returns one or more features for the given Geometry

func (Feature) String

func (f Feature) String() string

func (*Feature) VTileFeature

func (f *Feature) VTileFeature(ctx context.Context, keys []string, vals []interface{}) (tf *vectorTile.Tile_Feature, err error)

VTileFeature will return a vectorTile.Feature that would represent the Feature

type Layer

type Layer struct {
	// Name is the unique name of the layer within the tile
	Name string
	// contains filtered or unexported fields
}

Layer describes a layer within a tile. Each layer can have multiple features

func (*Layer) AddFeatures

func (l *Layer) AddFeatures(features ...Feature)

AddFeatures will add one or more Features to the Layer per the spec features SHOULD have unique ids but it's not required

func (*Layer) Extent

func (l *Layer) Extent() int

Extent defaults to 4096

func (*Layer) Features

func (l *Layer) Features() (f []Feature)

Features returns a copy of the features in the layer, use the index of the this array to remove any features from the layer

func (*Layer) RemoveFeature

func (l *Layer) RemoveFeature(idxs ...int)

RemoveFeature allows you to remove one or more features, with the provided indexes. To figure out the indexes, use the indexs from the Features array.

func (*Layer) SetExtent

func (l *Layer) SetExtent(e int)

SetExtent sets the extent value

func (*Layer) VTileLayer

func (l *Layer) VTileLayer(ctx context.Context) (*vectorTile.Tile_Layer, error)

VTileLayer returns a vectorTile Tile_Layer object that represents this layer.

func (*Layer) Version

func (*Layer) Version() int

Version is the version of tile spec this layer is from.

type Tile

type Tile struct {
	// contains filtered or unexported fields
}

Tile describes a Mapbox Vector Tile

func Decode

func Decode(r io.Reader) (*Tile, error)

Decode reads all the data from r and decodes the MVT tile into a Tile TODO(ear7h): handle tile tags

func DecodeByte

func DecodeByte(b []byte) (*Tile, error)

DecodeByte decodes the MVT encoded bytes into a Tile. TODO(ear7h): handle tile tags

func (*Tile) AddLayers

func (t *Tile) AddLayers(layers ...*Layer) error

AddLayers adds a Layer to the Tile

func (*Tile) Layers

func (t *Tile) Layers() (l []Layer)

Layers returns a copy of the layers in this tile.

func (*Tile) VTile

func (t *Tile) VTile(ctx context.Context) (vt *vectorTile.Tile, err error)

VTile returns a Tile according to the Google Protobuff definition. This function does the hard work of converting everything to the standard.