{"id":13737798,"url":"https://github.com/DHI/terracotta","last_synced_at":"2025-05-08T15:31:30.798Z","repository":{"id":33649509,"uuid":"124049306","full_name":"DHI/terracotta","owner":"DHI","description":"A light-weight, versatile XYZ tile server, built with Flask and Rasterio :earth_africa:","archived":false,"fork":false,"pushed_at":"2025-04-30T09:48:17.000Z","size":11377,"stargazers_count":730,"open_issues_count":36,"forks_count":83,"subscribers_count":19,"default_branch":"main","last_synced_at":"2025-04-30T10:05:43.270Z","etag":null,"topics":["cloud-optimized-geotiff","python","rasterio","serverless","tileserver","xyz"],"latest_commit_sha":null,"homepage":"https://terracotta-python.readthedocs.org","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/DHI.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-03-06T08:53:34.000Z","updated_at":"2025-04-30T09:47:53.000Z","dependencies_parsed_at":"2023-02-17T05:01:09.687Z","dependency_job_id":"de1fe75d-1a6c-410a-95b5-6b374ce823a3","html_url":"https://github.com/DHI/terracotta","commit_stats":{"total_commits":914,"total_committers":29,"mean_commits":"31.517241379310345","dds":0.4912472647702407,"last_synced_commit":"54d29190153e727c7694fc491588db7fa387f3a8"},"previous_names":["dhi/terracotta","dhi-gras/terracotta"],"tags_count":24,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHI%2Fterracotta","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHI%2Fterracotta/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHI%2Fterracotta/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/DHI%2Fterracotta/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/DHI","download_url":"https://codeload.github.com/DHI/terracotta/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253096034,"owners_count":21853531,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloud-optimized-geotiff","python","rasterio","serverless","tileserver","xyz"],"created_at":"2024-08-03T03:02:01.452Z","updated_at":"2025-05-08T15:31:29.908Z","avatar_url":"https://github.com/DHI.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"[![Tests](https://github.com/DHI/terracotta/actions/workflows/test.yml/badge.svg)](https://github.com/DHI/terracotta/actions/workflows/test.yml)\n[![Documentation Status](https://readthedocs.org/projects/terracotta-python/badge/?version=latest)](https://terracotta-python.readthedocs.io/en/latest/?badge=latest)\n[![codecov](https://codecov.io/gh/DHI-GRAS/terracotta/branch/main/graph/badge.svg?token=u16QBwwvvn)](https://codecov.io/gh/DHI-GRAS/terracotta)\n[![GitHub release](https://img.shields.io/github/release-pre/dhi-gras/terracotta.svg)](https://github.com/DHI/terracotta/releases)\n[![PyPI release](https://img.shields.io/pypi/v/terracotta.svg)](https://pypi.org/project/terracotta)\n[![License](https://img.shields.io/github/license/dhi-gras/terracotta.svg)](https://github.com/DHI/terracotta/blob/main/LICENSE)\n[![Python versions](https://img.shields.io/pypi/pyversions/terracotta.svg)](https://pypi.org/project/terracotta)\n\n[![Logo](docs/_figures/logo-banner.svg)](#)\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’t 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%|██████████████████████████| [05:16\u003c00: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%|███████████████████████████████████████████| 6/6 [00:49\u003c00: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![preview](docs/_figures/workflow-preview.png)\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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDHI%2Fterracotta","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FDHI%2Fterracotta","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FDHI%2Fterracotta/lists"}