A lightweight PostGIS based dynamic vector tile server.
Test Coverage Package version License
Documentation: https://developmentseed.org/timvt/
Source Code: https://github.com/developmentseed/timvt
⚠️ This project is on pause while we focus ondevelopmentseed/tipg⚠️ ref: #96
TiMVT, pronounced tee-MVT, is a python package which helps creating lightweight Vector Tiles service from PostGIS Database.
Built on top of the modern and fast FastAPI framework, timvt is written in Python using async/await asynchronous code to improve the performances and handle heavy loads.
TiMVT is mostly inspired from the awesome urbica/martin and CrunchyData/pg_tileserv projects.
- Multiple TileMatrixSets via morecantile. Default is set to WebMercatorQuad which is the usual Web Mercator projection used in most of Wep Map libraries.)
- Built with FastAPI
- Table and Function layers
- Async API using asyncpg
Install TiMVT from pypi
# update pip (optional) python -m pip install pip -U # install timvt python -m pip install timvt
or install from source:
$ git clone https://github.com/developmentseed/timvt.git $ cd timvt $ python -m pip install -e .
TiMVT rely mostly on ST_AsMVT function and will need PostGIS >= 2.5.
If you want more info about ST_AsMVT function or on the subject of creating Vector Tile from PostGIS, please read this great article from Paul Ramsey: https://info.crunchydata.com/blog/dynamic-vector-tiles-from-postgis
To be able to create Vector Tile, the application will need access to the PostGIS database. TiMVT uses pydantic's configuration pattern which make use of environment variable and/or .env file to pass variable to the application.
Example of .env file can be found in .env.example
POSTGRES_USER=username
POSTGRES_PASS=password
POSTGRES_DBNAME=postgis
POSTGRES_HOST=0.0.0.0
POSTGRES_PORT=5432
# Or you can also define the DATABASE_URL directly
DATABASE_URL=postgresql://username:password@0.0.0.0:5432/postgis
from timvt.db import close_db_connection, connect_to_db from timvt.factory import VectorTilerFactory from timvt.layer import FunctionRegistry from fastapi import FastAPI, Request # Create Application. app = FastAPI() # Add Function registry to the application state app.state.timvt_function_catalog = FunctionRegistry() # Register Start/Stop application event handler to setup/stop the database connection # and populate `app.state.table_catalog` @app.on_event("startup") async def startup_event(): """Application startup: register the database connection and create table list.""" await connect_to_db(app) @app.on_event("shutdown") async def shutdown_event(): """Application shutdown: de-register the database connection.""" await close_db_connection(app) # Register endpoints. mvt_tiler = VectorTilerFactory( with_tables_metadata=True, with_functions_metadata=True, # add Functions metadata endpoints (/functions.json, /{function_name}.json) with_viewer=True, ) app.include_router(mvt_tiler.router, tags=["Tiles"])
While we encourage users to write their own application using TiMVT package, we also provide a default production ready application:
# Install timvt dependencies and Uvicorn (a lightning-fast ASGI server) $ pip install timvt 'uvicorn[standard]>=0.12.0,<0.14.0' # Set Database URL environment variable so TiMVT can access it $ export DATABASE_URL=postgresql://username:password@0.0.0.0:5432/postgis # Launch Demo Application $ uvicorn timvt.main:app --reload
You can also use the official docker image
$ docker run \
-p 8081:8081 \
-e PORT=8081 \
-e DATABASE_URL=postgresql://username:password@0.0.0.0:5432/postgis \
ghcr.io/developmentseed/timvt:latest
:endpoint:/docs
See CONTRIBUTING.md
See LICENSE
Created by Development Seed
See CHANGES.md.