README

Tegola

Build Status Report Card Coverage Status Godoc license

Tegola is a vector tile server delivering Mapbox Vector Tiles with support for PostGIS and GeoPackage 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.
  • Embedded viewer with auto 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.

Usage

tegola is a vector tile server
Version: v0.10.2

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. Setup your config file and run. Dy 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 a built in viewer with an auto generated style. For example:

tegola built in viewer

/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 PostGIS data provider with two layers. The first layer includes a tablename, geometry_field and an id_field. The second layer uses a custom sql statement instead of the tablename property.

Under the maps section, map layers are associated with data provider layers and their min_zoom and max_zoom values are defined. Optionally, default_tags can be setup which will be encoded into the layer. If the same tags are returned from a data provider, the data provider's values will take precedence.

[webserver]
port = ":9090"              # port to bind the web server to. defaults ":8080"

	[webserver.headers]
	Access-Control-Allow-Origin = "*"
	Cache-Control = "no-cache, no-store, must-revalidate"

[cache]                     # configure a tile cache
type = "file"               # a file cache will cache to the local file system
basepath = "/tmp/tegola"    # where to write the file cache

# register data providers
[[providers]]
name = "test_postgis"       # provider name is referenced from map layers (required)
type = "postgis"            # the type of data provider. currently only supports postgis (required)
host = "localhost"          # postgis database host (required)
port = 5432                 # postgis database port (required)
database = "tegola"         # postgis database name (required)
user = "tegola"             # postgis database user (required)
password = ""               # postgis database password (required)
srid = 3857                 # The default srid for this provider. Defaults to WebMercator (3857) (optional)
max_connections = 50        # The max connections to maintain in the connection pool. Default is 100. (optional)
ssl_mode = "prefer"        # PostgreSQL SSL mode*. Default is "disable". (optional)

	[[providers.layers]]
	name = "landuse"                    # will be encoded as the layer name in the tile
	tablename = "gis.zoning_base_3857"  # sql or tablename are required
	geometry_fieldname = "geom"         # geom field. default is geom
	id_fieldname = "gid"                # geom id field. default is gid
	srid = 4326                         # the srid of table's geo data. Defaults to WebMercator (3857)

	[[providers.layers]]
	name = "roads"                      # will be encoded as the layer name in the tile
	tablename = "gis.zoning_base_3857"  # sql or tablename are required
	geometry_fieldname = "geom"         # geom field. default is geom
	geometry_type = "linestring"        # geometry type. if not set, tables are inspected at startup to try and infer the gemetry type
	id_fieldname = "gid"                # geom id field. default is gid
	fields = [ "class", "name" ]        # Additional fields to include in the select statement.

	[[providers.layers]]
	name = "rivers"                     # will be encoded as the layer name in the tile
	geometry_fieldname = "geom"         # geom field. default is geom
	id_fieldname = "gid"                # geom id field. default is gid
	# Custom sql to be used for this layer. Note: that the geometery field is wraped
	# in a ST_AsBinary() and the use of the !BBOX! token
	sql = "SELECT gid, ST_AsBinary(geom) AS geom FROM gis.rivers WHERE geom && !BBOX!"

	[[providers.layers]]
	name = "buildings"                  # will be encoded as the layer name in the tile
	geometry_fieldname = "geom"         # geom field. default is geom
	id_fieldname = "gid"                # geom id field. default is gid
	# Custom sql to be used for this layer as a sub query. ST_AsBinary and
	# !BBOX! filter are applied automatically.
	sql = "(SELECT gid, geom, type FROM buildings WHERE scalerank = !ZOOM! LIMIT 1000) AS sub"

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

	[[maps.layers]]
	name = "landuse"                         # name is optional. If it's not defined the name of the ProviderLayer will be used.
	                                         # It can also be used to group multiple ProviderLayers under the same namespace.
	provider_layer = "test_postgis.landuse"  # must match a data provider layer
	min_zoom = 12                            # minimum zoom level to include this layer
	max_zoom = 16                            # maximum zoom level to include this layer

		[maps.layers.default_tags]           # table of default tags to encode in the tile. SQL statements will override
		class = "park"

	[[maps.layers]]
	name = "rivers"                          # name is optional. If it's not defined the name of the ProviderLayer will be used.
	                                         # It can also be used to group multiple ProviderLayers under the same namespace.
	provider_layer = "test_postgis.rivers"   # must match a data provider layer
	dont_simplify = true                     # optionally, turn off simplification for this layer. Default is false.
	dont_clip = true                         # optionally, turn off clipping for this layer. Default is false.
	min_zoom = 10                            # minimum zoom level to include this layer
	max_zoom = 18                            # maximum zoom level to include this layer

