timvt

Name	timvt JSON
Version	0.7.0 JSON
	download
home_page	None
Summary	A lightweight PostGIS based dynamic vector tile server.
upload_time	2022-06-09 09:16:48
maintainer	None
docs_url	None
author	None
requires_python	>=3.7
license	None
keywords	fastapi mvt postgis
VCS
bugtrack_url
requirements	No requirements were recorded.
Travis-CI	No Travis.
coveralls test coverage	No coveralls.

            <p align="center">
  <img width="500" src="https://user-images.githubusercontent.com/10407788/172734314-a2b47e51-b919-4aa3-a7cf-33e57f3c2852.png"/>
  <p align="center">A lightweight PostGIS based dynamic vector tile server.</p>
</p>

<p align="center">
  <a href="https://github.com/developmentseed/timvt/actions?query=workflow%3ACI" target="_blank">
      <img src="https://github.com/developmentseed/timvt/workflows/CI/badge.svg" alt="Test">
  </a>
  <a href="https://codecov.io/gh/developmentseed/timvt" target="_blank">
      <img src="https://codecov.io/gh/developmentseed/timvt/branch/master/graph/badge.svg" alt="Coverage">
  </a>
  <a href="https://pypi.org/project/timvt" target="_blank">
      <img src="https://img.shields.io/pypi/v/timvt?color=%2334D058&label=pypi%20package" alt="Package version">
  </a>
  <a href="https://github.com/developmentseed/timvt/blob/master/LICENSE" target="_blank">
      <img src="https://img.shields.io/github/license/developmentseed/timvt.svg" alt="License">

  </a>
</p>

---

**Documentation**: <a href="https://developmentseed.org/timvt/" target="_blank">https://developmentseed.org/timvt/</a>

**Source Code**: <a href="https://github.com/developmentseed/timvt" target="_blank">https://github.com/developmentseed/timvt</a>

---

`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:password@0.0.0.0: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.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: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`

