Client

Private Preview

RasterflowClient

RasterflowClient(
    rasterflow_version: str = 'v3.0.4',
    rasterflow_domain: str | None = None,
    mosaics_version: str = 'v2.1.0',
    mosaics_domain: str | None = None,
    zarr_multiscales_version: str = 'v2.1.3',
    zarr_multiscales_domain: str | None = None,
    dry_run: bool = False,
    cache: bool = True
)

High-level client for executing RasterFlow workflows using Flyte remote.

build_gti_mosaics()

Build a Zarr mosaic from a GDAL Tile Index (GTI) vector file. See https://gdal.org/en/latest/drivers/raster/gti.html for more information. Note: The GTI tile index must: 1. Have a geometry column corresponding to the spatial extent of each tile 2. Have a column pointing to the remote URL of each GeoTIFF/COG 3. Contain homogeneous bands across all entries Additional recommended metadata as described in the GDAL docs will improve performance or quality of the mosaic.

def build_gti_mosaics(
    self,
    gti: str,
    aoi: str,
    bands: list[str],
    location_field: str,
    target_crs: str | int = 'EPSG:3857',
    time_column: str | None = None,
    skip_xy_coords: bool = False,
    xy_chunksize: int = 512,
    max_shard_size: float = 3500000000.0,
    query: str | None = None,
    requester_pays: bool = False,
    envs: dict[str, str] | None = None,
    sort_field: str | None = None,
    resampling:
        wherobots_rasterflow_core.domain.enums.ResamplingMethod =
        ResamplingMethod.NEAREST,
    resolution: float | None = None,
    nodata: float | None = None,
    id: str | None = None
) -> wherobots_rasterflow_core.domain.mosaics.MosaicResult

Parameters

str

required

Remote URL path to the tile index GeoDataFrame.

str

required

Remote URL path to the area of interest GeoDataFrame.

list[str]

required

List of band names to include in the mosaic. Must exist in all tiles.

str

required

Column name in the GTI that contains the path/URL to each GeoTIFF/COG.

str | int

Target coordinate reference system for the output mosaic. Accepted values include EPSG strings, EPSG integer codes, WKT, and PROJJSON. Default is “EPSG:3857”.

str | None

GTI column used to group entries into mosaic time intervals. Defaults to None. If set to None, all rows are grouped into a single NaT time slice. For example, a year column with elements from would lead to time dimension of length 2. This enables the user to specify any time resolution based on properties of the underlying raster data. Be sure that the cardinality of the time column is not too high.

bool

Whether to skip the XY coordinates when building the mosaic. This is useful for very very large mosaics. Defaults to False.

int

Chunk size in pixels to use for the X and Y dimensions when building the mosaic. Default is 512.

float

The size in bytes that determines the shard size for the Zarr store and the partition size for each task. Default is 3.5GB in bytes.

str | None

Pandas query string to filter the GTI before processing. Uses DataFrame.query() syntax. See https://pandas.pydata.org/docs/reference/api/pandas.DataFrame.query.html. Default is None.

bool

If True, enables requester pays for accessing cloud-stored tiles. The requester’s account will be charged for data transfer. Default is False.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

str | None

Column name in the GTI to sort entries by before building the mosaic. Sorting can affect which tiles take precedence in overlapping areas. Default is None.

ResamplingMethod

default:"ResamplingMethod"

Resampling method to use when building the mosaic, by default ResamplingMethod.NEAREST.

float | None

Spatial resolution for the output mosaic in the units of the target CRS. If None, uses the native resolution of the input tiles. Default is None.

float | None

Nodata value to assign to the output mosaic. If None, attempts to use the nodata value from the source tiles. Will raise an error if tiles lack a nodata value. Default is None.

str | None

default:"None"

Optional identifier used to create a deterministic output prefix under the configured storage URI. If None, the remote workflow execution id is used.

Response

MosaicResult

Result containing the output mosaics GeoDataFrame and the first_row_mosaic URI extracted from its location column.

build_mosaics()

Execute the mosaic building workflow.

