Skip to main content

Tilebox Banner Image

Documentation | Console

Tilebox Python

Query satellite data, read imagery from cloud storage, and run processing workflows with Tilebox.

tilebox installs three Python packages together. It contains no source code of its own:

  • tilebox-datasets — Query satellite metadata by location, time, and attributes.
  • tilebox-storage — Read imagery directly from cloud storage, including windows of Cloud Optimized GeoTIFFs (COGs).
  • tilebox-workflows — Distribute processing tasks across local, cloud, or on-premises runners.

Install

Requires Python 3.11 or newer.

pip install tilebox

Documentation

See the documentation, Python SDK reference, and guides.

Getting started

Read Sentinel-2 imagery

Render the branching ice streams of the Aletsch Glacier in Switzerland. This example queries public Sentinel-2 metadata and reads only the RGB window covering the glacier from public COGs. No account, API key, or cloud credentials are needed.

Install the image-writing dependency and save the code below as aletsch.py:

pip install pillow
import asyncio

import numpy as np
from PIL import Image
from shapely import box
from tilebox.datasets import Client, field
from tilebox.datasets.assets import AssetCollection
from tilebox.storage.aio import open_geotiff
from tilebox.storage.geotiff import window_from_bounds

# Aletsch Glacier: west, south, east, north.
area = box(7.94, 46.37, 8.16, 46.57)
collection = Client().dataset("open_data.aws_earth.sentinel2").collection("L2A")
scenes = collection.query(
    temporal_extent=("2025-08-01", "2025-09-01"),
    spatial_extent=area,
    filter=field("cloud_cover") < 10,
)
scene = scenes.sortby("cloud_cover").isel(time=0)
assets = AssetCollection.from_datapoint(scene)


async def read_band(key):
    asset = assets[key]
    geotiff = await open_geotiff(asset)
    window = window_from_bounds(
        geotiff, area.bounds, crs="EPSG:4326", require_fully_contained=True
    )
    raster = await geotiff.read(window=window)
    return raster.data[0].astype(np.float32) * asset.raster.scale + asset.raster.offset


async def main():
    bands = await asyncio.gather(*(read_band(key) for key in ("red", "green", "blue")))
    rgb = np.stack(bands, axis=-1)
    display = np.clip(rgb / 0.9, 0, 1) ** (1 / 2.2)
    image = Image.fromarray((display * 255).astype(np.uint8))
    image.thumbnail((1200, 1200), Image.Resampling.LANCZOS)
    image.save("aletsch.jpg", quality=90)


asyncio.run(main())

Run python aletsch.py to create aletsch.jpg:

Sentinel-2 RGB image of the Aletsch Glacier, with tributary glaciers converging between rocky Alpine ridges

Aletsch Glacier, August 8, 2025. Contains modified Copernicus Sentinel data (2025), accessed through Element 84 Earth Search. Generated with the code above.

The scale and offset convert each band to surface reflectance; the stretch and gamma correction are for display only. See Create a Sentinel-2 RGB image for more detail. If you change the location or dates, check for an empty query result and verify that the selected scene covers your area.

Compare Alpine snow cover

How much of the same area is classified as snow or ice in June, August, and October? This workflow creates one task per month. Each task selects a low-cloud scene, reads a small window of its 20 m Scene Classification Layer (SCL), and logs snow-and-ice coverage without saving imagery to disk.

Authenticate before running workflows. Append this code to aletsch.py; it reuses the imports, area, and collection above:

from shapely import Polygon
from tilebox.workflows import Client as WorkflowsClient, Runner, Task


