Build Multiscales with RasterFlow

Public Preview

RasterFlow writes its mosaics and model outputs as Zarr stores at a single, native resolution. That is the right format for analysis and inference, but it is a poor fit for interactive viewing: every pan or zoom has to stream full-resolution pixels, even when the whole scene is on screen at once. build_zarr_multiscales takes an existing Zarr store and writes a new, visualization-ready store that adds downsampled overview levels — an image pyramid — plus histogram statistics. A map client can then stream coarse tiles when you are zoomed out and full-resolution pixels when you zoom in.

Benefits

Interactive visualization

Overview levels let the Wherobots Cloud map viewer and the wherobots_gl.Map() widget render large mosaics responsively instead of pulling native-resolution pixels at every zoom level.

Histogram statistics

The workflow computes value distributions alongside the pyramid, so display tooling can pick sensible default color limits per band rather than guessing at a stretch.

Works on any Zarr store

The same task accepts mosaics from build_mosaics and build_gti_mosaics, model outputs from run_mosaic_inference and the recipe tasks, and change-detection outputs from run_mosaics_change. It also accepts a georeferenced Zarr store you bring yourself, so you can make your own imagery visualization-ready without running it through RasterFlow first.

Non-destructive

The source store is read, never modified. The pyramid is written to a new, visualization-ready store, so your analysis-ready output stays exactly as RasterFlow produced it.

Before you start

Wherobots requirements

A Wherobots account. RasterFlow is available to every Organization with nothing to enable.
Outside a Wherobots notebook or job, a Wherobots API key, set as WHEROBOTS_API_KEY.
For the Python examples, Python 3.11 or later with wherobots-python-sdk. The API examples need only curl.
No Wherobots runtime. RasterFlow tasks run on RasterFlow’s own compute, so where you call them from does not affect how fast the multiscale build runs.

Input requirements

A Zarr store URI that RasterFlow can read. This can be an s3:// path produced by an earlier RasterFlow task, or a georeferenced Zarr store of your own.
Write access to the destination bucket.

Build a multiscale Zarr store

The examples on this page run RasterFlow through the Tasks API, in two tabs. Python uses the Wherobots Python SDK, and API calls the REST API with curl. Outside a Wherobots notebook or job, both need a Wherobots API key in WHEROBOTS_API_KEY. Each example starts a task run; to wait for it and read its results, see Get started and Run RasterFlow Tasks.

Get the URI of the source store

The source can be any Zarr store, including a model’s predictions. This example builds a NAIP mosaic and uses the store it wrote.

# pip install wherobots-python-sdk
import wherobots

wb = wherobots.Wherobots()  # outside Wherobots, reads WHEROBOTS_API_KEY

run = wb.tasks.run("build_mosaics", {
    "datasets": ["naip_30cm"],
    "aoi": "s3://wherobots-examples/rasterflow/aois/collegepark.parquet",
    "start": "2023-01-01T00:00:00Z",
    "end": "2023-12-31T00:00:00Z",
    "target_crs": "EPSG:3857",
}, region="aws-us-west-2")
# When the run succeeds, results["mosaic_index_uri"] is the mosaic index.

curl -X POST "https://api.cloud.wherobots.com/tasks/build_mosaics/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "NAIP mosaic",
    "inputs": {
      "datasets": ["naip_30cm"],
      "aoi": "s3://wherobots-examples/rasterflow/aois/collegepark.parquet",
      "start": "2023-01-01T00:00:00Z",
      "end": "2023-12-31T00:00:00Z",
      "target_crs": "EPSG:3857"
    }
  }'

# When the run succeeds, results.mosaic_index_uri is the mosaic index.

The index lists one Zarr store per row in its location column. Most AOIs produce one; if yours produces more, build multiscales for each store you want to view. To read the index outside a Wherobots notebook, see Download a task run’s results.

Build the visualization-ready store

run = wb.tasks.run("build_zarr_multiscales", {
    "source_store": "s3://<bucket>/<path>/mosaic.zarr",  # a location from the mosaic index
}, region="aws-us-west-2")
# When the run succeeds, results["output_uri"] is the multiscale store.

