tegola

README

Tegola

Tegola is a vector tile server delivering Mapbox Vector Tiles with support for PostGIS, GeoPackage and SAP HANA Spatial data providers. User documentation can be found at tegola.io

Features

• Native geometry processing (simplification, clipping, make valid, intersection, contains, scaling, translation)
• Mapbox Vector Tile v2 specification compliant.
• An embedded viewer with an automatically generated style for quick data visualization and inspection.
• Support for PostGIS and GeoPackage data providers. Extensible design to support additional data providers.
• Support for several cache backends: file, s3, redis, azure blob store.
• Cache seeding and invalidation via individual tiles (ZXY), lat / lon bounds and ZXY tile list.
• Parallelized tile serving and geometry processing.
• Support for Web Mercator (3857) and WGS84 (4326) projections.
• Support for AWS Lambda.
• Support for serving HTTPS.
• Support for PostGIS ST_AsMVT.
• Support for Prometheus observability.

Usage

tegola is a vector tile server
Version: v0.17.0

Usage:
  tegola [command]

Available Commands:
  cache       Manipulate the tile cache
  help        Help about any command
  serve       Use tegola as a tile server
  version     Print the version number of tegola

Flags:
      --config string   path to config file (default "config.toml")
  -h, --help            help for tegola

Use "tegola [command] --help" for more information about a command.

Running tegola as a vector tile server

1. Download the appropriate binary of tegola for your platform via the release page.
2. Set up your config file and run. By default, Tegola looks for a config.toml in the same directory as the binary. You can set a different location for the config.toml using a command flag:

./tegola serve --config=/path/to/config.toml

Server Endpoints

/

The server root will display the built-in viewer with an automatically generated style. For example:

/maps/:map_name/:z/:x/:y

Return vector tiles for a map. The URI supports the following variables:

• :map_name is the name of the map as defined in the config.toml file.
• :z is the zoom level of the map.
• :x is the row of the tile at the zoom level.
• :y is the column of the tile at the zoom level.

/maps/:map_name/:layer_name/:z/:x/:y

Return vector tiles for a map layer. The URI supports the same variables as the map URI with the additional variable:

• :layer_name is the name of the map layer as defined in the config.toml file.

/capabilities

Return a JSON encoded list of the server's configured maps and layers with various attributes.

/capabilities/:map_name

Return TileJSON details about the map.

/maps/:map_name/style.json

Return an auto generated Mapbox GL Style for the configured map.

Configuration

The tegola config file uses the TOML format. The following example shows how to configure a mvt_postgis data provider. The mvt_postgis provider will leverage PostGIS's ST_AsMVT() function for the encoding of the vector tile.

Under the maps section, map layers are associated with data provider layers and their min_zoom and max_zoom values are defined.

Example config using Postgres 12+ / PostGIS 3.0 ST_AsMVT():

# register a MVT data provider. MVT data providers have the prefix "mvt_" in their type
# note mvt data providers can not be conflated with any other providers of any type in a map
# thus a map may only contain a single mvt provider.
[[providers]]
name = "my_postgis"         # provider name is referenced from map layers (required). 
type = "mvt_postgis"        # the type of data provider must be "mvt_postgis" for this data provider (required)
uri = "postgresql://tegola:<password>@localhost:5432/tegola?ssl_mode=prefer" # database connection string

  [[providers.layers]]
  name = "landuse"
  # MVT data provider must use SQL statements
  # this table uses "geom" for the geometry_fieldname and "gid" for the id_fieldname so they don't need to be configured
  # Wrapping the geom with ST_AsMVTGeom is required. 
  sql = "SELECT ST_AsMVTGeom(geom,!BBOX!) AS geom, gid FROM gis.landuse WHERE geom && !BBOX!"