class SnowCover(Task):
    area: Polygon
    period: tuple[str, str]

    async def execute(self, context):
        scenes = collection.query(
            temporal_extent=self.period,
            spatial_extent=self.area,
            filter=field("cloud_cover") < 10,
        )
        if not scenes.sizes.get("time", 0):
            raise ValueError(f"No low-cloud scenes for {self.period}")
        scene = scenes.sortby("cloud_cover").isel(time=0)
        geotiff = await open_geotiff(AssetCollection.from_datapoint(scene)["scl"])
        window = window_from_bounds(
            geotiff, self.area.bounds, crs="EPSG:4326", require_fully_contained=True
        )
        classes = (await geotiff.read(window=window)).data[0]
        clear = np.isin(classes, [4, 5, 6, 11])  # Vegetation, bare ground, water, snow/ice.
        if clear.mean() < 0.8:
            raise ValueError("Less than 80% of the window has a clear classification")
        context.logger.info(
            "Snow cover",
            scene=scene.stac_id.item(),
            snow_ice_pct=round(100 * np.count_nonzero(classes == 11) / clear.sum(), 1),
            clear_pct=round(100 * clear.mean(), 1),
        )


class CompareSnowCover(Task):
    area: Polygon
    year: int

    def execute(self, context):
        context.submit_subtasks([
            SnowCover(self.area, (f"{self.year}-{m:02}-01", f"{self.year}-{m + 1:02}-01"))
            for m in (6, 8, 10)
        ])


client = WorkflowsClient()
job = client.jobs().submit("aletsch-snow-cover", CompareSnowCover(area, 2025))
Runner(tasks=[CompareSnowCover, SnowCover]).connect_to(client).run_all()
print(f"https://console.tilebox.com/workflows/jobs/{job.id}")

Run python aletsch.py again to submit the job and process its tasks on your machine. The runner prints results locally; open the printed Console link to inspect the task graph and logs. Additional runners can process the monthly tasks in parallel. See Build and deploy a workflow to run on cloud infrastructure.

These are scene snapshots, not a glacier-retreat or mass-balance estimate. snow_ice_pct is the fraction of clearly classified pixels labeled snow/ice; clear_pct reports how much of the window contributed. Clouds, shadows, missing data, and unclassified pixels are excluded. The window includes surrounding mountains, and a low scene-wide cloud percentage does not guarantee a clear glacier.

Contributing

Contributions are welcome! Please see the contributing guide for more information.

You can also join us on Discord if you have any questions or want to share your ideas.

License

Distributed under the MIT License (The MIT License).

Authentication

Public open-data queries and the imagery example work without authentication. Workflows, private datasets, and higher query rate limits require a Tilebox account.

Create an API key in the Tilebox Console, then set it before running your script:

export TILEBOX_API_KEY="your-api-key"

The clients read TILEBOX_API_KEY automatically. See Authentication for details. Access to other imagery providers or private storage may require separate credentials.

Metadata

Release files for tilebox 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for tilebox 0.2.0
File Size Uploaded Provenance Actions
tilebox-0.2.0.tar.gz 5.5 kB With provenance Details for tilebox-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for tilebox 0.2.0
File Interpreter ABI Platform Actions
tilebox-0.2.0-py3-none-any.whl Python 3 none any Details for tilebox-0.2.0-py3-none-any.whl

Total release size: 11.3 kB

Release files / tilebox-0.2.0.tar.gz

Download URL tilebox-0.2.0.tar.gz
Size 5.5 kB
Tags Source
SHA-256 checksum
How to use checksums
b50fb91597babee2eb056cdc772f9040e1661020bdf5642690b9aa3849952c46
BLAKE2b-256 checksum
How to use checksums
1d227583dcfaef7a1d086889b0125a09755a298e1acf0be2e324a34f36596b97
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Release files / tilebox-0.2.0-py3-none-any.whl

Download URL tilebox-0.2.0-py3-none-any.whl
Size 5.8 kB
Tags Python 3
SHA-256 checksum
How to use checksums
339fd2be915f2e4dfa55bd1d9e8db8be2304ccb8af19d76dc9232232d3097551
BLAKE2b-256 checksum
How to use checksums
4ddf55129fe5f73410a0ceaf1f815009e23bdace69110a7dc717c9c8d1fa2757
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

Security for tilebox 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for tilebox-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 9, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page