Build Multiscales with RasterFlow

Public Preview

RasterFlow Overview

Learn about RasterFlow’s key features and capabilities

Reference

Browse the build_zarr_multiscales API documentation

RasterFlow Datasets

Learn about built-in datasets and how to bring your own.

Run as a Job

Submit RasterFlow workflows as automated Job Runs.

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 call accepts mosaics from build_mosaics and build_gti_mosaics, model outputs from predict_mosaic and its recipe variants, 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

Access to RasterFlow in your Organization.
A Wherobots notebook, a VS Code Extension workspace, or a Job Run with rasterflow_remote available.
The Micro runtime is sufficient. RasterFlow manages its own compute, so runtime size 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 workflow, or a georeferenced Zarr store of your own.
Write access to the destination bucket.

Build a multiscale Zarr store

Get the URI of the source store

Mosaic and inference workflows return a MosaicResult. Its first_row_mosaic attribute is the URI of the store for the first mosaic location, which is what you want when your Area of Interest has a single geometry.

from datetime import datetime

from rasterflow_remote import RasterflowClient
from rasterflow_remote.data_models import DatasetEnum

rf_client = RasterflowClient()

mosaic_index = rf_client.build_mosaics(
    datasets=[DatasetEnum.NAIP_30CM],
    aoi=aoi_uri,
    start=datetime(2023, 1, 1),
    end=datetime(2024, 1, 1),
    target_crs=3857,
)

mosaic_store = mosaic_index.first_row_mosaic

If your AOI produces more than one mosaic location, read mosaic_index.mosaic_index_gdf to see every output store and call build_zarr_multiscales once per store you want to visualize.

Build the visualization-ready store

optimized_store = rf_client.build_zarr_multiscales(source_store=mosaic_store)

print(f"Optimized store: {optimized_store.uri}")

The method returns a UriOutput. Its uri attribute points at the new multiscale Zarr store.

Open the result on the map

UriOutput also exposes a map_url attribute that links directly to the store in the Wherobots Cloud map viewer. It is None when no viewer URL is available for the store.

print(f"View on the map: {optimized_store.map_url}")

Opening that URL should show your imagery redrawing smoothly as you zoom, rather than stalling on full-resolution reads.

Build a visualization-ready store from a model output

Inference and change detection outputs are Zarr stores too, so the workflow is identical; build the pyramid on the prediction store.

from rasterflow_remote.data_models import ModelRecipes

model_output_index = rf_client.predict_mosaic_recipe(
    aoi=aoi_uri,
    start=datetime(2023, 1, 1),
    end=datetime(2024, 1, 1),
    model_recipe=ModelRecipes.FTW,
    target_crs="EPSG:3857",
)

model_output_store = model_output_index.first_row_mosaic
optimized_store = rf_client.build_zarr_multiscales(source_store=model_output_store)

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

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:

optimized_store = rf_client.build_zarr_multiscales(
    source_store=mosaic_store,
    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:

optimized_store = rf_client.build_zarr_multiscales(
    source_store=mosaic_store,
    histogram_dims=["band"],
)

Leaving histogram_dims as None 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

Pass bucket to write the visualization-ready store under an S3 URI prefix other than your configured Wherobots Managed Storage bucket:

optimized_store = rf_client.build_zarr_multiscales(
    source_store=mosaic_store,
    bucket="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

WorkflowExecutionError

Potential Cause: The workflow failed to start. Common reasons are a source_store URI that RasterFlow cannot read or a destination bucket it cannot write to.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 optimized_store.uri or optimized_store.map_url, 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 build_gti_mosaics.

Writes a new store rather than updating in place

The workflow always writes a new store.

One store per call

The method takes a single source_store. To build visualization-ready stores for a multi-location mosaic index, iterate over the stores in mosaic_index_gdf and call the method for each one.

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.

The resampling method is fixed

build_zarr_multiscales downsamples each overview level with a fixed resampling method and takes no resampling parameter. This is separate from build_mosaics, which does let you set resampling when the mosaic itself is built. If you need a different method for overview levels, contact support@wherobots.com.

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 the Micro runtime: RasterFlow manages its own compute, so a larger runtime adds cost without speeding up the build.

Next steps

Building NAIP mosaics

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

Run RasterFlow as a Job

Add the multiscale build to an automated, production-scale job script.

Client API reference

See the full signature, parameters, and return type for build_zarr_multiscales.

API reference

For detailed API documentation, see:

Client API Reference - RasterflowClient methods
Data Models Reference - Enums and configuration objects
Exceptions Reference - Error handling

Agentic Development

Notebook Management

RasterFlow

SQL API & SDKs

Storage Management

Other deployment options

Orchestration

Monitoring

Build Multiscales with RasterFlow

RasterFlow Overview

Reference

RasterFlow Datasets

Run as a Job

Benefits

Before you start

Build a multiscale Zarr store

Build a visualization-ready store from a model output

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

Run RasterFlow as a Job

Client API reference

API reference

RasterFlow Overview

Reference

RasterFlow Datasets

Run as a Job

​Benefits

​Before you start

​Build a multiscale Zarr store

​Build a visualization-ready store from a model output

​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

Run RasterFlow as a Job

Client API reference

​API reference

Benefits

Before you start

Build a multiscale Zarr store

Build a visualization-ready store from a model output

Control the fill value

Control histogram statistics

Route the output to a specific bucket

Troubleshooting

Limitations

Usage and best practices

Next steps

API reference