* more on PostgreSQL SSL mode here. The postgis config also supports "ssl_cert" and "ssl_key" options are required, corresponding semantically with "PGSSLKEY" and "PGSSLCERT". These options do not check for environment variables automatically. See the section below on injecting environment variables into the config.

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 = "postgis"
host = "${POSTGIS_HOST}"    # postgis database host (required)
port = "${POSTGIS_PORT}"    # recall this value must be an int
database = "${POSTGIS_DB}"
user = "tegola"
password = ""
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 support two values:

  • LAYER_SQL: print layer SQL as they are parsed from the config file.
  • EXECUTE_SQL: 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:

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 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 encode a layer with the name value set to debug and include two features:

  • debug_outline: a line feature that traces the border of the tile
  • debug_text: a point feature in the middle of the tile with the following tags:
    • zxy: 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.x to compile from source. (We support the three newest versions of Go.) To build tegola from source, make sure you have Go installed and have cloned the repository to your $GOPATH. Navigate to the repository then run the following commands:

cd cmd/tegola/
go build

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

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).

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'

Turning off CGO Tegola uses CGO for certain functionality (i.e. GeoPackge support). To build tegola without CGO use the following command:

CGO_ENABLED=0 go build

License

See license file in repo.

Documentation

Overview

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

    Index

    Constants

    View Source
    const (
    	WebMercator = 3857
    	WGS84       = 4326
    )
    View Source
    const (
    	DefaultEpislon    = 10.0
    	DefaultExtent     = 4096
    	DefaultTileBuffer = 64.0
    	MaxZ              = 22
    )

    Variables

    View Source
    var (
    	WebMercatorBounds = &geom.Extent{-20026376.39, -20048966.10, 20026376.39, 20048966.10}
    	WGS84Bounds       = &geom.Extent{-180.0, -85.0511, 180.0, 85.0511}
    )
    View Source
    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

                                                      Directories

                                                      Path Synopsis
                                                      Package atlas provides an abstraction for a collection of Maps.
                                                      Package atlas provides an abstraction for a collection of Maps.
                                                      s3
                                                      cmd
                                                      Package config loads and understands the tegola config format.
                                                      Package config loads and understands the tegola config format.
                                                      container
                                                      draw
                                                      svg
                                                      !build
                                                      !build
                                                      mapbox
                                                      tilejson
                                                      TileJSON https://github.com/mapbox/tilejson-spec
                                                      TileJSON https://github.com/mapbox/tilejson-spec
                                                      Package math contins generic math functions that we need for doing transforms.
                                                      Package math contins generic math functions that we need for doing transforms.
                                                      webmercator
                                                      Package webmercator does the translation to and from WebMercator and WGS84 Gotten from: http://wiki.openstreetmap.org/wiki/Mercator#C.23
                                                      Package webmercator does the translation to and from WebMercator and WGS84 Gotten from: http://wiki.openstreetmap.org/wiki/Mercator#C.23
                                                      mvt
                                                      vector_tile
                                                      Package vectorTile is a generated protocol buffer package.
                                                      Package vectorTile is a generated protocol buffer package.
                                                      debug
                                                      The debug provider returns features that are helpful for debugging a tile including a box for the tile edges and a point in the middle of the tile with z,x,y values encoded
                                                      The debug provider returns features that are helpful for debugging a tile including a box for the tile edges and a point in the middle of the tile with z,x,y values encoded
                                                      Package server implements the http frontend
                                                      Package server implements the http frontend
                                                      internal
                                                      cmd
                                                      Package cmd contains the Context type that can be used to cleanly terminate an application upon receiving a Termination signal.
                                                      Package cmd contains the Context type that can be used to cleanly terminate an application upon receiving a Termination signal.
                                                      env
                                                      dict is a helper function that allow one to easily get concreate values out of a map[string]interface{}
                                                      dict is a helper function that allow one to easily get concreate values out of a map[string]interface{}
                                                      log
                                                      p
                                                      pacakge p takes in values and returns a pointer to the value
                                                      pacakge p takes in values and returns a pointer to the value