An embedding is a vector of numbers that a geospatial foundation model produces to summarize Earth observation data, such as satellite and aerial imagery. Depending on the model, each vector covers one pixel or a patch of pixels, and summarizes a single image or many observations over time. Similar land cover, such as two cornfields, gets similar vectors, so the distance between two embeddings measures how different two places are, or how much one place changed between two dates. The
run_mosaics_change task compares the embeddings of the same place across time and gives each pixel a change score. You don’t train a model or label any data: the task measures how far each pixel’s embedding moved.
Use it to find new construction, burn scars, flooding, forest clearing, and other land-surface change, then turn the changed areas into polygons with vectorize_mosaic.
Because the embeddings are precomputed, scoring change over a large area is fast and cheap. That makes change detection a good first pass: find the small areas that changed, then run slower, more resource-intensive analysis, such as a join with building footprints or an object detection model, only on those polygons to work out what kind of change happened.
Run change detection on AlphaEarth embeddings
Google’s AlphaEarth Foundations (AEF) embeddings1 cover the globe at 10 m, with one 64-dimension embedding per pixel for each year from 2017 to 2025. A public copy is on Source Cooperative as one Zarr mosaic. This example compares 2021 with 2023 over a new subdivision north of Denham Springs, Louisiana. Run tasks with the Wherobots Python SDK, which uses your Wherobots credentials inside a Wherobots notebook or job.run_and_wait returns when the run finishes, and .output is the run’s output URI. If the run doesn’t succeed, run_and_wait raises with the run’s error message.
The inputs:
mosaic_urianddata_var: the Zarr store that holds the embeddings, and the array inside it. For AEF, the array isembeddings.distance_metric: how to compare two embeddings. Usealpha_earth_cosine_distancefor AEF. It converts AEF’s 8-bit integers back to the original values before it computes the cosine distance. The other metrics also run on AEF without an error, but they compare the 8-bit integers directly.aoi: the area to process, as polygon WKT in EPSG:4326 longitude/latitude, or the S3 URI of a GeoParquet file. See Areas of interest.time_selection: the observations to compare. Leave it out to use every year in the store.
score_methods defaults to difference, and scores are raw distances by default. Both are described below.
Read the change scores
The output,change_index_uri, is a mosaic index: a GeoParquet file whose location column lists the Zarr stores the task wrote. Each store keeps the input data_var name (embeddings for AEF) and has one band per score method. With the inputs above, the band is difference_alpha_earth_cosine_distance. Read the store’s band coordinate for the exact name when you change the method, the metric, or robust_time_zscore.
With the default raw distance, a score of 0 means the embedding didn’t change, and a larger score means it changed more. With robust_time_zscore, 0 is the pixel’s usual amount of change, and scores can be negative. With difference, each score is stored at the later of the two years it compares, so the first selected year has no score (NaN).
The output covers a little more than your area of interest, because the task reads whole blocks of the source store around it.
To see the scores, read the store’s location from the mosaic index, then map it with Wherobots-GL:
Turn changed areas into polygons
Pass the change index tovectorize_mosaic with a threshold. Pixels with a score above the threshold become polygons, and stats adds each polygon’s mean score.
None when no pixel scored above the threshold.
The change detection notebook continues this example: it joins the polygons with Overture Maps building footprints to tell new neighborhoods apart from other change.
Choose the years to compare
Pass one form oftime_selection:
Each period or timestamp must exist in the store. Datetimes without an offset use UTC.
Choose a score method
score_methods takes a list, and the output has one band per method:
difference needs at least two time steps, and the other two methods need at least three. The medoid is the time step whose embedding is closest to all the others, so loo_medoid scores how far each year is from the pixel’s usual state.
Set robust_time_zscore to true to rescale each pixel’s scores by that pixel’s own median and spread over time. This helps compare a pixel that changes every year, such as cropland, with one that rarely changes. With only a few time steps, such as annual AEF data, the z-scores are noisy, so the default is raw distance.
Use your own embeddings
You can run the task on a Zarr store of embeddings you computed yourself, for example with therun_embedding_recipe task. The store needs:
- A
timedimension with at least two time steps, and an array of embeddings. Setdata_varto that array’s name. - Georeferencing in one of two forms: a
spatial_refarray withGeoTransformandcrs_wktattributes, as rioxarray writes it, orproj:codeandspatial:transformattributes. - A nodata value. The task uses the array’s Zarr fill value. To use a different value, pass
fill_value.
cosine_distance (1 − cosine similarity) or euclidean. Use alpha_earth_cosine_distance only for AEF-style 8-bit embeddings.
Cost
A run is billed for the embedding values it reads: pixels × embedding dimensions × time steps compared, with a 1 RasterFlow Spatial Unit minimum. Comparing two years costs proportionally less than comparing every year, and the score methods you request don’t change the price. See Change Detection billing for the details and a worked example.References
- Brown, C. F., Kazmierski, M. R., Pasquarella, V. J., et al. (2025). AlphaEarth Foundations: An embedding field model for accurate and efficient global mapping from sparse label data. arXiv preprint arXiv:2507.22291. The AlphaEarth Foundations Satellite Embedding dataset is produced by Google and Google DeepMind (CC BY 4.0); the examples on this page read the Zarr mosaic of it published by Taylor Geospatial on Source Cooperative.
Next steps
Change detection notebook
Run the full example: change scores, polygons, and a join with buildings.
Run RasterFlow tasks
Run states, task outputs, and how to read a task’s inputs.

