Terracotta is a pure Python tile server that runs as a WSGI app on a dedicated webserver or as a serverless app on AWS Lambda. It is built on a modern Python stack, powered by awesome open-source software such as Flask, Zappa, and Rasterio.
Read the docs | Explore the API | Satlas, powered by Terracotta
Why Terracotta?
- It is trivial to get going. Got a folder full of
cloud-optimized GeoTiffs in different
projections you want to have a look at in your browser?
terracotta serve -r {name}.tifandterracotta connect localhost:5000get you there. - We make minimal assumptions about your data, so you stay in charge. Keep using the tools you know and love to create and organize your data, Terracotta serves it exactly as it is.
- Serverless deployment is a first-priority use case, so you donโt have to worry about maintaining or scaling your architecture.
- Terracotta instances are self-documenting. Everything the frontend needs to know about your data is accessible from only a handful of API endpoints.
The Terracotta workflow
1. Optimize raster files
$ ls -lh
total 1.4G
-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:45 S2A_20160724_135032_27XVB_B02.tif
-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:45 S2A_20160724_135032_27XVB_B03.tif
-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:46 S2A_20160724_135032_27XVB_B04.tif
-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:56 S2A_20170831_171901_25XEL_B02.tif
-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:57 S2A_20170831_171901_25XEL_B03.tif
-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:57 S2A_20170831_171901_25XEL_B04.tif
$ terracotta optimize-rasters *.tif -o optimized/
Optimizing rasters: 100%|โโโโโโโโโโโโโโโโโโโโโโโโโโ| [05:16<00:00, file=S2A_20170831_...25XEL_B04.tif]2. Create a database from file name pattern
$ terracotta ingest optimized/S2A_{date}_{}_{tile}_{band}.tif -o greenland.sqlite
Ingesting raster files: 100%|โโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโโ| 6/6 [00:49<00:00, 8.54s/it]3. Serve it up
$ terracotta serve -d greenland.sqlite
* Serving Flask app "terracotta.server" (lazy loading)
* Environment: production
WARNING: Do not use the development server in a production environment.
Use a production WSGI server instead.
* Debug mode: off
* Running on http://localhost:5000/ (Press CTRL+C to quit)4. Explore the running server
Manually
You can use any HTTP-capable client, such as curl.
$ curl localhost:5000/datasets?tile=25XEL
{"page":0,"limit":100,"datasets":[{"date":"20170831","tile":"25XEL","band":"B02"},{"date":"20170831","tile":"25XEL","band":"B03"},{"date":"20170831","tile":"25XEL","band":"B04"}]}Modern browsers (e.g. Chrome or Firefox) will render the JSON as a tree.
Interactively
Terracotta also includes a web client. You can start the client (assuming the server is running at http://localhost:5000) using
$ terracotta connect localhost:5000
* Serving Flask app "terracotta.client" (lazy loading)
* Environment: production
WARNING: Do not use the development server in a production environment.
Use a production WSGI server instead.
* Debug mode: off
* Running on http://127.0.0.1:5100/ (Press CTRL+C to quit)Then open the client page (http://127.0.0.1:5100/ in this case) in your browser.
Development
We gladly accept bug reports
and pull requests via GitHub.
For your code to be useful, make sure that it is covered by tests and that
it satisfies our linting practices (via mypy and flake8).
To run the tests, just install the necessary dependencies via
$ pip install -e .[test]Then, you can run
$ pytestfrom the root of the repository.