def build_mosaics(
    self,
    datasets:
        list[wherobots_rasterflow_core.domain.enums.DatasetEnum],
    aoi: str,
    start: datetime.datetime,
    end: datetime.datetime,
    target_crs: str | int = 'EPSG:3857',
    xy_chunksize: int = 512,
    max_shard_size: float = 3500000000.0,
    envs: dict[str, str] | None = None,
    resolution: float | None = None,
    skip_xy_coords: bool = False
) -> wherobots_rasterflow_core.domain.mosaics.MosaicResult

Parameters

list[DatasetEnum]

required

List of datasets to include in the mosaic. Available datasets are defined in DatasetEnum.

str

required

Area of interest as any file format supported by GeoPandas read_file or read_parquet (e.g., GeoJSON, GeoParquet, Shapefile) via remote URL.

datetime

required

Start date for the temporal range of the mosaic.

datetime

required

End date for the temporal range of the mosaic.

str | int

Target coordinate reference system for the output mosaic. Accepted values include EPSG strings, EPSG integer codes, WKT, and PROJJSON. Default is “EPSG:3857”.

int

Chunk size in pixels to use for the X and Y dimensions when building the mosaic. Larger values use more memory but may be faster. Default is 512.

float

The size in bytes that determines the shard size for the Zarr store and the partition size for each task. Default is 3.5GB in bytes.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

float | None

Spatial resolution for the output mosaic in the units of the target CRS. If None, uses the native resolution of the input datasets. Default is None.

bool

Whether to skip the XY coordinates when building the mosaic. This is useful for very very large mosaics. Defaults to False.

Response

MosaicResult

Result containing the output mosaics GeoDataFrame and the first_row_mosaic URI extracted from its location column.

build_zarr_multiscales()

Build an optimized multiscale Zarr store from an unoptimized Zarr store. This workflow creates a new Zarr store with multiple resolution levels (overviews) and optional histogram statistics, suitable for efficient visualization and analysis.

def build_zarr_multiscales(
    self,
    source_store: str,
    nodata: float | None = None,
    histogram_dims: list[str] | None = None,
    envs: dict[str, str] | None = None
) -> rasterflow_remote.data_models.MosaicOutput

Parameters

str

required

