updated readme for v0.4.0 release

README.md

@@ -5,91 +5,114 @@
 [![Godoc](http://img.shields.io/badge/godoc-reference-blue.svg?style=flat)](https://godoc.org/github.com/terranodo/tegola)
 [![license](http://img.shields.io/badge/license-MIT-red.svg?style=flat)](https://github.com/terranodo/tegola/blob/master/LICENSE.md)
 
-Tegola is a high performance vector tile server delivering [Mapbox Vector Tiles](https://github.com/mapbox/vector-tile-spec) leveraging PostGIS as the data provider.
+Tegola is a vector tile server delivering [Mapbox Vector Tiles](https://github.com/mapbox/vector-tile-spec) leveraging PostGIS as the data provider.
 
-## Near term goals
-- [X] Support for transcoding WKB to MVT.
-- [x] Support for `/z/x/y` web mapping URL scheme.
-- [x] Support for PostGIS data provider.
+## Features
+- Native geometry processing (simplification, clipping, make valid, intersection, contains, scaling, translation)
+- [Mapbox Vector Tile v2 specification](https://github.com/mapbox/vector-tile-spec) compliant .
+- Embedded viewer with auto generated style for quick data visualization and inspection.
+- Support for PostGIS as a data provider. Extensible to support additional data providers.
+- Local filesystem caching. Extensible design to support additional cache backends.
+- Parallelized tile serving and geometry processing.
+- Support for Web Mercator (3857) and WGS84 (4326) projections.
 
 ## Running Tegola
-1. Download the appropriate binary of tegola for your platoform via the [release page](https://github.com/terranodo/tegola/releases).
+1. Download the appropriate binary of tegola for your platform via the [release page](https://github.com/terranodo/tegola/releases).
 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:
+## Server Endpoints
+
+```
+/
+```
+
+The server root will display a built in viewer with an auto generated style. 
+
 
 ```
 /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.
 
-### Additional endpoints
+
+```
+/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
 ```
-Will return a JSON encoded list of the server's configured maps and layers with various attributes. An example response:
 
-```json
-{
-	"maps": [{
-		"name": "zoning",
-		"uri": "/maps/zoning",
-		"layers": [{
-			"name": "landuse",
-			"minZoom": 12,
-			"maxZoom": 16
-		}]
-	}]
-}
+Return a JSON encoded list of the server's configured maps and layers with various attributes.
 
+```
+/capabilities/:map_name
 ```
 
+Return [TileJSON](https://github.com/mapbox/tilejson-spec) details about the map.
+
+```
+/capabilities/:map_name/style.json
+```
+
+Return an auto generated [Mapbox GL Style](https://www.mapbox.com/mapbox-gl-js/style-spec/) for the configured map.
+
+
 ## Configuration
 The tegola config file uses the [TOML](https://github.com/toml-lang/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.
+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.
 
 ```toml
 
 [webserver]
-port = ":9090"
+port = ":9090"				# port to bind the web server to. defaults ":8080"
+
+[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
-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)
+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)
 
 	[[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.
+	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
+	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
@@ -123,16 +146,20 @@ name = "zoning"							# used in the URL to reference this map (/maps/:map_name)
 	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
+```
 
+### Supported PostGIS SQL tokens
+The following tokens are supported in custom SQL queries for the PostGIS data provider:
 
-```
+- `!BBOX!` - [required] Will convert the z/x/y values into a bounding box to query the feature table with.
+- `!ZOOM!` - [optional] Pass in the zoom value for the request. Useful for filtering feature results by zoom.
 
-## Command flags
-Tegola currently supports the following command flags:
+## Command line flags
+Tegola 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-file` - Path to write webserver tile request 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.
@@ -143,14 +170,13 @@ Tegola currently supports the following command flags:
 ## Debugging
 
 ### Environment Variables
-The following environment variables can be used for debugging the tegola server:
+The following environment variables can be used for debugging:
 
 `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
 
 ```bash
@@ -181,10 +207,5 @@ go build -o tegola
 
 You will now have a binary named `tegola` in the current directory which is [ready for running](#running-tegola).
 
-
-## Specifications
-- [Well Known Binary (WKB)](http://edndoc.esri.com/arcsde/9.1/general_topics/wkb_representation.htm)
-- [Mapbox Vector Tile (MVT) 2.1](https://github.com/mapbox/vector-tile-spec/tree/master/2.1)
-
 ## License
 See [license](LICENSE.md) file in repo.