# Replace the source_store value with a Zarr URI from the mosaic index's location column
curl -X POST "https://api.cloud.wherobots.com/tasks/build_zarr_multiscales/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "NAIP multiscales",
    "inputs": {
      "source_store": "s3://<bucket>/<path>/mosaic.zarr"
    }
  }'

Open the result on the map

Go to Map in Wherobots Cloud, paste the optimized store URI into Layer URL, and select Add Layer.Opening the store on the map should show your imagery redrawing smoothly as you zoom, rather than stalling on full-resolution reads.

Build multiscales on the prediction store before you vectorize it with the vectorize_mosaic task. Being able to see the raw scores on a map makes it much easier to pick a sensible threshold for vectorization.

Select an area of interest

For a single Zarr source, pass aoi as a GeoJSON or GeoParquet S3 URI with a CRS, or as nonempty polygon or multipolygon WKT in EPSG:4326. WKT coordinates use longitude, latitude order. The task transforms the AOI to the source CRS and expands its bounding window to source chunk boundaries. The output retains pixels outside the polygon within that rectangular window. AOI selection requires source georeferencing and named y and x axes.

run = wb.tasks.run("build_zarr_multiscales", {
    "source_store": "s3://<bucket>/<path>/mosaic.zarr",
    "aoi": "POLYGON ((-76.94 38.98, -76.93 38.98, -76.93 38.99, -76.94 38.99, -76.94 38.98))",
}, region="aws-us-west-2")

curl -X POST "https://api.cloud.wherobots.com/tasks/build_zarr_multiscales/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "College Park multiscales",
    "inputs": {
      "source_store": "s3://<bucket>/<path>/mosaic.zarr",
      "aoi": "POLYGON ((-76.94 38.98, -76.93 38.98, -76.93 38.99, -76.94 38.99, -76.94 38.98))"
    }
  }'

Omit aoi to process the full spatial extent. If you also pass spatial selector ranges, the task intersects them with the AOI window. Mosaic index inputs do not accept aoi, selector, or data_var.

Control the fill value

Overview levels have to know which pixels carry no data, otherwise nodata pixels get averaged into the downsampled levels and the result looks washed out or blank at coarse zooms. By default, build_zarr_multiscales uses the source array’s fill_value. When the source store does not declare one, it falls back to NaN for floating-point types and 0 for non-floating types. Set nodata explicitly when the source store’s fill value is missing or wrong:

run = wb.tasks.run("build_zarr_multiscales", {
    "source_store": "s3://<bucket>/<path>/mosaic.zarr",
    "nodata": 0,
}, region="aws-us-west-2")

curl -X POST "https://api.cloud.wherobots.com/tasks/build_zarr_multiscales/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "Multiscales with nodata 0",
    "inputs": {
      "source_store": "s3://<bucket>/<path>/mosaic.zarr",
      "nodata": 0
    }
  }'

Control histogram statistics

Use histogram_dims to choose the dimensions that get their own histogram. Passing ["band"] produces one histogram per band, which is what you want for multi-band imagery where each band has a different value range:

run = wb.tasks.run("build_zarr_multiscales", {
    "source_store": "s3://<bucket>/<path>/mosaic.zarr",
    "histogram_dims": ["band"],
}, region="aws-us-west-2")

curl -X POST "https://api.cloud.wherobots.com/tasks/build_zarr_multiscales/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "Multiscales with band histograms",
    "inputs": {
      "source_store": "s3://<bucket>/<path>/mosaic.zarr",
      "histogram_dims": ["band"]
    }
  }'

Omitting histogram_dims auto-detects: the workflow uses ["band"] if the store has a band dimension, and otherwise computes a single global histogram. The default is the right choice for most RasterFlow outputs.

Route the output to a specific bucket

When you omit storage_uri, the task writes the visualization-ready store to Wherobots Managed Storage, under a task-specific prefix. Pass storage_uri to write it under an S3 URI prefix that you choose, such as a path in your Managed Storage or a bucket with a storage integration:

run = wb.tasks.run("build_zarr_multiscales", {
    "source_store": "s3://<bucket>/<path>/mosaic.zarr",
    "storage_uri": "s3://my-bucket/rasterflow-outputs/",
}, region="aws-us-west-2")

