Python task inputs

Python tasks are data classes. Annotate each task field with one of the supported types below, and Tilebox reconstructs that type before the task runs. This page applies to tasks executed by Python runners. For tasks submitted and executed across different languages, use an input schema supported by both SDKs. See Multi-language workflows. The examples focus on task input declarations and omit the execute method.

Python standard library

These types require no extra packages:

Values: str, int, float, bool, bytes, and bytearray
Collections: list, tuple, dict, set, and frozenset
Type annotations: Optional, Union, and Literal
Structured values: data classes and Enum
Dates and times: datetime, date, time, timedelta, and ZoneInfo
Other values: UUID, Decimal, and PurePath subclasses such as Path

Example usage

from datetime import datetime
from pathlib import Path
from uuid import UUID

from tilebox.workflows import Task

class BuildSentinel2Mosaic(Task):
    scene_ids: list[UUID]
    bands: tuple[str, ...]
    acquired_after: datetime
    output_path: Path

Protocol buffers

protobuf provides generated message classes for strongly typed schemas and is installed with tilebox-workflows. Tilebox supports Message and its generated subclasses. Example usage

from google.protobuf.timestamp_pb2 import Timestamp
from tilebox.workflows import Task

class ProcessSceneAcquisition(Task):
    scene_id: str
    acquired_at: Timestamp

Tilebox Datasets

tilebox-datasets provides value types for dataset and job queries and is installed with tilebox-workflows.

Type	Use in a workflow
`TimeInterval`, `IDInterval`	Pass dataset or job query ranges to a task
`SpatialFilter`	Pass a dataset spatial query to a task; its geometry requires Shapely

Example usage

from tilebox.datasets.data.data_access import SpatialFilter
from tilebox.datasets.query import TimeInterval
from tilebox.workflows import Task

class QuerySentinel2Scenes(Task):
    collections: list[str]
    temporal_extent: TimeInterval
    spatial_extent: SpatialFilter

Shapely

shapely provides geometry types for vector features, footprints, and areas of interest.

Single geometries: Geometry, Point, LineString, LinearRing, and Polygon
Geometry collections: MultiPoint, MultiLineString, MultiPolygon, and GeometryCollection

Example usage

from shapely import MultiPolygon
from tilebox.workflows import Task

class ComputeSentinel2CloudStatistics(Task):
    area_of_interest: MultiPolygon
    preceding_hours: int

Coordinate systems and raster transforms

affine provides two-dimensional affine transformation matrices. pyproj provides coordinate reference systems and coordinate transformations.

Type	Use in a workflow
`Affine`	Preserve the pixel-to-world transform for raster processing
`pyproj.CRS`	Pass a coordinate reference system without reducing it to a string

Example usage

from affine import Affine
from pyproj import CRS
from tilebox.workflows import Task

class ReprojectRasterTile(Task):
    source_crs: CRS
    target_crs: CRS
    source_transform: Affine

ODC Geo

odc-geo provides projection-aware geometry and raster grid types.

Type	Use in a workflow
`CRS`	Preserve an ODC coordinate reference system
`Geometry`, `BoundingBox`	Pass projection-aware geometries and bounds
`XY`, `Resolution`	Describe grid coordinates and spatial resolution
`Index2d`, `Shape2d`	Describe a grid index or shape
`GeoBox`	Preserve an aligned, georeferenced raster grid
`GeoboxTiles`, `AnchorEnum`	Partition and align a `GeoBox` for tiled processing

Example usage

from odc.geo import GeoBox
from tilebox.workflows import Task

class ReprojectSentinel2Product(Task):
    product_location: str
    source_grid: GeoBox
    target_grid: GeoBox

Raster windows

rasterio provides raster data access and processing. async-geotiff provides asynchronous GeoTIFF and Cloud Optimized GeoTIFF reads. Install either package separately when your workflow uses its window type.

Type	Use in a workflow
`rasterio.windows.Window`	Pass a rectangular pixel region to a task that uses `rasterio`
`async_geotiff.Window`	Pass a rectangular pixel region to an async GeoTIFF task

Example usage

from rasterio.windows import Window
from tilebox.workflows import Task

class ComputeHyperspectralChunkStatistics(Task):
    product_path: str
    window: Window
    output_key: str

Keep task inputs compact

Task inputs are part of the workflow graph and are not intended for large arrays, file contents, pandas DataFrames, clients, or open files. Store large data in object storage or the job cache, then pass a compact reference such as an ID, object prefix, cache key, time interval, geometry, or raster window.

Tilebox SDKs

Python

Go

Python standard library

Protocol buffers

Tilebox Datasets

Shapely

Coordinate systems and raster transforms

ODC Geo

Raster windows

Keep task inputs compact

​Python standard library

​Protocol buffers

​Tilebox Datasets

​Shapely

​Coordinate systems and raster transforms

​ODC Geo

​Raster windows

​Keep task inputs compact

Python standard library

Protocol buffers

Tilebox Datasets

Shapely

Coordinate systems and raster transforms

ODC Geo

Raster windows

Keep task inputs compact