> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wherobots.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Detect Change with Embeddings

> Score how much each pixel changed between years by comparing geospatial embeddings, then turn the changed areas into polygons.

Public Preview

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)](https://arxiv.org/abs/2507.22291) embeddings<sup>[1](#references)</sup> 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](https://source.coop/tge-labs/aef-mosaic) 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](https://docs.wherobots.com/develop/rasterflow/rasterflow-tasks.md#run-a-task), which uses your Wherobots credentials inside a Wherobots notebook or job.

```python theme={"system"}
import logging

import wherobots

wb = wherobots.Wherobots(region="aws-us-west-2")

# Log each task run's ID and state changes while it runs
logging.basicConfig(format="%(message)s")
logging.getLogger("wherobots").setLevel(logging.INFO)

change_index_uri = wb.tasks.run_and_wait("run_mosaics_change", {
    "mosaic_uri": "s3://us-west-2.opendata.source.coop/tge-labs/aef-mosaic/",
    "data_var": "embeddings",
    "distance_metric": "alpha_earth_cosine_distance",
    "aoi": "POLYGON ((-90.979 30.522, -90.939 30.522, -90.939 30.547, -90.979 30.547, -90.979 30.522))",
    "time_selection": {"periods": ["2021", "2023"]},
}, name="Denham Springs change 2021-2023").output
```

`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_uri`** and **`data_var`**: the Zarr store that holds the embeddings, and the array inside it. For AEF, the array is `embeddings`.
* **`distance_metric`**: how to compare two embeddings. Use `alpha_earth_cosine_distance` for 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](https://docs.wherobots.com/develop/rasterflow/rasterflow-tasks.md#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](https://docs.wherobots.com/develop/rasterflow/rasterflow-visualization.md):

```python theme={"system"}
from sedona.spark import SedonaContext
from wherobots_gl import Map

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

# The mosaic index has one row per output Zarr store
change_store = sedona.read.format("geoparquet").load(change_index_uri).first()["location"]

Map(layers=[{
    "type": "zarr",
    "source": change_store,
    "name": "AEF change score, 2021 to 2023",
    "variable": "embeddings",
    # With difference, the scores are at the later year, index 1
    "selector": {"time": {"selected": 1, "type": "index"}},
    "colormap": {"type": "preset", "preset": "magma"},
    # Leave scores under 0.1 clear so the imagery shows through
    "clim": [0.1, 0.5],
    "discardOutsideClim": True,
    "opacity": 0.85,
}], view={"zoom": 15.5, "lat": 30.5343, "lng": -90.9592}, basemap="satellite")
```

Scores aren't probabilities, so choose a threshold on the score scale: compare the map with the imagery, and pick a score that outlines the change you're looking for without picking up unrelated noise. In this example, 0.2 outlines the new subdivision.

## Turn changed areas into polygons

Pass the change index to `vectorize_mosaic` with a threshold. Pixels with a score above the threshold become polygons, and `stats` adds each polygon's mean score.

```python theme={"system"}
change_polygons_uri = wb.tasks.run_and_wait("vectorize_mosaic", {
    "mosaic_uri": change_index_uri,
    "data_var": "embeddings",
    "features": ["difference_alpha_earth_cosine_distance"],
    "threshold": 0.2,
    "stats": True,
}, name="Denham Springs change polygons").output
change_polygons_uri
```

The output is a directory of GeoParquet files, or `None` when no pixel scored above the threshold.

The [change detection notebook](https://docs.wherobots.com/tutorials/example-notebooks/rasterflow-changedetection.md) 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 of `time_selection`:

| Form | Example | Selects |
| - | - | - |
| `periods` | `{"periods": ["2021", "2024"]}` | Every observation in each year, quarter (`2021Q3`), month (`2021-06`), or day |
| `timestamps` | `{"timestamps": ["2021-06-03T10:15:00Z", "2024-06-19T09:30:00Z"]}` | Exact instants |
| `range` | `{"range": {"start": "2021", "stop": "2024"}}` | Everything between two dates, inclusive |
| `where` | `{"where": {"year": [2021, 2024], "month": [6]}}` | Observations that match every listed component |

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:

| Method | Compares each time step with | Use it for |
| - | - | - |
| `difference` (default) | The previous selected time step | Before/after change, and the year it happened |
| `loo_medoid` | The medoid of all other time steps | One-off events, such as floods, burns, or spills |
| `loo_mean` | The mean of all other time steps | Like `loo_medoid`, but a lasting change blends into the mean |

`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 the `run_embedding_recipe` task. The store needs:

* A `time` dimension with at least two time steps, and an array of embeddings. Set `data_var` to that array's name.
* Georeferencing in one of two forms: a `spatial_ref` array with `GeoTransform` and `crs_wkt` attributes, as rioxarray writes it, or `proj:code` and `spatial:transform` attributes.
* A nodata value. The task uses the array's Zarr fill value. To use a different value, pass `fill_value`.

For floating-point embeddings, use `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](https://docs.wherobots.com/get-started/organization-management/rasterflow-billing.md#change-detection) for the details and a worked example.

## References

1. **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](https://creativecommons.org/licenses/by/4.0/)); the examples on this page read the Zarr mosaic of it published by Taylor Geospatial on [Source Cooperative](https://source.coop/tge-labs/aef-mosaic).

## Next steps

> [card] [Change detection notebook](https://docs.wherobots.com/tutorials/example-notebooks/rasterflow-changedetection.md)
>
> Run the full example: change scores, polygons, and a join with buildings.

> [card] [Run RasterFlow tasks](https://docs.wherobots.com/develop/rasterflow/rasterflow-tasks.md)
>
> Run states, task outputs, and how to read a task's inputs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.