[](https://github.com/DHI/terracotta/actions/workflows/test.yml)
[](https://terracotta-python.readthedocs.io/en/latest/?badge=latest)
[](https://codecov.io/gh/DHI-GRAS/terracotta)
[](https://github.com/DHI/terracotta/releases)
[](https://pypi.org/project/terracotta)
[](https://github.com/DHI/terracotta/blob/main/LICENSE)
[](https://pypi.org/project/terracotta)
[](#)
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](http://flask.pocoo.org), [Zappa](https://github.com/Miserlou/Zappa),
and [Rasterio](https://github.com/mapbox/rasterio).
[Read the docs](https://terracotta-python.readthedocs.io/en/latest) |
[Try the demo](https://terracotta-demo-frontend.orangebeach-11aa4896.westeurope.azurecontainerapps.io/) |
[Explore the API](https://terracotta-python.readthedocs.io/en/latest/apidoc.html) |
[Satlas, powered by Terracotta](http://satlas.dk) |
[Docker Image](https://hub.docker.com/r/dhigras/terracotta/tags)
## Why Terracotta?
- It is trivial to get going. Got a folder full of
[cloud-optimized GeoTiffs](https://www.cogeo.org/) in different
projections you want to have a look at in your browser?
`terracotta serve -r {name}.tif` and
`terracotta connect localhost:5000` get 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
```bash
$ 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
```bash
$ 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
```bash
$ 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`.
```bash
$ 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
```bash
$ 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](https://github.com/DHI/terracotta/issues)
and [pull requests](https://github.com/DHI/terracotta/pulls) 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
```bash
$ pip install -e .[test]
```
Then, you can run
```bash
$ pytest
```
from the root of the repository.
Raw data
{
"_id": null,
"home_page": "https://github.com/DHI/terracotta",
"name": "terracotta",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "xyz tileserver rasterio cloud-optimized-geotiff serverless",
"author": "Dion H\u00e4fner",
"author_email": "mail@dionhaefner.de",
"download_url": "https://files.pythonhosted.org/packages/75/d6/813487ed47f3df49a1d999aeb5035be5274aec06a620508f8bf44a21ddab/terracotta-0.8.6.tar.gz",
"platform": null,
"description": "[](https://github.com/DHI/terracotta/actions/workflows/test.yml)\n[](https://terracotta-python.readthedocs.io/en/latest/?badge=latest)\n[](https://codecov.io/gh/DHI-GRAS/terracotta)\n[](https://github.com/DHI/terracotta/releases)\n[](https://pypi.org/project/terracotta)\n[](https://github.com/DHI/terracotta/blob/main/LICENSE)\n[](https://pypi.org/project/terracotta)\n\n[](#)\n\nTerracotta is a pure Python tile server that runs as a WSGI app on a\ndedicated webserver or as a serverless app on AWS Lambda. It is built on a\nmodern Python stack, powered by awesome open-source software such as\n[Flask](http://flask.pocoo.org), [Zappa](https://github.com/Miserlou/Zappa),\nand [Rasterio](https://github.com/mapbox/rasterio).\n\n[Read the docs](https://terracotta-python.readthedocs.io/en/latest) |\n[Try the demo](https://terracotta-demo-frontend.orangebeach-11aa4896.westeurope.azurecontainerapps.io/) |\n[Explore the API](https://terracotta-python.readthedocs.io/en/latest/apidoc.html) |\n[Satlas, powered by Terracotta](http://satlas.dk) |\n[Docker Image](https://hub.docker.com/r/dhigras/terracotta/tags)\n\n## Why Terracotta?\n\n- It is trivial to get going. Got a folder full of\n [cloud-optimized GeoTiffs](https://www.cogeo.org/) in different\n projections you want to have a look at in your browser?\n `terracotta serve -r {name}.tif` and\n `terracotta connect localhost:5000` get you there.\n- We make minimal assumptions about your data, so *you stay in charge*.\n Keep using the tools you know and love to create and organize your\n data, Terracotta serves it exactly as it is.\n- Serverless deployment is a first-priority use case, so you don\u2019t have\n to worry about maintaining or scaling your architecture.\n- Terracotta instances are self-documenting. Everything the frontend\n needs to know about your data is accessible from only a handful of\n API endpoints.\n\n## The Terracotta workflow\n\n### 1. Optimize raster files\n\n```bash\n$ ls -lh\ntotal 1.4G\n-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:45 S2A_20160724_135032_27XVB_B02.tif\n-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:45 S2A_20160724_135032_27XVB_B03.tif\n-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:46 S2A_20160724_135032_27XVB_B04.tif\n-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:56 S2A_20170831_171901_25XEL_B02.tif\n-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:57 S2A_20170831_171901_25XEL_B03.tif\n-rw-r--r-- 1 dimh 1049089 231M Aug 29 16:57 S2A_20170831_171901_25XEL_B04.tif\n\n$ terracotta optimize-rasters *.tif -o optimized/\n\nOptimizing rasters: 100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| [05:16<00:00, file=S2A_20170831_...25XEL_B04.tif]\n```\n\n### 2. Create a database from file name pattern\n\n```bash\n$ terracotta ingest optimized/S2A_{date}_{}_{tile}_{band}.tif -o greenland.sqlite\nIngesting raster files: 100%|\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588\u2588| 6/6 [00:49<00:00, 8.54s/it]\n```\n\n### 3. Serve it up\n\n```bash\n$ terracotta serve -d greenland.sqlite\n * Serving Flask app \"terracotta.server\" (lazy loading)\n * Environment: production\n WARNING: Do not use the development server in a production environment.\n Use a production WSGI server instead.\n * Debug mode: off\n * Running on http://localhost:5000/ (Press CTRL+C to quit)\n```\n\n### 4. Explore the running server\n\n#### Manually\n\nYou can use any HTTP-capable client, such as `curl`.\n```bash\n$ curl localhost:5000/datasets?tile=25XEL\n{\"page\":0,\"limit\":100,\"datasets\":[{\"date\":\"20170831\",\"tile\":\"25XEL\",\"band\":\"B02\"},{\"date\":\"20170831\",\"tile\":\"25XEL\",\"band\":\"B03\"},{\"date\":\"20170831\",\"tile\":\"25XEL\",\"band\":\"B04\"}]}\n```\n\nModern browsers (e.g. Chrome or Firefox) will render the JSON as a tree.\n\n#### Interactively\n\nTerracotta also includes a web client. You can start the client (assuming the server is running at http://localhost:5000) using\n```bash\n$ terracotta connect localhost:5000\n * Serving Flask app \"terracotta.client\" (lazy loading)\n * Environment: production\n WARNING: Do not use the development server in a production environment.\n Use a production WSGI server instead.\n * Debug mode: off\n * Running on http://127.0.0.1:5100/ (Press CTRL+C to quit)\n```\n\nThen open the client page (http://127.0.0.1:5100/ in this case) in your browser.\n\n\n\n## Development\n\nWe gladly accept [bug reports](https://github.com/DHI/terracotta/issues)\nand [pull requests](https://github.com/DHI/terracotta/pulls) via GitHub.\nFor your code to be useful, make sure that it is covered by tests and that\nit satisfies our linting practices (via `mypy` and `flake8`).\n\nTo run the tests, just install the necessary dependencies via\n\n```bash\n$ pip install -e .[test]\n```\n\nThen, you can run\n\n```bash\n$ pytest\n```\n\nfrom the root of the repository.\n",
"bugtrack_url": null,
"license": null,
"summary": "A modern XYZ tile server written in Python",
"version": "0.8.6",
"project_urls": {
"Homepage": "https://github.com/DHI/terracotta"
},
"split_keywords": [
"xyz",
"tileserver",
"rasterio",
"cloud-optimized-geotiff",
"serverless"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "75d6813487ed47f3df49a1d999aeb5035be5274aec06a620508f8bf44a21ddab",
"md5": "447e5aedefcd85c93547aafbce32639e",
"sha256": "c17e04723d2b1cd1f0bf60e22f338b31902b1aab6e8ab5303f3edc4a1bebc68a"
},
"downloads": -1,
"filename": "terracotta-0.8.6.tar.gz",
"has_sig": false,
"md5_digest": "447e5aedefcd85c93547aafbce32639e",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 3662752,
"upload_time": "2025-02-27T08:42:24",
"upload_time_iso_8601": "2025-02-27T08:42:24.303678Z",
"url": "https://files.pythonhosted.org/packages/75/d6/813487ed47f3df49a1d999aeb5035be5274aec06a620508f8bf44a21ddab/terracotta-0.8.6.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-02-27 08:42:24",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "DHI",
"github_project": "terracotta",
"travis_ci": false,
"coveralls": true,
"github_actions": true,
"lcname": "terracotta"
}
JSON