# maps are made up of layers
[[maps]]
name = "zoning"                           # used in the URL to reference this map (/maps/zoning)

  [[maps.layers]]
  name = "landuse"                        # name is optional. If it's not defined the name of the ProviderLayer will be used.
  provider_layer = "my_postgis.landuse"   # must match a data provider layer
  min_zoom = 10                           # minimum zoom level to include this layer
  max_zoom = 16                           # maximum zoom level to include this layer

  # configure addition URL parameters: /maps/:map_name/:layer_name/:z/:x/:y?param=value
  # which will be passed to the database queries
  [[maps.params]]
  name          = "param"         # name used in the URL
  token         = "!PARAM!"       # token to replace in providers.layers.sql query
  type          = "string"        # one of: int, float, string, bool
  sql           = "AND param = ?" # SQL to replace the token in the query. ? will be replaced with a parameter value. If omitted, defaults to "?"
  # if neither default_value nor default_sql is specified, the URL parameter is required to be present in all queries
  # either
  default_value = "value"         # if parameter is not specified, this value will be passed to .sql parameter
  # or
  default_sql   = " "             # if parameter is not specified, this value will replace the .sql parameter. Useful for omitting query entirely

• More information on PostgreSQL SSL modes can be found here.
• More information on the mvt_postgis provider can be found here

Environment Variables

Config TOML

Environment variables can be injected into the configuration file. One caveat is that the injection has to be within a string, though the value it represents does not have to be a string.

The above config example could be written as:

# register data providers
[[providers]]
name = "test_postgis"
type = "mvt_postgis"
uri = "${POSTGIS_CONN_STR}"  # database connection string
srid = 3857
max_connections = "${POSTGIS_MAX_CONN}"

SQL Debugging

The following environment variables can be used for debugging:

TEGOLA_SQL_DEBUG specify the type of SQL debug information to output. Currently, supporting two values:

• LAYER_SQL will print layer SQL as they are parsed from the config file.
• EXECUTE_SQL will print SQL that is executed for each tile request, and the number of items it returns or an error.

Usage

$ TEGOLA_SQL_DEBUG=LAYER_SQL tegola serve --config=/path/to/conf.toml

The following environment variables can be used to control various runtime options on dataproviders that are NOT mvt_postgis:

TEGOLA_OPTIONS specify a set of options comma or space delimited. Supports the following options

• DontSimplifyGeo to turn off simplification for all layers.
• SimplifyMaxZoom={{int}} to set the max zoom that simplification will apply to. (14 is default)

Client side debugging

When debugging client side, it's often helpful to see an outline of a tile along with it's Z/X/Y values. To encode a debug layer into every tile add the query string variable debug=true to the URL template being used to request tiles. For example:

http://localhost:8080/maps/mymap/{z}/{x}/{y}.vector.pbf?debug=true

The requested tile will be encoded with a layer that has the name value set to debug and includes the three following features.

• debug_outline is a line feature that traces the border of the tile
• debug_text is a point feature in the middle of the tile with the following tags:
• zxy is a string with the Z, X and Y values formatted as: Z:0, X:0, Y:0

Building from source

Tegola is written in Go and requires Go 1.21 or higher to compile from the source. (We support the two newest versions of Go.) To build tegola from the source, make sure you have Go installed and have cloned the repository. Navigate to the repository then run the following command:

go generate ... && cd cmd/tegola/ && go build -mod vendor

You will now have a binary named tegola in the current directory which is ready to run.

Build Flags The following build flags can be used to turn off certain features of tegola:

• noAzblobCache - turn off the Azure Blob cache back end.
• noS3Cache - turn off the AWS S3 cache back end.
• noRedisCache - turn off the Redis cache back end.
• noPostgisProvider - turn off the PostGIS data provider.
• noGpkgProvider - turn off the GeoPackage data provider. Note, GeoPackage uses CGO and will be turned off if the environment variable CGO_ENABLED=0 is set prior to building.
• noViewer - turn off the built-in viewer.
• pprof - enable Go profiler. Start profile server by setting the environment TEGOLA_HTTP_PPROF_BIND environment (e.g. TEGOLA_HTTP_PPROF_BIND=localhost:6060).
• noPrometheusObserver - turn off support for the Prometheus metric end point.

Example of using the build flags to turn of the Redis cache back end, the GeoPackage provider and the built-in viewer.

go build -tags 'noRedisCache noGpkgProvider noViewer'

Setting Version Information The following flags can be used to set version information:

# first set some env to make it easier to read:
BUILD_PKG=github.com/go-spatial/tegola/internal/build
VERSION=1.16.x
GIT_BRANCH=$(git branch --no-color --show-current)
GIT_REVISION=$(git log HEAD --oneline | head -n 1 | cut -d ' ' -f 1)

# build the go binary
go build -ldflags "-w -X ${BUILD_PKG}.Version=${VERSION} -X ${BUILD_PKG}.GitRevision=${GIT_REVISION} -X ${BUILD_PKG}.GitBranch=${GIT_BRANCH}"

