TiMVT

A lightweight PostGIS based dynamic vector tile server.

Documentation: developmentseed.org/timvt/

This project is on pause while we focus on developmentseed/tipg

ref: developmentseed/timvt?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.

Features¶

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¶

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 .

PostGIS/Postgres¶

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: info.crunchydata.com/blog/dynamic-vector-tiles-from-postgis

Configuration¶

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:[email protected]:5432/postgis

Minimal Application¶

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"])

Default Application¶

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:[email protected]: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:[email protected]:5432/postgis \
    ghcr.io/developmentseed/timvt:latest

:endpoint:/docs

Contribution & Development¶

See CONTRIBUTING.md

License¶

See LICENSE

Authors¶

Created by Development Seed

Changes¶

See CHANGES.md.