Building Sentinel-2 mosaics with RasterFlow

Public Preview

The following content is a read-only preview of an executable Jupyter notebook.To run this notebook interactively:

Go to Wherobots Cloud.
Start a runtime.
Open the notebook.
In the Jupyter Launcher:
1. Click File > Open Path.
2. Paste the following path to access this notebook: examples/Analyzing_Data/RasterFlow_S2_Mosaic.ipynb
3. Click Enter.

Build a harvest-season median, an all-bands median over a custom window, and a closest-valid composite for a single reference date. Each example uses the same Area of Interest (AOI).

Choosing a Sentinel-2 composite

S2_MED_PLANTING and S2_MED_HARVEST use latitude-based seasonal windows. The harvest example contains RGB, NIR, and a valid-pixel count:

s2med_harvest:B02 - Blue
s2med_harvest:B03 - Green
s2med_harvest:B04 - Red
s2med_harvest:B08 - NIR
s2med_harvest:N_VALID_PIXELS - Number of valid observations used in the median

For a custom UTC date window, choose one of these datasets:

S2_MEDIAN produces one per-pixel RGB+NIR median over [start, end), labelled by start.
S2_MEDIAN_ALL_BANDS uses the same window and returns all 12 L2A reflectance bands.
S2_CLOSEST_VALID produces one composite for an explicit target_date, using the inclusive candidate window [start, end].
S2_CLOSEST_VALID_BEFORE_AFTER produces two closest-valid composites at the window endpoints.

The custom-window examples require an SDK release that accepts dataset member names as strings and target_date, plus a registered Mosaics version with these datasets. Set the client’s mosaics_version to that version when it is available. Backend API and billing workers must also support the new dataset names before these examples run.

Setup and Imports

from datetime import datetime

import shapely
import wkls
import xarray as xr
from rasterflow_remote import RasterflowClient
from rasterflow_remote.data_models import DatasetEnum
from sedona.spark import *

config = SedonaContext.builder().getOrCreate()
sedona = SedonaContext.create(config)

Initializing the RasterFlow client

rf_client = RasterflowClient()

Selecting an Area of Interest (AOI)

We will use Haskell County, Kansas as our AOI. This is an agricultural region in the US Great Plains, ideal for demonstrating harvest-season imagery.

# Generate a WKT geometry for Haskell County, Kansas using Well-Known Locations (https://github.com/wherobots/wkls)
aoi = wkls.us.ks.haskellcounty.wkt()

min_lon, min_lat, max_lon, max_lat = shapely.from_wkt(aoi).bounds
print(f"Bounds: [{min_lon:.4f}, {min_lat:.4f}, {max_lon:.4f}, {max_lat:.4f}]")

Building the harvest season mosaic

This step builds a Sentinel-2 median composite mosaic for the harvest season only. The workflow will:

Query Sentinel-2 imagery for the AOI and date range
Filter to harvest season dates based on latitude
Apply cloud and quality filtering — excluding scenes with >= 75% cloud cover and masking pixels flagged as cloud, cloud shadow, cirrus, saturated/defective, or unclassified in the SCL band
Compute a pixel-wise median composite across remaining valid observations
Output the result as a Zarr store

Note: This step will take approximately 10-15 minutes to complete. If you want to skip this build_mosaics step, you can uncomment the next cell and start with a pre-generated mosaic.

# Use the pre-generated mosaic instead
# mosaic_store = "s3://wherobots-examples/rasterflow/mosaics/haskell_harvest.zarr"

mosaic_index = rf_client.build_mosaics(
    # Dataset type for harvest season median mosaic
    datasets=[DatasetEnum.S2_MED_HARVEST],
    
    # Area of Interest as WKT (EPSG:4326)
    aoi=aoi,
    
    # Date range for imagery to be used
    start=datetime(2024, 1, 1),
    end=datetime(2025, 1, 1),
    
    # Output CRS (Web Mercator)
    target_crs=3857,
)

