Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/developmentseed/timvt
PostGIS based Vector Tile server.
https://github.com/developmentseed/timvt
asyncio fastapi postgis postgresql python tile-server vector vector-tile-server vector-tiles
Last synced: 5 days ago
JSON representation
PostGIS based Vector Tile server.
- Host: GitHub
- URL: https://github.com/developmentseed/timvt
- Owner: developmentseed
- License: mit
- Created: 2020-05-14T01:47:51.000Z (over 4 years ago)
- Default Branch: master
- Last Pushed: 2024-07-11T04:17:24.000Z (7 months ago)
- Last Synced: 2025-01-21T08:05:48.280Z (12 days ago)
- Topics: asyncio, fastapi, postgis, postgresql, python, tile-server, vector, vector-tile-server, vector-tiles
- Language: PLpgSQL
- Homepage: https://developmentseed.org/timvt/
- Size: 10.2 MB
- Stars: 190
- Watchers: 14
- Forks: 27
- Open Issues: 9
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGES.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
Awesome Lists containing this project
README
A lightweight PostGIS based dynamic vector tile server.
---
**Documentation**: https://developmentseed.org/timvt/
**Source Code**: https://github.com/developmentseed/timvt
---
> :warning: This project is on pause while we focus on [`developmentseed/tipg`](https://github.com/developmentseed/tipg) :warning:
>
> ref: https://github.com/developmentseed/timvt/discussions/96
---
`TiMVT`, pronounced **tee-MVT**, is a python package which helps creating lightweight [Vector Tiles](https://github.com/mapbox/vector-tile-spec) service from [PostGIS](https://github.com/postgis/postgis) Database.
Built on top of the *modern and fast* [FastAPI](https://fastapi.tiangolo.com) 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](https://github.com/urbica/martin) and [CrunchyData/pg_tileserv](https://github.com/CrunchyData/pg_tileserv) projects.
## Features
- Multiple TileMatrixSets via [morecantile](https://github.com/developmentseed/morecantile). Default is set to WebMercatorQuad which is the usual Web Mercator projection used in most of Wep Map libraries.)
- Built with [FastAPI](https://fastapi.tiangolo.com)
- Table and Function layers
- Async API using [asyncpg](https://github.com/MagicStack/asyncpg)
## Install
Install `TiMVT` from pypi
```bash
# update pip (optional)
python -m pip install pip -U
# install timvt
python -m pip install timvt
```
or install from source:
```bash
$ git clone https://github.com/developmentseed/timvt.git
$ cd timvt
$ python -m pip install -e .
```
## PostGIS/Postgres
`TiMVT` rely mostly on [`ST_AsMVT`](https://postgis.net/docs/ST_AsMVT.html) 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
### Configuration
To be able to create Vector Tile, the application will need access to the PostGIS database. `TiMVT` uses [pydantic](https://pydantic-docs.helpmanual.io/usage/settings/)'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](https://github.com/developmentseed/timvt/blob/master/.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
```python
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:
```bash
# 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](https://github.com/developmentseed/timvt/blob/master/CONTRIBUTING.md)
## License
See [LICENSE](https://github.com/developmentseed/timvt/blob/master/LICENSE)
## Authors
Created by [Development Seed]()
## Changes
See [CHANGES.md](https://github.com/developmentseed/timvt/blob/master/CHANGES.md).