curl -X POST "https://api.cloud.wherobots.com/tasks/build_zarr_multiscales/runs" \
  -H "X-API-Key: $WHEROBOTS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "region": "aws-us-west-2",
    "name": "Multiscales in my bucket",
    "inputs": {
      "source_store": "s3://<bucket>/<path>/mosaic.zarr",
      "storage_uri": "s3://my-bucket/rasterflow-outputs/"
    }
  }'

For the storage destinations available to RasterFlow and how access to your own bucket is authenticated, see Use RasterFlow with Storage Integration.

Troubleshooting

The task run ends FAILED or REJECTED

Potential Cause: The inputs failed validation (REJECTED), or the run could not finish (FAILED). Common reasons are a source_store URI that RasterFlow cannot read or a storage_uri it cannot write to. The run’s error_message (errorMessage in the REST API) says which.Solution:

Verify the source_store URI, including the .zarr suffix, by printing it before the call.
Confirm your storage integration grants read access to the source and write access to the destination.

Coarse zoom levels look blank or washed out

Potential Cause: Nodata pixels are being averaged into the overview levels because the source store’s fill value is missing or does not match the data.Solution:

Pass nodata explicitly to match the value your imagery actually uses for no-data pixels.
Rebuild the multiscale store after changing nodata; overview levels are computed at build time, not at read time.

The map viewer still feels slow

Potential Cause: You are viewing the source store rather than the visualization-ready one. The two URIs are different — building multiscales does not modify the source.Solution:

Open the run’s output_uri result, not the URI you passed as source_store.

Limitations

Zarr input only

build_zarr_multiscales reads Zarr stores. It does not build overviews for GeoTIFF or COG inputs; mosaic those into a Zarr store first with the build_gti_mosaics task.

Writes a new store rather than updating in place

The workflow always writes a new store.

One store per call

The task takes a single source_store. To build visualization-ready stores for a multi-location mosaic index, run the task once for each store in the index’s location column.

Inference reads one array, not the group

A visualization-ready store is a group of arrays, one per overview level. Run inference on the source store, or point at a level within the group: s3://path/to/store.zarr/0 is the full-resolution level.

Four resampling methods

resampling_method sets how each overview level is downsampled: average (the default) for continuous imagery and scores, mode or nearest to keep class values, or bilinear.

Usage and best practices

Do
Don't

Build multiscales for large stores: A native-resolution store still opens on the map, but the viewer renders it only once you zoom in far enough. Small stores are fine to view directly; large ones stay blank at coarse zoom until you build overview levels.
Build only what you intend to look at: Build multiscales on the specific mosaic or prediction store you want on a map, not on every intermediate output.
Set nodata when you know it: An explicit fill value avoids nodata bleeding into coarse overview levels.
Use mode or nearest for class maps: average blends class values into ones that don’t exist.

Don’t expect the source store to change: The source is left untouched; downstream steps must reference the run’s output_uri result to see the pyramid.
Don’t rebuild on every run: If the source store has not changed, reuse the visualization-ready store you already built.

Next steps

Building NAIP mosaics

Walk through a complete mosaic build that ends in a visualization-ready store on the map.

Visualize RasterFlow outputs

View the visualization-ready store on the map or in a notebook.

Get a task

Read the input schema, outputs, and examples for build_zarr_multiscales.

API reference

For detailed API documentation, see:

Run a task - POST /tasks/{taskName}/runs
Get a task run - state, results, and errors
Wherobots Python SDK - wb.tasks and wb.task_runs

​Benefits

​Before you start

​Build a multiscale Zarr store

​Select an area of interest

​Control the fill value

​Control histogram statistics

​Route the output to a specific bucket

​Troubleshooting

​Limitations

​Usage and best practices

​Next steps

Building NAIP mosaics

Visualize RasterFlow outputs

Get a task

​API reference

Benefits

Before you start

Build a multiscale Zarr store

Select an area of interest

Control the fill value

Control histogram statistics

Route the output to a specific bucket

Troubleshooting

Limitations

Usage and best practices

Next steps

API reference