# Inspect the mosaic index (one row per output mosaic location)
mosaic_index.mosaic_index_df.show(truncate=60)

# This example AOI has one geometry, so we select the first (only) mosaic location.
mosaic_store = mosaic_index.first_row_mosaic

mosaic_store

(Optional) Build an optimized Zarr for visualization

RasterFlow writes its outputs as Zarr stores at native resolution. To explore them interactively on cloud.wherobots.com/map, you can build an optimized multiscale Zarr. build_zarr_multiscales adds downsampled overview levels (image pyramids) to the store so the map can stream coarse tiles when zoomed out and full-resolution pixels when zoomed in. This step is optional and can take a few minutes for large outputs, so the code below is commented out by default — uncomment it to run it.

# optimized_store = rf_client.build_zarr_multiscales(source_store=mosaic_store)
# The same call works on the all-bands store: build_zarr_multiscales(source_store=all_bands_store)
# optimized_store

Visualizing outputs

You can visualize the Zarr outputs using cloud.wherobots.com/map.

Building an all-bands median over a custom window

Use S2_MEDIAN_ALL_BANDS when you need a specific date window and bands beyond RGB+NIR. It returns B01, B02, B03, B04, B05, B06, B07, B08, B8A, B09, B11, and B12 at 10 m. B10 is absent from L2A. This example creates one time step over UTC [2024-07-01, 2024-09-01), labelled 2024-07-01. It uses no seasonal heuristic. Cloud masking and per-pixel median calculation follow the harvest example above. Band names use the s2_median_all_bands prefix.

all_bands_index = rf_client.build_mosaics(
    datasets=["S2_MEDIAN_ALL_BANDS"],
    aoi=aoi,
    start=datetime(2024, 7, 1),
    end=datetime(2024, 9, 1),
    target_crs=3857,
)

all_bands_store = all_bands_index.first_row_mosaic
print(f"All-bands mosaic store: {all_bands_store}")

Building one closest-valid composite

S2_CLOSEST_VALID requires a reference date separate from the candidate window. This example searches UTC [2021-12-01, 2022-02-01] and produces one time step labelled 2022-01-01. The reference must fall within the window, and start must be earlier than end. Naive datetimes mean UTC; timezone-aware values normalize to UTC. For each pixel, the compositor chooses the nearest SCL-valid observation among the selected scenes. Earlier acquisitions win equal-distance ties. Source dates may differ across pixels; the output label is the reference date. This method uses validity and date proximity, without ranking atmospheric quality. Its reflectance bands use the s2_closest_valid prefix. Pass target_date only with S2_CLOSEST_VALID. Other datasets and mixed requests reject it. For two endpoint composites, use S2_CLOSEST_VALID_BEFORE_AFTER without target_date.

closest_valid_index = rf_client.build_mosaics(
    datasets=["S2_CLOSEST_VALID"],
    aoi=aoi,
    start=datetime(2021, 12, 1),
    end=datetime(2022, 2, 1),
    target_date=datetime(2022, 1, 1),
    target_crs=3857,
)

closest_valid_store = closest_valid_index.first_row_mosaic
print(f"Closest-valid mosaic store: {closest_valid_store}")

Next steps

Compare with a planting-season median using DatasetEnum.S2_MED_PLANTING.
Run the FTW model for field boundary detection in RasterFlow_FTW.ipynb.
Use the mosaic for model inference.

Set bucket to a persistent storage prefix when you need to retain outputs. Temporary user storage expires after seven days.

​Choosing a Sentinel-2 composite

​Setup and Imports

​Initializing the RasterFlow client

​Selecting an Area of Interest (AOI)

​Building the harvest season mosaic

​(Optional) Build an optimized Zarr for visualization

​Visualizing outputs

​Building an all-bands median over a custom window

​Building one closest-valid composite

​Next steps