Intro
TiTiler
is a set of python modules whose goal are to help users in creating a dynamic tile server. To learn more about dynamic tiling
please refer to the docs.
Users can choose to extend or use TiTiler
as it is.
Default Application¶
TiTiler
comes with a default (complete) application with support for COG, STAC, and MosaicJSON. You can install and start the application locally by doing:
$ pip install uvicorn titiler.application
$ uvicorn titiler.application.main:app
> INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
See default endpoints documentation pages:
/cog
- Cloud Optimized GeoTIFF/mosaicjson
- MosaicJSON/stac
- Spatio Temporal Asset Catalog/tms
- TileMatrixSets
Settings¶
The default application can be customized using environment variables defined in titiler.application.settings.ApiSettings
class. Each variable needs to be prefixed with TITILER_API_
.
NAME
(str): name of the application. Defaults totitiler
.CORS_ORIGINS
(str,,
delimited origins): allowed CORS origin. Defaults to*
.CACHECONTROL
(str): Cache control header to add to responses. Defaults to"public, max-age=3600"
.ROOT_PATH
(str): path behind proxy.DEBUG
(str): addsLoggerMiddleware
andTotalTimeMiddleware
in the middleware stack.DISABLE_COG
(bool): disable/cog
endpoints.DISABLE_STAC
(bool): disable/stac
endpoints.DISABLE_MOSAIC
(bool): disable/mosaic
endpoints.LOWER_CASE_QUERY_PARAMETERS
(bool): transform all query-parameters to lower case (see developmentseed/titiler!321).
Development¶
To install and run Titiler
from sources and for developing the Titiler
code itself:
$ git clone https://github.com/developmentseed/titiler.git
$ cd titiler
$ pip install uvicorn -e src/titiler/core -e src/titiler/mosaic -e src/titiler/application
$ uvicorn titiler.application.main:app --reload
> INFO: Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
> INFO: Started reloader process [66665] using statreload
Customized, minimal app¶
TiTiler
has been developed so users can build their own app using only the portions they need. Using TilerFactories, users can create a fully customized application with only the endpoints needed.
When building a custom application, you may wish to only install the core
and/or mosaic
modules. To install these from PyPI:
$ pip install -U pip
$ pip install titiler.core
$ pip install titiler.mosaic
These can then be used like:
from titiler.core.factory import TilerFactory
from titiler.core.errors import DEFAULT_STATUS_CODES, add_exception_handlers
from fastapi import FastAPI
app = FastAPI()
cog = TilerFactory()
app.include_router(cog.router)
add_exception_handlers(app, DEFAULT_STATUS_CODES)
Extending TiTiler's app¶
If you want to include all of Titiler's built-in endpoints, but also include customized endpoints, you can import and extend the app directly.
$ pip install -U pip
$ pip install titiler.application # also installs titiler.core and titiler.mosaic
These can then be used like:
# Add private COG endpoints requiring token validation
from fastapi import APIRouter, Depends, HTTPException, Security
from fastapi.security.api_key import APIKeyQuery
from titiler.application.main import app
from titiler.core.factory import TilerFactory
api_key_query = APIKeyQuery(name="access_token", auto_error=False)
def token_validation(access_token: str = Security(api_key_query)):
"""stupid token validation."""
if not access_token:
raise HTTPException(status_code=403, detail="Missing `access_token`")
if not access_token == "token":
raise HTTPException(status_code=403, detail="Invalid `access_token`")
return True
# Custom router with token dependency
router = APIRouter(dependencies=[Depends(token_validation)])
tiler = TilerFactory(router_prefix="private/cog", router=router)
app.include_router(tiler.router, prefix="/private/cog", tags=["Private"])
More on customization