A lightweight Cloud Optimized GeoTIFF dynamic tile server.

Titiler, pronounced tee-tiler (ti is the diminutive version of the french petit which means small), is lightweight service, which sole goal is to create map tiles dynamically from Cloud Optimized GeoTIFF COG.

This project is the descendant of https://github.com/developmentseed/cogeo-tiler

• Multiple TileMatrixSets via morecantile. Default is set to WebMercatorQuad which is the usual Web Mercator projection used in most of Wep Map libraries.) (see docs/TMS)
• Cloud Optimized GeoTIFF support (see docs/COG)
• SpatioTemporal Asset Catalog support (see docs/STAC)
• MosaicJSON support (Optional)
• OGC WMTS support
• Caching layer for tiles (Optional)
• AWS Lambda / ECS deployement options

$ git clone https://github.com/developmentseed/titiler.git

$ cd titiler && pip install -e .["server"]
$ uvicorn titiler.main:app --reload

Or with Docker

$ docker-compose build
$ docker-compose up 

• MosaicJSON support: pip install -e .["mosaic"]

Documentation can be found in /docs

To be able to deploy on either ECS or Lambda you first need to install more dependencies:

$ git clone https://github.com/developmentseed/titiler.git
$ cd titiler && pip install -e .["�deploy"]

The stack is deployed by the aws cdk utility. It will handle tasks such as generating a docker image set up an application load balancer and the ECS services.

$ npm install cdk -g

$ cdk bootstrap # Deploys the CDK toolkit stack into an AWS environment

# in specific region
$ cdk bootstrap aws://${AWS_ACCOUNT_ID}/eu-central-1

$ cdk synth  # Synthesizes and prints the CloudFormation template for this stack

PROJECT_NAME = os.environ.get("PROJECT", "titiler")
STAGE = os.environ.get("STAGE", "dev")

# // Service config
# Min/Max Number of ECS images
MIN_ECS_INSTANCES = 2
MAX_ECS_INSTANCES = 50

# CPU value      |   Memory value
# 256 (.25 vCPU) | 0.5 GB, 1 GB, 2 GB
# 512 (.5 vCPU)  | 1 GB, 2 GB, 3 GB, 4 GB
# 1024 (1 vCPU)  | 2 GB, 3 GB, 4 GB, 5 GB, 6 GB, 7 GB, 8 GB
# 2048 (2 vCPU)  | Between 4 GB and 16 GB in 1-GB increments
# 4096 (4 vCPU)  | Between 8 GB and 30 GB in 1-GB increments
TASK_CPU = 1024
TASK_MEMORY = 2048

$ cdk deploy titiler-ecs-dev # Deploys the stack(s) titiler-ecs-dev in stack/app.py

Titiler is built on top of FastAPI which is a modern, fast (high-performance), web framework for building APIs. It doesn't work natively with AWS Lambda and API Gateway because it needs a way to handler event and context instead of raw HTML requests. This is possible by wrapping the FastAPI app with the awesome mangum module.

from mangum import Mangum
from titiler.main import app

handler = Mangum(app, enable_lifespan=False)

The Lambda stack is also deployed by the aws cdk utility. It will create the package.zip and handle the creation of the lambda function and the API Gateway HTTP endpoint.

$ npm install cdk -g

$ cdk bootstrap # Deploys the CDK toolkit stack into an AWS environment

# in specific region
$ cdk bootstrap aws://${AWS_ACCOUNT_ID}/eu-central-1

$ cdk synth  # Synthesizes and prints the CloudFormation template for this stack

PROJECT_NAME = "titiler"
PROJECT_NAME = os.environ.get("PROJECT", "titiler")
...
TIMEOUT: int = 10
MEMORY: int = 512
MAX_CONCURRENT: int = 500

$ cdk deploy titiler-lambda-dev # Deploys the stack(s) titiler-lambda-dev in stack/app.py

# in specific region
$ AWS_DEFAULT_REGION=eu-central-1 AWS_REGION=eu-central-1 cdk deploy titiler-lambda-dev 

titiler/                         - titiler python module.
 ├── custom/                     - Custom colormap and TMS grids.
 ├── db/                         - db related stuff.
 ├── endpoints                   - api routes.
 │   ├── cog.py                  - COG related endpoints.
 │   ├── stac.py                 - STAC related endpoints.
 │   ├── mosaic.py               - MosaicJSON related endpoints.
 │   └── tms.py                  - TileMatrixSets endpoints.
 ├── models/                     - pydantic models for this application.
 ├── ressources/                 - application ressources (enums, constants, ...).
 ├── templates/                  - html/xml models.
 ├── dependencies.py             - API dependencies.
 ├── errors.py                   - API custom error handling.
 ├── main.py                     - FastAPI application creation and configuration.
 ├── settings.py                 - application configuration.
 ├── utils.py                    - utility functions.
 │
stack/
 ├── app.py                      - AWS Stack definition (vpc, cluster, ecs, alb ...)
 ├── config.py                   - Optional parameters for the stack definition [EDIT THIS]
 │
Dockerfiles/
 ├── ecs/
 │   └── Dockerfile              - Dockerfile to build the ECS service image.
 ├── lambda/
 │   └── Dockerfile              - Dockerfile to build the Lambda service image.
 │
lambda/
 │   └── handler.py              - Mangum adaptator fro AWS Lambda.
 │
docs/                            - Project documentations.

Issues and pull requests are more than welcome.

dev install

$ git clone https://github.com/developmentseed/titiler.git
$ cd titiler
$ pip install -e .[dev]

Python3.7 only

This repo is set to use pre-commit to run isort, mypy, flake8, pydocstring and black ("uncompromising Python code formatter") when commiting new code.

$ pre-commit install

Created by Development Seed