URI of the input Zarr store to process (e.g., an S3 path like s3://bucket/path/store.zarr).

float | None

Fill value to use for target arrays. If None, uses source array fill_value when available, otherwise falls back to NaN for floating types and 0 for non-floating types. Default is None.

list[str] | None

Dimensions to create separate histograms for (e.g., ["band"]). If None, auto-detects: uses ["band"] if a “band” dimension exists, otherwise creates a single global histogram. Default is None.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

MosaicOutput

Output URI to the generated multiscale Zarr store.

predict_mosaic()

Run inference on a single mosaic zarr store using a specified model.

def predict_mosaic(
    self,
    mosaics: str,
    model_path: str,
    patch_size: int,
    clip_size: int,
    device: str,
    features: list[str],
    labels: list[str],
    actor:
        wherobots_rasterflow_core.domain.enums.MosaicToMosaicActorEnum,
    max_batch_size: int,
    merge_mode:
        wherobots_rasterflow_core.domain.enums.MergeModeEnum,
    selected_labels: list[str] | None = None,
    xy_block_multiplier: int = 4,
    target_xy_chunksize: int | None = None,
    runtime: wherobots_rasterflow_core.domain.enums.RuntimeEnum =
        RuntimeEnum.SMALL,
    envs: dict[str, str] | None = None
) -> wherobots_rasterflow_core.domain.mosaics.MosaicResult

Parameters

str

required

URI of the input mosaic Zarr store to run inference on.

str

required

Path (local or remote URL) to the model file. Should be compatible with the specified inference actor.

int

required

Size of the patches to be used during inference.

int

required

Size in pixels to clip from patch edges before merging predictions. Helps reduce edge artifacts in overlapping regions. Must be less than patch_size.

str

required

Device to run the model on. Options: “cuda” for GPU, “cpu” for CPU.

list[str]

required

List of feature (band) names from the mosaic to use as model inputs. Must exist in the input Zarr store.

list[str]

required

List of output label names that the model produces. These will be the band names in the output store.

MosaicToMosaicActorEnum

required

The inference actor to use for running the model. Available options are defined in MosaicToMosaicActorEnum.

int

required

Maximum number of patches to process in a single batch during inference.

MergeModeEnum

required

Method for merging predictions from overlapping patches. Options defined in MergeModeEnum.

list[str] | None

Subset of labels to extract from model output. If None, all labels produced by the model are saved. Default is None.

int

Multiplier on Zarr chunks. Larger values process bigger blocks (groups of chunks) at once. Default is 4.

int | None

default:"None"

Optional chunk size for output mosaics. If None, the workflow default is used.

RuntimeEnum

Compute resources to allocate for the workflow execution. Options defined in RuntimeEnum (e.g., SMALL, MEDIUM, LARGE). Default is RuntimeEnum.SMALL.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

MosaicResult

Result containing the output mosaics GeoDataFrame and the first_row_mosaic URI extracted from its location column.

predict_mosaic_geometries()

Run geometry inference on a single mosaic zarr store using a specified model. Produces georeferenced vector geometries from model predictions on an existing mosaic, unlike :meth:predict_mosaic_geometries_recipe which also builds the mosaic from a configured data source.

def predict_mosaic_geometries(
    self,
    mosaics: str,
    model_path: str,
    patch_size: int,
    clip_size: int,
    device: str,
    features: list[str],
    labels: list[str],
    actor:
        wherobots_rasterflow_core.domain.enums.GeometryActorEnum,
    max_batch_size: int,
    confidence_threshold: float,
    merge_mode:
        wherobots_rasterflow_core.domain.enums.MergeModeEnum =
        clip,
    selected_labels: list[str] | None = None,
    xy_block_multiplier: int = 4,
    dst_crs: str = 'EPSG:4326',
    runtime: wherobots_rasterflow_core.domain.enums.RuntimeEnum =
        RuntimeEnum.SMALL,
    envs: dict[str, str] | None = None
) -> rasterflow_remote.data_models.GeometryOutput

Parameters

str

required

URI of the input mosaic Zarr store to run inference on.

str

required

Path (local or remote URL) to the model file. Should be compatible with the specified inference actor.

int

required

Size of the patches to be used during inference.

int

required

Size in pixels to clip from patch edges before merging predictions. Helps reduce edge artifacts in overlapping regions. Must be less than patch_size.

str

required

Device to run the model on. Options: “cuda” for GPU, “cpu” for CPU.

list[str]

required

List of feature (band) names from the mosaic to use as model inputs. Must exist in the input Zarr store.

list[str]

required

List of output label names that the model produces.

GeometryActorEnum

required

The inference actor to use for running the model. Available options are defined in GeometryActorEnum.

int

required

Maximum number of patches to process in a single batch during inference.

float

required

Minimum confidence score in [0.0, 1.0] to retain a geometry detection. Lower values yield more detections at the cost of more false positives.

MergeModeEnum

Method for merging predictions from overlapping patches. Options defined in MergeModeEnum. Default is MergeModeEnum.CLIP.

list[str] | None

Subset of labels to extract from model output. If None, all labels produced by the model are saved. Default is None.

int

Multiplier on Zarr chunks. Larger values process bigger blocks (groups of chunks) at once. Default is 4.

str

EPSG code string for the output coordinate reference system of the geometries (e.g., "EPSG:4326"). Default is "EPSG:4326".

RuntimeEnum

Compute resources to allocate for the workflow execution. Options defined in RuntimeEnum (e.g., SMALL, MEDIUM, LARGE). Default is RuntimeEnum.SMALL.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

GeometryOutput

Output URI to a parquet directory containing georeferenced vector geometries. The URI is None if no geometries were detected.

predict_mosaic_geometries_recipe()

Run geometry inference using a pre-configured recipe for a specific model. This convenience method builds a mosaic from the configured data source and runs inference to produce georeferenced vector geometries from a text prompt.

def predict_mosaic_geometries_recipe(
    self,
    aoi: str,
    start: datetime.datetime,
    end: datetime.datetime,
    model_recipe:
        wherobots_rasterflow_core.domain.enums.GeometryModelRecipes,
    text_prompt: str | list[str],
    confidence_threshold: float,
    target_crs: str | int | None = None,
    runtime: wherobots_rasterflow_core.domain.enums.RuntimeEnum =
        RuntimeEnum.SMALL,
    envs: dict[str, str] | None = None
) -> rasterflow_remote.data_models.GeometryOutput

Parameters

str

required

Remote URL path to the area of interest GeoDataFrame.

datetime

required

Start date for the temporal range of the mosaic.

datetime

required

End date for the temporal range of the mosaic.

GeometryModelRecipes

required

Pre-configured recipe that defines the datasets, model, and inference parameters to use. Available recipes are defined in the GeometryModelRecipes enum.

str | list[str]

required

One or more noun phrases describing the objects to detect (e.g., "building", ["tree", "shrub"]). A bare string is treated as a single-element list. All listed categories are detected and included in the output.

float

required

Minimum confidence score in [0.0, 1.0] to retain a geometry detection. Lower values yield more detections at the cost of more false positives.

str | int | None

Target coordinate reference system. Accepted values include EPSG strings, EPSG integer codes, WKT, and PROJJSON. If None, defaults to the native CRS of the underlying datasets for the model recipe where possible.

RuntimeEnum

Compute resources to allocate for the workflow execution. Options defined in RuntimeEnum (e.g., SMALL, MEDIUM, LARGE). Default is RuntimeEnum.SMALL.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

GeometryOutput

Output URI to a parquet directory containing georeferenced vector geometries. The URI is None if no geometries were detected.

predict_mosaic_recipe()

Build a mosaic and run inference using a pre-configured recipe for a specific model. This convenience method combines mosaic building and inference into a single workflow using a model recipe that defines the input datasets, model, and inference parameters.

def predict_mosaic_recipe(
    self,
    aoi: str,
    start: datetime.datetime,
    end: datetime.datetime,
    model_recipe:
        wherobots_rasterflow_core.domain.enums.ModelRecipes,
    target_crs: str | int | None = None,
    runtime: wherobots_rasterflow_core.domain.enums.RuntimeEnum =
        RuntimeEnum.SMALL,
    envs: dict[str, str] | None = None
) -> wherobots_rasterflow_core.domain.mosaics.MosaicResult

Parameters

str

required

Remote URL path to the area of interest GeoDataFrame.

datetime

required

Start date for the temporal range of the mosaic.

datetime

required

End date for the temporal range of the mosaic.

ModelRecipes

required

Pre-configured recipe that defines the datasets, model, and inference parameters to use. Available recipes are defined in the ModelRecipes enum.

str | int | None

RuntimeEnum

Compute resources to allocate for the workflow execution. Options defined in RuntimeEnum (e.g., SMALL, MEDIUM, LARGE). Default is RuntimeEnum.SMALL.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

MosaicResult

Result containing the output mosaics GeoDataFrame and the first_row_mosaic URI extracted from its location column.

run_mosaics_change()

Run temporal change detection on a mosaic zarr store.

def run_mosaics_change(
    self,
    mosaics: str,
    score_methods:
        list[wherobots_rasterflow_core.domain.enums.TemporalScoreMethodEnum],
    distance_metric:
        wherobots_rasterflow_core.domain.enums.DistanceMetricEnum,
    xy_block_multiplier: int = 4,
    sharded: bool = False,
    target_xy_chunksize: int | None = None,
    selector: dict[str, tuple[int, int]] | None = None,
    data_var: str = 'variables',
    fill_value: float | None = None,
    robust_time_zscore: bool = True,
    runtime: wherobots_rasterflow_core.domain.enums.RuntimeEnum =
        RuntimeEnum.SMALL,
    envs: dict[str, str] | None = None
) -> wherobots_rasterflow_core.domain.mosaics.MosaicResult

Parameters

str

required

URI of the input mosaic Zarr store to score over time.

list[TemporalScoreMethodEnum]

required

Temporal scoring methods to compute. Each method is written as a separate output band.

DistanceMetricEnum

required

Distance metric used when comparing embeddings across time.

int

Multiplier on Zarr chunks. Larger values process bigger blocks at once. Default is 4.

bool

Whether to write sharded output chunks. Default is False.

int | None

default:"None"

Optional chunk size for output mosaics. If None, the workflow default is used.

dict[str, tuple[int, int]] | None

Per-dimension integer index selection to subset the mosaic before processing. A mapping from dimension name (e.g. "x", "y", "time") to a (start, stop) pair of chunk-aligned integer indices. Only integer index selection is supported for now. Default is None (process the full mosaic).

str

Name of the source array variable to read and the output array variable to write. Default is "variables".

float | None

default:"None"

Optional nodata/fill value to replace with NaN before scoring.

bool

Whether to post-process raw distance scores as a robust z-score along the time dimension. Default is True.

RuntimeEnum

Compute resources to allocate for the workflow execution. Options defined in RuntimeEnum (e.g., SMALL, MEDIUM, LARGE). Default is RuntimeEnum.SMALL.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

MosaicResult

Result containing the output mosaics GeoDataFrame and the first_row_mosaic URI extracted from its location column.

vectorize_mosaic()

Convert raster predictions to vector geometries through polygonization. Supports thresholding and then vectorizing float values. Typically these are confidence scores from semantic segmentation workflows.

def vectorize_mosaic(
    self,
    mosaic: str,
    features: list[str],
    threshold: float,
    vectorize_method:
        wherobots_rasterflow_core.domain.enums.VectorizeMethodEnum,
    vectorize_config:
        wherobots_rasterflow_core.domain.vectorize.SemSegRasterioConfig
        | None,
    xy_block_multiplier: int = 4,
    dst_crs: str | None = 'EPSG:4326',
    runtime: wherobots_rasterflow_core.domain.enums.RuntimeEnum =
        RuntimeEnum.SMALL,
    envs: dict[str, str] | None = None
) -> rasterflow_remote.data_models.VectorizeOutput

Parameters

str

required

URI of the input mosaic Zarr store to vectorize.

list[str]

required

List of features (band) names from the mosaic to vectorize. Typically these represent the model predictions from predict_mosaic. Each feature is vectorized separately.

float

required

Threshold value for binarizing continuous predictions before vectorization. Pixels with values greater than or equal to this threshold are considered foreground (1), while values below are background (0).

VectorizeMethodEnum

required

Vectorization method to use. Available methods are defined in VectorizeMethodEnum.

VECTOR_CONFIG_TYPES

required

The configuration for the vectorize_method.

int

Multiplier on Zarr chunks. Larger values process bigger blocks (groups of chunks) at once. Default is 4.

str | None

Target coordinate reference system for the output geometries in EPSG format (e.g., “EPSG:4326”). If None, geometries remain in the CRS of the input mosaic. Default is “EPSG:4326” (WGS84 lat/lon).

RuntimeEnum

Compute resources to allocate for the workflow execution. Options defined in RuntimeEnum (e.g., SMALL, MEDIUM, LARGE). Default is RuntimeEnum.SMALL.

dict[str, str] | None

Additional environment variables to pass to the workflow execution. Default is None.

Response

VectorizeOutput

Output URI to the merged parquet directory containing vectorization results, or None when no vector features were produced.

Wherobots Cloud REST API

WherobotsDB

Vector tiles (PMTiles)

Havasu (Iceberg) table management

GeoStats and Map Matching

Rasterflow

RasterflowClient

build_gti_mosaics()

Parameters

Response

build_mosaics()

Parameters

Response

build_zarr_multiscales()

Parameters

Response

predict_mosaic()

Parameters

Response

predict_mosaic_geometries()

Parameters

Response

predict_mosaic_geometries_recipe()

Parameters

Response

predict_mosaic_recipe()

Parameters

Response

run_mosaics_change()

Parameters

Response

vectorize_mosaic()

Parameters

Response

​RasterflowClient

​build_gti_mosaics()

​Parameters

​Response

​build_mosaics()

​Parameters

​Response

​build_zarr_multiscales()

​Parameters

​Response

​predict_mosaic()

​Parameters

​Response

​predict_mosaic_geometries()

​Parameters

​Response

​predict_mosaic_geometries_recipe()

​Parameters

​Response

​predict_mosaic_recipe()

​Parameters

​Response

​run_mosaics_change()

​Parameters

​Response

​vectorize_mosaic()

​Parameters

​Response

RasterflowClient

build_gti_mosaics()

Parameters

Response

build_mosaics()

Parameters

Response

build_zarr_multiscales()

Parameters

Response

predict_mosaic()

Parameters

Response

predict_mosaic_geometries()

Parameters

Response

predict_mosaic_geometries_recipe()

Parameters

Response

predict_mosaic_recipe()

Parameters

Response

run_mosaics_change()

Parameters

Response

vectorize_mosaic()

Parameters

Response