![](https://user-images.githubusercontent.com/10407788/136578935-e1170784-5a4f-4946-842c-9a6de39165f6.jpg)


## 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](<http://developmentseed.org>)

## Changes

See [CHANGES.md](https://github.com/developmentseed/timvt/blob/master/CHANGES.md).


            

Raw data

            {
    "_id": null,
    "home_page": null,
    "name": "timvt",
    "maintainer": null,
    "docs_url": null,
    "requires_python": ">=3.7",
    "maintainer_email": null,
    "keywords": "FastAPI,MVT,POSTGIS",
    "author": null,
    "author_email": "Vincent Sarago <vincent@developmentseed.com>",
    "download_url": "https://files.pythonhosted.org/packages/a9/55/0558dc40bcb80c03d23b91ea6812f2a5cd78f831d04eec7ce0388ddb58f3/timvt-0.7.0.tar.gz",
    "platform": null,
    "description": "<p align=\"center\">\n  <img width=\"500\" src=\"https://user-images.githubusercontent.com/10407788/172734314-a2b47e51-b919-4aa3-a7cf-33e57f3c2852.png\"/>\n  <p align=\"center\">A lightweight PostGIS based dynamic vector tile server.</p>\n</p>\n\n<p align=\"center\">\n  <a href=\"https://github.com/developmentseed/timvt/actions?query=workflow%3ACI\" target=\"_blank\">\n      <img src=\"https://github.com/developmentseed/timvt/workflows/CI/badge.svg\" alt=\"Test\">\n  </a>\n  <a href=\"https://codecov.io/gh/developmentseed/timvt\" target=\"_blank\">\n      <img src=\"https://codecov.io/gh/developmentseed/timvt/branch/master/graph/badge.svg\" alt=\"Coverage\">\n  </a>\n  <a href=\"https://pypi.org/project/timvt\" target=\"_blank\">\n      <img src=\"https://img.shields.io/pypi/v/timvt?color=%2334D058&label=pypi%20package\" alt=\"Package version\">\n  </a>\n  <a href=\"https://github.com/developmentseed/timvt/blob/master/LICENSE\" target=\"_blank\">\n      <img src=\"https://img.shields.io/github/license/developmentseed/timvt.svg\" alt=\"License\">\n\n  </a>\n</p>\n\n---\n\n**Documentation**: <a href=\"https://developmentseed.org/timvt/\" target=\"_blank\">https://developmentseed.org/timvt/</a>\n\n**Source Code**: <a href=\"https://github.com/developmentseed/timvt\" target=\"_blank\">https://github.com/developmentseed/timvt</a>\n\n---\n\n`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.\n\nBuilt 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.\n\n`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.\n\n## Features\n\n- 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.)\n- Built with [FastAPI](https://fastapi.tiangolo.com)\n- Table and Function layers\n- Async API using [asyncpg](https://github.com/MagicStack/asyncpg)\n\n\n## Install\n\nInstall `TiMVT` from pypi\n```bash\n# update pip (optional)\npython -m pip install pip -U\n\n# install timvt\npython -m pip install timvt\n```\n\nor install from source:\n\n```bash\n$ git clone https://github.com/developmentseed/timvt.git\n$ cd timvt\n$ python -m pip install -e .\n```\n\n## PostGIS/Postgres\n\n`TiMVT` rely mostly on [`ST_AsMVT`](https://postgis.net/docs/ST_AsMVT.html) function and will need PostGIS >= 2.5.\n\nIf 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\n\n### Configuration\n\nTo 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.\n\nExample of `.env` file can be found in [.env.example](https://github.com/developmentseed/timvt/blob/master/.env.example)\n```\nPOSTGRES_USER=username\nPOSTGRES_PASS=password\nPOSTGRES_DBNAME=postgis\nPOSTGRES_HOST=0.0.0.0\nPOSTGRES_PORT=5432\n\n# Or you can also define the DATABASE_URL directly\nDATABASE_URL=postgresql://username:password@0.0.0.0:5432/postgis\n```\n\n## Minimal Application\n\n```python\nfrom timvt.db import close_db_connection, connect_to_db\nfrom timvt.factory import VectorTilerFactory\nfrom timvt.layer import FunctionRegistry\nfrom fastapi import FastAPI, Request\n\n# Create Application.\napp = FastAPI()\n\n# Add Function registry to the application state\napp.state.function_catalog = FunctionRegistry()\n\n# Register Start/Stop application event handler to setup/stop the database connection\n# and populate `app.state.table_catalog`\n@app.on_event(\"startup\")\nasync def startup_event():\n    \"\"\"Application startup: register the database connection and create table list.\"\"\"\n    await connect_to_db(app)\n\n\n@app.on_event(\"shutdown\")\nasync def shutdown_event():\n    \"\"\"Application shutdown: de-register the database connection.\"\"\"\n    await close_db_connection(app)\n\n# Register endpoints.\nmvt_tiler = VectorTilerFactory(\n    with_tables_metadata=True,\n    with_functions_metadata=True,  # add Functions metadata endpoints (/functions.json, /{function_name}.json)\n    with_viewer=True,\n)\napp.include_router(mvt_tiler.router, tags=[\"Tiles\"])\n```\n\n## Default Application\n\nWhile we encourage users to write their own application using `TiMVT` package, we also provide a default `production ready` application:\n\n```bash\n# Install timvt dependencies and Uvicorn (a lightning-fast ASGI server)\n$ pip install timvt 'uvicorn[standard]>=0.12.0,<0.14.0'\n\n# Set Database URL environment variable so TiMVT can access it\n$ export DATABASE_URL=postgresql://username:password@0.0.0.0:5432/postgis\n\n# Launch Demo Application\n$ uvicorn timvt.main:app --reload\n```\n\nYou can also use the official docker image\n\n```\n$ docker run \\\n    -p 8081:8081 \\\n    -e PORT=8081 \\\n    -e DATABASE_URL=postgresql://username:password@0.0.0.0:5432/postgis \\\n    ghcr.io/developmentseed/timvt:latest\n```\n\n`:endpoint:/docs`\n\n![](https://user-images.githubusercontent.com/10407788/136578935-e1170784-5a4f-4946-842c-9a6de39165f6.jpg)\n\n\n## Contribution & Development\n\nSee [CONTRIBUTING.md](https://github.com/developmentseed/timvt/blob/master/CONTRIBUTING.md)\n\n## License\n\nSee [LICENSE](https://github.com/developmentseed/timvt/blob/master/LICENSE)\n\n## Authors\n\nCreated by [Development Seed](<http://developmentseed.org>)\n\n## Changes\n\nSee [CHANGES.md](https://github.com/developmentseed/timvt/blob/master/CHANGES.md).\n\n",
    "bugtrack_url": null,
    "license": null,
    "summary": "A lightweight PostGIS based dynamic vector tile server.",
    "version": "0.7.0",
    "split_keywords": [
        "fastapi",
        "mvt",
        "postgis"
    ],
    "urls": [
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "c4b780c68b9648498dad12e4d01e00cbba7bd60bcbad6ccef8804dfc41da9eb9",
                "md5": "0ecbc4beddcfd1510be991af9f05f8c2",
                "sha256": "d7f04b7e797ff2888559748ab1148fe532767069624c7f8b4a466c6bc7bbf090"
            },
            "downloads": -1,
            "filename": "timvt-0.7.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "0ecbc4beddcfd1510be991af9f05f8c2",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.7",
            "size": 24802,
            "upload_time": "2022-06-09T09:16:46",
            "upload_time_iso_8601": "2022-06-09T09:16:46.109424Z",
            "url": "https://files.pythonhosted.org/packages/c4/b7/80c68b9648498dad12e4d01e00cbba7bd60bcbad6ccef8804dfc41da9eb9/timvt-0.7.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "a9550558dc40bcb80c03d23b91ea6812f2a5cd78f831d04eec7ce0388ddb58f3",
                "md5": "2c0f27df204e382185ac545583e69b9b",
                "sha256": "ebd251d4df217e840f9f36271e91b0d48a1c94763d6982429edce01bc8a6d304"
            },
            "downloads": -1,
            "filename": "timvt-0.7.0.tar.gz",
            "has_sig": false,
            "md5_digest": "2c0f27df204e382185ac545583e69b9b",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.7",
            "size": 24599,
            "upload_time": "2022-06-09T09:16:48",
            "upload_time_iso_8601": "2022-06-09T09:16:48.025141Z",
            "url": "https://files.pythonhosted.org/packages/a9/55/0558dc40bcb80c03d23b91ea6812f2a5cd78f831d04eec7ce0388ddb58f3/timvt-0.7.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2022-06-09 09:16:48",
    "github": false,
    "gitlab": false,
    "bitbucket": false,
    "lcname": "timvt"
}