Read and download assets

The storage client reads assets from local files, S3, Google Cloud Storage, Azure, and HTTP locations. It selects a compatible location from the metadata attached to each asset.

Resolve assets from a datapoint

Query an asset-enabled dataset and select one datapoint. See Querying data for the complete query API.

Python

from shapely import box
from tilebox.datasets import Client, field
from tilebox.datasets.assets import AssetCollection

collection = Client().dataset("open_data.aws_earth.sentinel2").collection("L2A")
data = collection.query(
    temporal_extent=("2026-07-20", "2026-07-28"),
    spatial_extent=box(16.25, 48.15, 16.35, 48.22),
    filter=field("cloud_cover") < 10,
)

assets = AssetCollection.from_datapoint(data.isel(time=0))
print(list(assets))
red = assets["red"]
thumbnail = assets["thumbnail"]

Copy

An asset exposes its media type, roles, bands, primary location, and alternate locations. from_datapoint accepts one selected datapoint; for multiple results, resolve each datapoint separately.

Create one client and reuse it across assets so it can reuse the underlying object stores:

Python

from tilebox.storage.aio import Client as StorageClient

storage = StorageClient()
await storage.download(thumbnail, "thumbnail.jpg")

Copy

Storage operations

Read an asset into memory

Use read_bytes for small files. Set max_bytes to reject unexpectedly large objects.

Python

content = await storage.read_bytes(thumbnail, max_bytes=10_000_000)

Copy

Stream asset bytes

Use iter_bytes when you can process the file incrementally.

Python

async for chunk in storage.iter_bytes(red):
    process(chunk)

Copy

Download an asset

download writes atomically to the exact destination path and does not replace an existing file unless requested.

Python

path = await storage.download(red, "data/red.tif")

Copy

Open a GeoTIFF

open_geotiff opens TIFF metadata without downloading the complete file. The COG and GeoTIFF section shows how to read a region.

Python

geotiff = await storage.open_geotiff(red)

Copy

Inspect the selected location

resolve selects a location without making a network request. Most code can let the other operations call it automatically.

Python

resolved = storage.resolve(red)
print(resolved.href, resolved.path)

Copy

Work with COG and GeoTIFF assets

A Cloud Optimized GeoTIFF (COG) supports range requests, so you can read the pixels for one region without downloading the complete image. Use window_from_bounds to convert geographic bounds into a pixel window.

Python

from tilebox.storage.geotiff import window_from_bounds

geotiff = await storage.open_geotiff(red)
window = window_from_bounds(
    geotiff,
    bounds=(16.25, 48.15, 16.35, 48.22),  # west, south, east, north
    crs="EPSG:4326",
)
pixels = await geotiff.read(window=window)

Copy

The storage client does not apply scale, offset, no-data masks, band stacking, or coordinate transformations. GeoTIFF access requires Python 3.11 or newer.

Read RGB bands in parallel

Use asyncio.gather to fetch independent assets concurrently. This example reads the same 512 × 512 pixel window from the red, green, and blue COGs and stacks the results into an RGB array.

Python

import asyncio

import numpy as np
from async_geotiff import Window

window = Window(col_off=4096, row_off=4096, width=512, height=512)

async def read_band(key):
    geotiff = await storage.open_geotiff(assets[key])
    raster = await geotiff.read(window=window)
    return raster.data[0]

red_data, green_data, blue_data = await asyncio.gather(
    read_band("red"),
    read_band("green"),
    read_band("blue"),
)
rgb = np.stack((red_data, green_data, blue_data), axis=-1)
print(rgb.shape)  # (512, 512, 3)

Copy

Choose a location

Assets can provide primary and alternate locations. By default, the client prefers local files, S3, Google Cloud Storage, Azure, HTTPS, and HTTP, in that order. Configure an AssetAccessPolicy to change that order.

Python

from tilebox.storage.aio import AssetAccessPolicy, Client as StorageClient

storage = StorageClient(
    policy=AssetAccessPolicy(preferred_schemes=("https", "s3")),
)

Copy

Storage metadata can provide regions, endpoints, and requester-pays settings.

Authentication

Asset locations can reference authentication metadata. The storage client currently supports S3 credentials from the standard AWS credential environment. Authenticated HTTP locations are not yet supported.

Next steps

Create a Sentinel-2 RGB image

Query Sentinel-2 and combine three image bands over a selected region.

Reference your own assets

Attach file references to datapoints you ingest.