License

See license file in the repo.

Looking for a vector tile style editor?

After Tegola is running you're likely going to want to work on your map's cartography. Give fresco a try!

Documentation

Overview

Package tegola describes the basic geometries that can be used to convert to and from.

Index

• Constants
• Variables
• func GeometeryDecorator(g Geometry, ptsPerLine int, comment string, ptDecorator func(pt Point) string) string
• func GeometryAsJSON(g Geometry, w io.Writer) error
• func GeometryAsMap(g Geometry) map[string]interface{}
• func GeometryAsString(g Geometry) string
• func IsCollectionEqual(c1, c2 Collection) bool
• func IsGeometryEqual(g1, g2 Geometry) bool
• func IsLineStringEqual(l1, l2 LineString) bool
• func IsMultiLineEqual(ml1, ml2 MultiLine) bool
• func IsMultiPointEqual(mp1, mp2 MultiPoint) bool
• func IsMultiPolygonEqual(mp1, mp2 MultiPolygon) bool
• func IsPoint3Equal(p1, p2 Point3) bool
• func IsPointEqual(p1, p2 Point) bool
• func IsPolygonEqual(p1, p2 Polygon) bool
• func LineAsPointPairs(l LineString) (pp []float64)
• func Tile2Lat(y, z uint64) float64
• func Tile2Lon(x, z uint64) float64
• type Collection
• type Geometry
• type LineString
• type MultiLine
• type MultiPoint
• type MultiPolygon
• type Point
• type Point3
• type Polygon
• type Tile
  • func NewTile(z, x, y uint) (t *Tile)
  • func NewTileLatLong(z uint, lat, lon float64) (t *Tile)
  • func (t *Tile) Bounds() [4]float64
  • func (t *Tile) Deg2Num() (x, y int)
  • func (t *Tile) FromPixel(srid int, pt [2]float64) (npt [2]float64, err error)
  • func (t *Tile) Init()
  • func (t *Tile) Num2Deg() (lat, lng float64)
  • func (t *Tile) PixelBufferedBounds() (bounds [4]float64, err error)
  • func (t *Tile) ToPixel(srid int, pt [2]float64) (npt [2]float64, err error)
  • func (t *Tile) ZEpislon() float64
  • func (t *Tile) ZLevel() uint
  • func (t *Tile) ZRes() float64

Constants

const (
	WebMercator = 3857
	WGS84       = 4326
)

const (
	DefaultEpislon    = 10.0
	DefaultExtent     = 4096
	DefaultTileBuffer = 64.0
	MaxZ              = 22
)

Variables

var (
	WebMercatorBounds = &geom.Extent{-20026376.39, -20048966.10, 20026376.39, 20048966.10}
	WGS84Bounds       = &geom.Extent{-180.0, -85.0511, 180.0, 85.0511}
)

var UnknownConversionError = fmt.Errorf("do not know how to convert value to requested value")

Functions

func GeometeryDecorator

func GeometeryDecorator(g Geometry, ptsPerLine int, comment string, ptDecorator func(pt Point) string) string

func GeometryAsJSON

func GeometryAsJSON(g Geometry, w io.Writer) error

func GeometryAsMap

func GeometryAsMap(g Geometry) map[string]interface{}

func GeometryAsString

func GeometryAsString(g Geometry) string

func IsCollectionEqual

func IsCollectionEqual(c1, c2 Collection) bool

CollectionIsEqual will check to see if the provided collections are equal. This function does not check to see if the collections contain any recursive structures, and if there are any recursive structures it will hang. If the collections contains any unknown geometries it will be assumed to not match.

func IsGeometryEqual

func IsGeometryEqual(g1, g2 Geometry) bool

GeometryIsEqual will check to see if the two given geometeries are equal. This function does not check to see if there are any recursive structures if there are any recursive structures it will hang. If the type of the geometry is unknown, it is assumed that it does not match any other geometries.

func IsLineStringEqual

func IsLineStringEqual(l1, l2 LineString) bool

IsLineStringEqual will check to see if the two linesstrings provided are equal.

func IsMultiLineEqual

func IsMultiLineEqual(ml1, ml2 MultiLine) bool

IsMultiLineEqual will check to see if the two Multilines that are provided are equal.

