tegola

README

Tegola

Tegola is a high performance vector tile server delivering Mapbox Vector Tiles leveraging PostGIS as the data provider.

Near term goals

• Support for transcoding WKB to MVT.
• Support for /z/x/y web mapping URL scheme.
• Support for PostGIS data provider.

Running Tegola

1. Download the appropriate binary of tegola for your platoform via the release page.
2. Setup your config file and run. Tegola expects a config.toml to be in the same directory as the binary. You can set a different location for the config.toml using a command flag:

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

URL Scheme

Tegola uses the following URL scheme:

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

• :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.

Additional endpoints

/capabilities

Will return a JSON encoded list of the server's configured maps and layers with various attributes. An example response:

{
	"maps": [{
		"name": "zoning",
		"uri": "/maps/zoning",
		"layers": [{
			"name": "landuse",
			"minZoom": 12,
			"maxZoom": 16
		}]
	}]
}

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 dataprovider layers and their min_zoom and max_zoom values are defined. Optionally, custom_tags can be setup which will be encoded into the layer. If the same tags are returned from a data provider, the dataprovider's values will take precidence.

[webserver]
port = ":9090"

# register data providers
[[providers]]
name = "test_postgis"	# provider name is referenced from map layers
type = "postgis"		# the type of data provider. currently only supports postgis
host = "localhost"		# postgis database host
port = 5432				# postgis database port
database = "tegola" 	# postgis database name
user = "tegola"			# postgis database user
password = ""			# postgis database password
srid = 3857             # The default srid for this provider. If not provided it will be WebMercator (3857)

	[[providers.layers]]
	name = "landuse" 					# will be encoded as the layer name in the tile
	tablename = "gis.zoning_base_3857" 	# sql or table_name 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.


	[[providers.layers]]
	name = "roads" 					# will be encoded as the layer name in the tile
	tablename = "gis.zoning_base_3857" 	# sql or table_name are required
	geometry_fieldname = "geom"			# geom field. default is geom
	id_fieldname = "gid"				# geom id field. default is gid
	fields = [ "class", "name" ]        # Additional fields to include in the select statement.
	srid = 3857                         # the srid of table's geo data. Don't need to specify this as it will inherit this from the provider.

	[[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, as tegola only understand wkb.
	sql = """
		SELECT
			gid,
			ST_AsBinary(geom) AS geom
		FROM
			gis.rivers
		WHERE
			geom && !BBOX!
	"""

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

	[[maps.layers]]
	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]]
	provider_layer = "test_postgis.rivers"	# must match a data provider layer
	min_zoom = 10						# minimum zoom level to include this layer
	max_zoom = 18						# maximum zoom level to include this layer

Command flags

Tegola currently supports the following command flags:

• config - Location of config file in TOML format. Can be absolute, relative or remote over http(s).
• port - Port for the webserver to bind to. i.e. :8080
• log-file - Path to write webserver access logs
• log-format - The format that the logger will log with. Available fields:
  • {{.Time}} : The current Date Time in RFC 2822 format.
  • {{.RequestIP}} : The IP address of the the requester.
  • {{.Z}} : The Zoom level.
  • {{.X}} : The X Coordinate.
  • {{.Y}} : The Y Coordinate.

Debugging

Environment Variables

The following environment variables can be used for debugging the tegola server:

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

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

Client side

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.7+ to compile from source. To build tegola from source, make sure you have Go installed and have cloned the repository to your $GOPATH or $GOROOT. Navigate to the repository then run the following commands:

cd cmd/tegola/
go build -o tegola *.go

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

Specifications

• Well Known Binary (WKB)
• Mapbox Vector Tile (MVT) 2.1

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
• type BoundingBox
• type Collection
• type Geometry
• type LineString
• type MultiLine
• type MultiPoint
• type MultiPolygon
• type Point
• type Point3
• type Polygon
• type Tile
  • func (t *Tile) BoundingBox() BoundingBox
  • func (t *Tile) Deg2Num() (x, y int)
  • func (t *Tile) Num2Deg() (lat, lng float64)
  • func (t *Tile) ZRes() float64

Constants

const (
	WebMercator = 3857
	WGS84       = 4326
)

const (
	ProviderPostGIS string = "postgis"
)

Types

type BoundingBox

type BoundingBox struct {
	Minx, Miny, Maxx, Maxy float64
}

BoundingBox defines the extent of a tile

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    int
	X    int
	Y    int
	Lat  float64
	Long float64
}

Tile slippy map tilenames

http://wiki.openstreetmap.org/wiki/Slippy_map_tilenames

func (*Tile) BoundingBox

func (t *Tile) BoundingBox() BoundingBox

BoundingBox returns the bound box coordinates for upper left (ulx, uly) and lower right (lrx, lry) in web mercator projection ported from: https://raw.githubusercontent.com/mapbox/postgis-vt-util/master/postgis-vt-util.sql

func (*Tile) Deg2Num

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

func (*Tile) Num2Deg

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

func (*Tile) ZRes

func (t *Tile) ZRes() float64

ZRes takes a web mercator zoom level and returns the pixel resolution for that

scale, assuming 256x256 pixel tiles. Non-integer zoom levels are accepted.
ported from: https://raw.githubusercontent.com/mapbox/postgis-vt-util/master/postgis-vt-util.sql