func IsMultiPointEqual

func IsMultiPointEqual(mp1, mp2 MultiPoint) bool

IsMultiPointEqual will check to see if the two provided multipoints are equal

func IsMultiPolygonEqual

func IsMultiPolygonEqual(mp1, mp2 MultiPolygon) bool

MultiPolygonIsEqual will check to see if the two provided multi-polygons are equal.

func IsPoint3Equal

func IsPoint3Equal(p1, p2 Point3) bool

IsPoint3Equal will check to see if the two 3d tegola points are equal.

func IsPointEqual

func IsPointEqual(p1, p2 Point) bool

IsPointEqual will check to see if the two tegola points are equal.

func IsPolygonEqual

func IsPolygonEqual(p1, p2 Polygon) bool

PolygonIsEqual will check to see if the two provided polygons are equal.

func LineAsPointPairs

func LineAsPointPairs(l LineString) (pp []float64)

func Tile2Lat

func Tile2Lat(y, z uint64) float64

func Tile2Lon

func Tile2Lon(x, z uint64) float64

Types

type Collection

type Collection interface {
	Geometry
	Geometries() []Geometry
}

Collection is a collections of different geometries.

type Geometry

type Geometry interface{}

Geometry describes a geometry.

type LineString

type LineString interface {
	Geometry
	Subpoints() []Point
}

LineString is a Geometry of a line.

type MultiLine

type MultiLine interface {
	Geometry
	Lines() []LineString
}

MultiLine is a Geometry with multiple individual lines.

type MultiPoint

type MultiPoint interface {
	Geometry
	Points() []Point
}

MultiPoint is a Geometry with multiple individual points.

type MultiPolygon

type MultiPolygon interface {
	Geometry
	Polygons() []Polygon
}

MultiPolygon describes a Geometry multiple intersecting polygons. There should only one exterior polygon, and the rest of the polygons should be interior polygons. The interior polygons will exclude the area from the exterior polygon.

type Point

type Point interface {
	Geometry
	X() float64
	Y() float64
}

Point is how a point should look like.

type Point3

type Point3 interface {
	Point
	Z() float64
}

Point3 is a point with three dimensions; at current is just converted and treated as a point.

type Polygon

type Polygon interface {
	Geometry
	Sublines() []LineString
}

Polygon is a multi-line Geometry where all the lines connect to form an enclose space.

type Tile

type Tile struct {
	Z         uint
	X         uint
	Y         uint
	Lat       float64
	Long      float64
	Tolerance float64
	Extent    float64
	Buffer    float64
	// contains filtered or unexported fields
}

Tile slippy map tilenames http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames

func NewTile

func NewTile(z, x, y uint) (t *Tile)

NewTile will return a non-nil tile object.

func NewTileLatLong

func NewTileLatLong(z uint, lat, lon float64) (t *Tile)

NewTileLatLong will return a non-nil tile object.

func (*Tile) Bounds

func (t *Tile) Bounds() [4]float64

Bounds returns the bounds of the Tile as defined by the North most Longitude, East most Latitude, South most Longitude, West most Latitude.

func (*Tile) Deg2Num

func (t *Tile) Deg2Num() (x, y int)

func (*Tile) FromPixel

func (t *Tile) FromPixel(srid int, pt [2]float64) (npt [2]float64, err error)

func (*Tile) Init

func (t *Tile) Init()

func (*Tile) Num2Deg

func (t *Tile) Num2Deg() (lat, lng float64)

func (*Tile) PixelBufferedBounds

func (t *Tile) PixelBufferedBounds() (bounds [4]float64, err error)

func (*Tile) ToPixel

func (t *Tile) ToPixel(srid int, pt [2]float64) (npt [2]float64, err error)

func (*Tile) ZEpislon

func (t *Tile) ZEpislon() float64

This is from Leafty

func (*Tile) ZLevel

func (t *Tile) ZLevel() uint

Returns web mercator zoom level

func (*Tile) ZRes

func (t *Tile) ZRes() float64

ZRes takes a web mercator zoom level and returns the pixel resolution for that scale, assuming t.Extent x t.Extent pixel tiles. Non-integer zoom levels are accepted. ported from: https://raw.githubusercontent.com/mapbox/postgis-vt-util/master/postgis-vt-util.sql 40075016.6855785 is the equator in meters for WGS84 at z=0