From fdf63dc262e09a06d11c13555d20b65b41fbe8d2 Mon Sep 17 00:00:00 2001 From: elpidioassinaturas Date: Thu, 12 Nov 2026 17:26:34 -0300 Subject: [PATCH 1/4] feat(embeddings): AlphaEarth similarity and change between years (#1720) embeddings.similarity: each cell's cosine similarity to a reference point's (or points' mean) embedding. embeddings.change: 1 - cosine between a cell's embeddings of two years. Both read one AlphaEarth tile's window by range, all 64 bands, and run as background raster workflows with Cancel. The COG window reader now reads files stored bottom-up (AlphaEarth's), turning the rows north up, and asks for a batch of bands' tiles at once instead of one band after another. Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/cmd/embeddings.rs | 415 +++++++++++++++++++++++++++- crates/engine/src/cmd/layer.rs | 154 ++++++++--- crates/engine/src/cmd/tiles.rs | 2 + crates/engine/src/cmd/workflows.rs | 2 + crates/engine/src/tests.rs | 30 ++ crates/tiles/src/cog.rs | 66 +++-- docs/user-guide/web-data.md | 24 ++ 7 files changed, 621 insertions(+), 72 deletions(-) diff --git a/crates/engine/src/cmd/embeddings.rs b/crates/engine/src/cmd/embeddings.rs index 5f89d5f042..2f40334baf 100644 --- a/crates/engine/src/cmd/embeddings.rs +++ b/crates/engine/src/cmd/embeddings.rs @@ -2,6 +2,8 @@ //! datasets, a search for a dataset's tiles where the map is, and a tile shown on the map — //! AlphaEarth's as a cloud-optimised GeoTIFF of three bands, Earth Index's as points coloured by //! their vectors' principal components, Tessera's as a raster of three bands of the view. +//! AlphaEarth's vectors compared, as rasters: each cell's similarity to a reference, and how far +//! it moved between two years (#1720). //! //! On the desktop and the command line these commands read what they need, waiting for it; the //! web app reads it off the frame and hands it over (`ran`). @@ -32,6 +34,13 @@ pub fn commands() -> Vec { C::new("embeddings.addCube", "Add Satellite Embeddings over Time", "Home › Add › Web Data", add_cube).roles(&[]).effects(crate::policy::Effects::NONE.with(crate::policy::Effect::Network)).params( r#"{"dataset": "alphaearth", "bbox"?: [west, south, east, north] | "view" (the area searched, default the map's extent), "start"?: year (default 2017), "end"?: year (default 2025), "bands"?: [red, green, blue] (bands from 1, default [2, 17, 10]), "stretch"?: number (dequantised values shown over ±stretch, default 0.3), "name"?: text, "found"?: (internal: the tiles the app found, each {years: {year: address}}), "complete"?: (internal: false when the app's search read only part of the index)} → a tile layer per AlphaEarth tile, a file per year, following the time slider (turned on over the years when it is off)"#, ), + // Each makes a raster; on another thread from the app (workflows::IN_BACKGROUND). + C::new("embeddings.similarity", "Satellite Embedding Similarity", "Home › Add › Web Data", similarity).roles(&[]).effects(crate::policy::Effects::NONE.with(crate::policy::Effect::Network)).params( + r#"{"dataset": "alphaearth", "point"?: [longitude, latitude] (the reference: the embedding of the cell there), "points"?: [[longitude, latitude], …] (the reference: the mean of their cells' embeddings, at most 1000; give point or points, inside the area), "year"?: number (2017–2025, default 2024), "bbox"?: [west, south, east, north] | "view" (the area read, default the map's extent; at most about 1000 × 1000 cells), "cellSize"?: metres (an overview with cells at most this size, for a larger area), "name"?: text, "ran"?: (internal: a raster the app has worked out)} → a raster of each cell's cosine similarity to the reference's embedding, from −1 to 1, in the tile's coordinate system (UTM)"#, + ), + C::new("embeddings.change", "Satellite Embedding Change", "Home › Add › Web Data", change).roles(&[]).effects(crate::policy::Effects::NONE.with(crate::policy::Effect::Network)).params( + r#"{"dataset": "alphaearth", "from"?: year (default 2017), "to"?: year after from (default 2025), "bbox"?: [west, south, east, north] | "view" (the area read, default the map's extent; at most about 1000 × 1000 cells), "cellSize"?: metres (an overview with cells at most this size, for a larger area), "name"?: text, "ran"?: (internal: a raster the app has worked out)} → a raster of how far each cell's embedding moved between the two years, 1 − their cosine, from 0 (the same) to 2 (opposite), in the tile's coordinate system (UTM)"#, + ), ] } @@ -202,15 +211,7 @@ fn add_cube(s: &mut Session, p: &Value) -> CmdResult { return Err(format!("{}: only AlphaEarth's years make a time cube here", d.name)); } let (first, last) = d.years.unwrap_or((2017, 2025)); - // Only a year left out (or null) takes the default: one given that isn't a year is refused. - let year_param = |k: &str, default: i32| match p.get(k).filter(|v| !v.is_null()) { - None => Ok(default), - Some(_) => match f(p, k) { - Some(y) if y.fract() == 0.0 && y >= f64::from(first) && y <= f64::from(last) => Ok(y as i32), - _ => Err(format!("{k} is a year from {first} to {last}")), - }, - }; - let (start, end) = (year_param("start", first)?, year_param("end", last)?); + let (start, end) = (year_param(d, p, "start", first)?, year_param(d, p, "end", last)?); if start > end { return Err("start is a year before end, or the same one".into()); } @@ -535,6 +536,316 @@ fn add_tessera(s: &mut Session, p: &Value, d: &emb::EmbeddingDataset, name: Opti super::raster::add_raster(s, &name, layer) } +// Similarity and change (#1720): what AlphaEarth's 64 values are for. + +/// The most reference points `embeddings.similarity` takes. +const MAX_REFERENCE_POINTS: usize = 1000; + +/// AlphaEarth's no-data value: −128 of its signed bytes. +#[cfg(not(target_arch = "wasm32"))] +const AEF_NODATA: f32 = -128.0; + +/// The values a cell of an AlphaEarth file holds. +#[cfg(not(target_arch = "wasm32"))] +const AEF_BANDS: usize = 64; + +fn similarity(s: &mut Session, p: &Value) -> CmdResult { + super::workflows::made_or_ran(s, p, "embeddings.similarity") +} + +fn change(s: &mut Session, p: &Value) -> CmdResult { + super::workflows::made_or_ran(s, p, "embeddings.change") +} + +/// What a similarity or a change reads of the session: AlphaEarth checked as the dataset, the +/// area (the view, read now), the cell size and the name asked for. +type Asked = (&'static emb::EmbeddingDataset, [f64; 4], Option, Option); + +/// [`Asked`], from `embeddings.similarity`'s or `embeddings.change`'s parameters. +fn analysis(s: &Session, p: &Value) -> Result { + let d = dataset(p)?; + if d.id != "alphaearth" { + return Err(format!("{}: similarity and change are worked out from AlphaEarth's tiles only", d.name)); + } + // A plugin's command in the app runs on the frame, where nothing may wait for the files. + if s.leave_downloads { + return Err( + "AlphaEarth's files are read by the command line, Python and the assistant, not by a plugin's command in the app".into() + ); + } + let cell = match p.get("cellSize").filter(|v| !v.is_null()) { + None => None, + Some(_) => Some(f(p, "cellSize").filter(|c| c.is_finite() && *c > 0.0).ok_or("cellSize is a size in metres above 0")?), + }; + let name = ps(p, "name").map(str::trim).filter(|n| !n.is_empty()).map(|n| n.chars().take(200).collect()); + Ok((d, bbox(s, p)?, cell, name)) +} + +/// A year a command names (`k`), within the dataset's; `default` when left out (or null). One +/// given that isn't a year is refused. +fn year_param(d: &emb::EmbeddingDataset, p: &Value, k: &str, default: i32) -> Result { + let (first, last) = d.years.unwrap_or((2017, 2025)); + match p.get(k).filter(|v| !v.is_null()) { + None => Ok(default), + Some(_) => match f(p, k) { + Some(y) if y.fract() == 0.0 && y >= f64::from(first) && y <= f64::from(last) => Ok(y as i32), + _ => Err(format!("{k} is a year from {first} to {last}")), + }, + } +} + +/// `embeddings.similarity`'s reference: `point`, or the `points` whose embeddings are averaged. +fn reference_points(p: &Value) -> Result, String> { + const POINTS: &str = "points is a list of [longitude, latitude] in degrees"; + let pair = |v: &Value| { + v.as_array() + .filter(|a| a.len() == 2) + .and_then(|a| Some((a.first()?.as_f64()?, a.get(1)?.as_f64()?))) + .filter(|(x, y)| (-180.0..=180.0).contains(x) && (-90.0..=90.0).contains(y)) + }; + match (p.get("point").filter(|v| !v.is_null()), p.get("points").filter(|v| !v.is_null())) { + (Some(_), Some(_)) => Err("give point or points, not both".into()), + (Some(v), None) => Ok(vec![pair(v).ok_or("point is [longitude, latitude] in degrees")?]), + (None, Some(Value::Array(list))) if list.is_empty() => Err("points is empty: give at least one [longitude, latitude]".into()), + (None, Some(Value::Array(list))) if list.len() > MAX_REFERENCE_POINTS => { + Err(format!("{} points given: at most {MAX_REFERENCE_POINTS} make a reference", list.len())) + } + (None, Some(Value::Array(list))) => list.iter().map(|v| pair(v).ok_or_else(|| POINTS.to_string())).collect(), + (None, Some(_)) => Err(POINTS.into()), + (None, None) => Err("the reference is required: point [longitude, latitude], or points [[longitude, latitude], …]".into()), + } +} + +/// What `embeddings.similarity` reads of the session, and the work that reads the tile and +/// compares each cell's embedding with the reference. +pub(crate) fn similarity_work(s: &Session, p: &Value) -> Result { + let (d, area, cell, name) = analysis(s, p)?; + let year = year(d, p)?; + let points = reference_points(p)?; + #[cfg(target_arch = "wasm32")] + { + let _ = (area, cell, name, year, points); + Err(IN_THE_BROWSER.into()) + } + #[cfg(not(target_arch = "wasm32"))] + Ok(Box::new(move || { + rustgis_data::progress::check().map_err(|e| e.to_string())?; + let (files, place, mut notes) = tile_files(area, &[year])?; + let file = files.first().ok_or("AlphaEarth has no file there")?; + let w = read_window(file, area, cell)?; + notes.extend(w.notes()); + let r = &w.raster; + let (reference, missed) = reference(r, &points)?; + if missed > 0 { + notes.push(format!( + "{missed} of the {} reference points have no embedding in the area read (outside it, or no data there) and were left out", + points.len() + )); + } + let band = similarity_band(r, &reference)?; + let name = name.unwrap_or_else(|| format!("AlphaEarth {year} similarity")); + let raster = rustgis_analysis::rasterops::derive(r, &name, vec![band])?; + made_saying(raster, notes, json!({"year": year, "tile": place, "points": points.len() - missed})) + })) +} + +/// What `embeddings.change` reads of the session, and the work that reads the tile's two years +/// and measures how far each cell's embedding moved. +pub(crate) fn change_work(s: &Session, p: &Value) -> Result { + let (d, area, cell, name) = analysis(s, p)?; + let (first, last) = d.years.unwrap_or((2017, 2025)); + let (from, to) = (year_param(d, p, "from", first)?, year_param(d, p, "to", last)?); + if from >= to { + return Err("from is a year before to".into()); + } + #[cfg(target_arch = "wasm32")] + { + let _ = (area, cell, name, from, to); + Err(IN_THE_BROWSER.into()) + } + #[cfg(not(target_arch = "wasm32"))] + Ok(Box::new(move || { + rustgis_data::progress::check().map_err(|e| e.to_string())?; + let (files, place, mut notes) = tile_files(area, &[from, to])?; + let (Some(a), Some(b)) = (files.first(), files.get(1)) else { return Err("AlphaEarth has no files there".into()) }; + let a = read_window(a, area, cell)?; + let b = read_window(b, area, cell)?; + notes.extend(a.notes()); + let band = change_band(&a.raster, &b.raster)?; + let name = name.unwrap_or_else(|| format!("AlphaEarth change {from}–{to}")); + let raster = rustgis_analysis::rasterops::derive(&a.raster, &name, vec![band])?; + made_saying(raster, notes, json!({"from": from, "to": to, "tile": place})) + })) +} + +/// Similarity and change aren't worked out in the web app yet: nothing there may wait for files. +#[cfg(target_arch = "wasm32")] +const IN_THE_BROWSER: &str = "AlphaEarth's similarity and change are worked out on the desktop and the command line for now"; + +/// The made raster, kept as a GeoTIFF, with what to say of it once it is added (by its name on +/// the map) and what the command answers besides. +#[cfg(not(target_arch = "wasm32"))] +fn made_saying(r: rustgis_data::raster::Raster, notes: Vec, extra: Value) -> Result { + let bytes = raster::geotiff::write_all(&r).map_err(|e| e.to_string())?; + let name = r.name.clone(); + let layer = RasterLayer::from_bytes(r, format!("{name}.tif"), bytes); + let said = name.clone(); + let then: super::workflows::Then = Box::new(move |s: &mut Session, v: &mut Value| { + let id = v.get("layer").and_then(Value::as_u64).and_then(|i| u32::try_from(i).ok()); + let added = id.and_then(|id| s.map().layer(id)).map_or(said, |l| l.name.clone()); + for note in notes { + s.notify(format!("{added}: {note}"), false); + } + }); + Ok(super::workflows::made_layer(name, layer, Some(extra), Some(then))) +} + +/// AlphaEarth's files of `years` (in their order) for the tile nearest the centre of `area` that +/// has them all, from one read of the index (a wait that doesn't look at Cancel); the tile's +/// place, and what to say of the search. +#[cfg(not(target_arch = "wasm32"))] +fn tile_files(area: [f64; 4], years: &[i32]) -> Result<(Vec, String, Vec), String> { + let span = (years.iter().copied().min().unwrap_or(2024), years.iter().copied().max().unwrap_or(2024)); + let found = emb::search_aef_series_blocking(area, span)?; + let listed = years.iter().map(i32::to_string).collect::>().join(" and "); + let tile = found.series.iter().find(|t| years.iter().all(|y| t.years.contains_key(y))).ok_or_else(|| { + if found.series.is_empty() { + "AlphaEarth has no tiles there".to_string() + } else { + format!("AlphaEarth has no tile there with files for {listed}") + } + })?; + let files: Vec = years.iter().filter_map(|y| tile.years.get(y).cloned()).collect(); + let place = files.first().and_then(|u| emb::aef_place(u)).unwrap_or_else(|| tile.tile.title.clone()); + let mut notes = Vec::new(); + if !found.complete { + notes.push( + "the area holds more of AlphaEarth's index than one search reads, so a tile nearer its centre may have been missed: take a smaller box" + .to_string(), + ); + } + if found.series.len() > 1 { + notes.push(format!( + "the area meets {} AlphaEarth tiles: one is read ({place}), the nearest its centre with files for {listed}; a box within one tile is read whole", + found.series.len() + )); + } + Ok((files, place, notes)) +} + +/// A window of AlphaEarth's file `url` over `area`, every band, read on a thread of its own while +/// this one looks at the run's Cancel and stops the read once it is set. A thread the system +/// refuses costs only that: the read runs here, Cancel looked at once it is in. +#[cfg(not(target_arch = "wasm32"))] +fn read_window(url: &str, area: [f64; 4], cell: Option) -> Result { + use std::sync::atomic::{AtomicBool, Ordering}; + let asked = super::layer::WindowAsked::of(url, area, cell); + let stop = AtomicBool::new(false); + let w = std::thread::scope(|scope| { + let reader = std::thread::Builder::new() + .name("AlphaEarth window".into()) + .spawn_scoped(scope, || super::layer::read_window_raster(&asked, &stop)); + let Ok(reader) = reader else { return super::layer::read_window_raster(&asked, &stop) }; + while !reader.is_finished() { + if rustgis_data::progress::check().is_err() { + stop.store(true, Ordering::Relaxed); + } + std::thread::sleep(std::time::Duration::from_millis(50)); + } + reader.join().unwrap_or_else(|_| Err(format!("{url}: the read failed unexpectedly"))) + })?; + rustgis_data::progress::check().map_err(|e| e.to_string())?; + if w.raster.band_count() != AEF_BANDS { + return Err(format!("{url}: {} bands, where AlphaEarth's files have {AEF_BANDS}", w.raster.band_count())); + } + Ok(w) +} + +#[cfg(not(target_arch = "wasm32"))] +/// The embedding of cell `i` of `r` into `out` (one value a band), dequantised +/// (`sign(v)·(v/127.5)²`, as AlphaEarth's files are stored) and scaled to unit length, which +/// takes up the quantisation's error: `false` when a band has no value there (AlphaEarth's −128, +/// or the file's no-data) or every value is 0. +fn unit_at(r: &rustgis_data::raster::Raster, i: usize, out: &mut [f32]) -> bool { + if out.len() != r.bands.len() { + return false; + } + let mut norm = 0.0f64; + for (o, b) in out.iter_mut().zip(&r.bands) { + let Some(v) = b.data.get(i).copied().filter(|v| r.is_valid(*v) && *v != AEF_NODATA) else { return false }; + let d = (v / 127.5) * (v / 127.5) * v.signum(); + *o = d; + norm += f64::from(d) * f64::from(d); + } + if norm <= 0.0 { + return false; + } + let n = norm.sqrt() as f32; + out.iter_mut().for_each(|o| *o /= n); + true +} + +#[cfg(not(target_arch = "wasm32"))] +fn dot(a: &[f32], b: &[f32]) -> f32 { + a.iter().zip(b).map(|(x, y)| f64::from(*x) * f64::from(*y)).sum::() as f32 +} + +#[cfg(not(target_arch = "wasm32"))] +/// The reference of a similarity: the mean of the unit embeddings at `points` (longitude, +/// latitude) in `r`, scaled to unit length, and how many points have none (outside `r`, or no +/// data there). An error when none has one. +fn reference(r: &rustgis_data::raster::Raster, points: &[(f64, f64)]) -> Result<(Vec, usize), String> { + let (mut sum, mut v, mut missed) = (vec![0.0f64; r.bands.len()], vec![0.0f32; r.bands.len()], 0usize); + for &(lon, lat) in points { + let cell = r.pixel_at(rustgis_geom::Coord::new(lon, lat)).map(|(c, row)| row as usize * r.width as usize + c as usize); + match cell { + Some(i) if unit_at(r, i, &mut v) => sum.iter_mut().zip(&v).for_each(|(s, x)| *s += f64::from(*x)), + _ => missed += 1, + } + } + if missed == points.len() { + return Err("no reference point has an embedding in the area read: give points inside the box, where the tile has data".into()); + } + let norm = sum.iter().map(|s| s * s).sum::().sqrt(); + if norm <= 0.0 { + return Err("the reference points' embeddings cancel out: their mean is zero".into()); + } + Ok((sum.iter().map(|s| (s / norm) as f32).collect(), missed)) +} + +#[cfg(not(target_arch = "wasm32"))] +/// Each cell's cosine similarity to `reference` (a unit vector), from −1 to 1; no data where the +/// cell has no embedding. +fn similarity_band(r: &rustgis_data::raster::Raster, reference: &[f32]) -> Result, String> { + let (n, k) = (r.width as usize * r.height as usize, reference.len()); + rustgis_analysis::rasterops::per_index( + n, + r.width as usize, + k, + || vec![0.0f32; k], + |v, i| if unit_at(r, i, v) { dot(v, reference).clamp(-1.0, 1.0) } else { rustgis_analysis::rasterops::NODATA }, + ) +} + +#[cfg(not(target_arch = "wasm32"))] +/// How far each cell's embedding moved from `a` to `b` (two years of one tile, on one grid): +/// 1 − their cosine, from 0 (the same) to 2 (opposite); no data where either has none. +fn change_band(a: &rustgis_data::raster::Raster, b: &rustgis_data::raster::Raster) -> Result, String> { + if (a.width, a.height, a.transform, a.crs, a.bands.len()) != (b.width, b.height, b.transform, b.crs, b.bands.len()) { + return Err("the two years' files of the tile aren't on one grid, so they can't be compared cell by cell".into()); + } + let (n, k) = (a.width as usize * a.height as usize, a.bands.len()); + rustgis_analysis::rasterops::per_index( + n, + a.width as usize, + 2 * k, + || (vec![0.0f32; k], vec![0.0f32; k]), + |(x, y), i| { + if unit_at(a, i, x) && unit_at(b, i, y) { (1.0 - dot(x, y)).clamp(0.0, 2.0) } else { rustgis_analysis::rasterops::NODATA } + }, + ) +} + #[cfg(test)] mod tests { use super::*; @@ -754,4 +1065,90 @@ mod tests { assert!(s.run("embeddings.add", &json!({"dataset": "earth-index", "ran": id})).is_err()); assert!(!s.downloaded.iter().any(|(d, _)| *d == id)); } + + /// A 2 × 2 raster of quantised embeddings (one value a band, as AlphaEarth stores them), in + /// longitude/latitude over 10–12° E, 44–46° N, cells by row from the north-west. + fn quantised(cells: [[f32; 3]; 4]) -> rustgis_data::raster::Raster { + let bands = (0..3).map(|b| cells.iter().map(|c| c[b]).collect()).collect(); + let t = rustgis_data::raster::GeoTransform { origin_x: 10.0, origin_y: 46.0, pixel_width: 1.0, pixel_height: -1.0 }; + let (crs, gray) = (rustgis_data::raster::Crs::LonLat, rustgis_data::raster::ColorHint::Gray); + rustgis_data::raster::Raster::new("aef", 2, 2, bands, t, crs, Some(-128.0), gray, "Int8").unwrap() + } + + #[test] + fn similarity_and_change_of_known_vectors() { + use rustgis_analysis::rasterops::NODATA; + let v = [100.0, -50.0, 20.0]; + let opposite = [-100.0, 50.0, -20.0]; + // Half of v quantised: dequantised (squared) it is a quarter of v's, the same direction. + let half = [50.0, -25.0, 10.0]; + let no_data = [100.0, -128.0, 20.0]; + let r = quantised([v, opposite, no_data, half]); + // The cells' centres: (10.5, 45.5), (11.5, 45.5), (10.5, 44.5), (11.5, 44.5). + let (one, missed) = reference(&r, &[(10.5, 45.5)]).unwrap(); + assert_eq!(missed, 0); + let close = |got: Vec, want: [f32; 4]| { + got.iter().zip(want).all(|(g, w)| if w == NODATA { *g == NODATA } else { (g - w).abs() < 1e-6 }) + }; + let sim = similarity_band(&r, &one).unwrap(); + assert!(close(sim.clone(), [1.0, -1.0, NODATA, 1.0]), "{sim:?}"); + // Several points: their mean. One off the raster and one on no data are counted, not used. + let (mean, missed) = reference(&r, &[(10.5, 45.5), (11.5, 44.5), (30.0, 0.0), (10.5, 44.5)]).unwrap(); + assert_eq!(missed, 2); + assert!(close(similarity_band(&r, &mean).unwrap(), [1.0, -1.0, NODATA, 1.0])); + assert!(reference(&r, &[(30.0, 0.0), (10.5, 44.5)]).unwrap_err().contains("no reference point")); + // Opposite points cancel out. + assert!(reference(&r, &[(10.5, 45.5), (11.5, 45.5)]).unwrap_err().contains("cancel out")); + // Change: the same 0, a quarter of the length still 0, opposite 2, no data either year no data. + let later = quantised([v, v, v, v]); + let moved = change_band(&r, &later).unwrap(); + assert!(close(moved.clone(), [0.0, 2.0, NODATA, 0.0]), "{moved:?}"); + // A vector of zeros has no direction: no data. + let zero = quantised([[0.0; 3], v, v, v]); + assert_eq!(change_band(&zero, &later).unwrap()[0], NODATA); + // Two grids that differ aren't compared. + let mut shifted = quantised([v, v, v, v]); + shifted.transform.origin_x += 1.0; + assert!(change_band(&r, &shifted).unwrap_err().contains("one grid")); + } + + #[test] + fn similarity_and_change_parameters() { + let mut s = Session::new(Project::default()); + let area = json!([10.0, 45.0, 10.1, 45.1]); + for bad in [ + json!({}), + json!({"dataset": "tessera", "point": [10.05, 45.05], "bbox": area}), + json!({"dataset": "alphaearth", "bbox": area}), + json!({"dataset": "alphaearth", "point": [10.05, 45.05], "points": [[10.05, 45.05]], "bbox": area}), + json!({"dataset": "alphaearth", "point": [10.05], "bbox": area}), + json!({"dataset": "alphaearth", "point": [200, 45], "bbox": area}), + json!({"dataset": "alphaearth", "points": [], "bbox": area}), + json!({"dataset": "alphaearth", "points": [[10.05, 45.05], "x"], "bbox": area}), + json!({"dataset": "alphaearth", "points": vec![json!([10.05, 45.05]); 1001], "bbox": area}), + json!({"dataset": "alphaearth", "points": "here", "bbox": area}), + json!({"dataset": "alphaearth", "point": [10.05, 45.05], "year": 2016, "bbox": area}), + json!({"dataset": "alphaearth", "point": [10.05, 45.05], "cellSize": 0, "bbox": area}), + json!({"dataset": "alphaearth", "point": [10.05, 45.05], "bbox": [1, 0, 0, 1]}), + json!({"dataset": "alphaearth", "point": [10.05, 45.05], "ran": 7, "bbox": area}), + ] { + assert!(s.run("embeddings.similarity", &bad).is_err(), "{bad}"); + } + for bad in [ + json!({"dataset": "earth-index", "bbox": area}), + json!({"dataset": "alphaearth", "from": 2020, "to": 2020, "bbox": area}), + json!({"dataset": "alphaearth", "from": 2024, "to": 2018, "bbox": area}), + json!({"dataset": "alphaearth", "from": 2016, "bbox": area}), + json!({"dataset": "alphaearth", "to": 2025.5, "bbox": area}), + json!({"dataset": "alphaearth", "cellSize": -10, "bbox": area}), + json!({"dataset": "alphaearth", "bbox": "here"}), + ] { + assert!(s.run("embeddings.change", &bad).is_err(), "{bad}"); + } + assert!(s.map().layers.is_empty()); + // A plugin's command in the app is refused before anything waits on the frame. + s.leave_downloads = true; + let e = s.run("embeddings.change", &json!({"dataset": "alphaearth", "bbox": area})).unwrap_err(); + assert!(e.contains("plugin"), "{e}"); + } } diff --git a/crates/engine/src/cmd/layer.rs b/crates/engine/src/cmd/layer.rs index 51572354b5..eb3ecec829 100644 --- a/crates/engine/src/cmd/layer.rs +++ b/crates/engine/src/cmd/layer.rs @@ -4385,7 +4385,7 @@ fn add_in_place( #[cfg(not(target_arch = "wasm32"))] const MAX_WINDOW_VALUES: u64 = if cfg!(test) { 300_000 } else { crate::render::rustgis_tiles::cog::MAX_VALUES_READ }; -/// The most bands a window reads: each band is a read of its own (8 under test, whose examples +/// The most bands a window reads, [`WINDOW_BATCH`] a read (8 under test, whose examples /// have 16 bands at most). #[cfg(not(target_arch = "wasm32"))] const MAX_WINDOW_BANDS: usize = if cfg!(test) { 8 } else { 256 }; @@ -4394,6 +4394,10 @@ const MAX_WINDOW_BANDS: usize = if cfg!(test) { 8 } else { 256 }; #[cfg(not(target_arch = "wasm32"))] const WINDOW_WAIT: std::time::Duration = std::time::Duration::from_secs(300); +/// The bands of a window read together, at most: their tiles asked for at once. +#[cfg(not(target_arch = "wasm32"))] +const WINDOW_BATCH: usize = 16; + /// The extension an address's file name has (lowercase, without the dot), if it has one: the /// query and fragment aside. pub(crate) fn address_extension(url: &str) -> Option { @@ -4487,6 +4491,16 @@ pub struct WindowAsked { name: Option, } +#[cfg(not(target_arch = "wasm32"))] +impl WindowAsked { + /// A window of the file at `url` over `bbox` (west, south, east, north in degrees), with the + /// coarsest level whose cells are at most `cell` (the full image without), as `layer.addUrl` + /// with that box and `"cellSize"` reads it. + pub(crate) fn of(url: &str, bbox: [f64; 4], cell: Option) -> WindowAsked { + WindowAsked { url: url.to_string(), bbox, cell, name: None } + } +} + #[cfg(all(test, not(target_arch = "wasm32")))] impl WindowAsked { pub(crate) fn bbox(&self) -> [f64; 4] { @@ -4563,11 +4577,11 @@ pub fn read_cog_window(asked: &WindowAsked) -> Result { read_cog_window_until(asked, &std::sync::atomic::AtomicBool::new(false)) } -/// [`read_cog_window`], giving up within a moment of `stop` being set (the app's Cancel of the -/// download, or its project closed): in the wait on the header, before each band and in the wait -/// on its tiles. Making the raster and writing its GeoTIFF, once the values are in, don't look. +/// [`read_cog_window`]'s raster, giving up within a moment of `stop` being set (the app's Cancel of +/// the download, or its project closed): in the wait on the header, before each batch of bands +/// and in the wait on their tiles. Making the raster, once the values are in, doesn't look. #[cfg(not(target_arch = "wasm32"))] -pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::AtomicBool) -> Result { +pub(crate) fn read_window_raster(asked: &WindowAsked, stop: &std::sync::atomic::AtomicBool) -> Result { use crate::render::rustgis_tiles::cog; use rustgis_data::raster::cog::Level; let url = asked.url.as_str(); @@ -4582,9 +4596,12 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom if !(pw.is_finite() && ph.is_finite() && pw != 0.0 && ph != 0.0) { return Err(named("its header gives no pixel size, so no window can be placed in it".into())); } - if ph > 0.0 || pw < 0.0 { - return Err(named("it isn't stored north up, which a window doesn't read yet".into())); + if pw < 0.0 { + return Err(named("it is stored east to west, which a window doesn't read yet".into())); } + // Stored bottom-up (AlphaEarth's files): the rows are read south first, and turned over once + // read, so the window is north up as any other. + let bottom_up = ph > 0.0; // The box in the file's coordinates: its edges at 32 points each, and each piece halved until // it is straight in the file to within a quarter of its pixel. A projected file bends them (a // parallel in a conic projection is an arc whose lowest point can fall between two points). @@ -4668,8 +4685,12 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom let at = |v: f64, most: u32| v.clamp(0.0, f64::from(most)) as u32; let (c0, c1) = (at(((x0 - lt.origin_x) / lt.pixel_width).floor(), l.width), at(((x1 - lt.origin_x) / lt.pixel_width).ceil(), l.width)); - let (r0, r1) = - (at(((y1 - lt.origin_y) / lt.pixel_height).floor(), l.height), at(((y0 - lt.origin_y) / lt.pixel_height).ceil(), l.height)); + // The file's first row is its northern edge, or its southern one when stored bottom-up. + let (first, last) = if bottom_up { (y0, y1) } else { (y1, y0) }; + let (r0, r1) = ( + at(((first - lt.origin_y) / lt.pixel_height).floor(), l.height), + at(((last - lt.origin_y) / lt.pixel_height).ceil(), l.height), + ); (c0, c1, r0, r1) }; let values = |l: &Level| { @@ -4691,12 +4712,13 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom // onto the pixels isn't a cut). let cut: Vec<&str> = { let lt = layout.transform_of(lv); - let (fx1, fy0) = (lt.origin_x + f64::from(lv.width) * lt.pixel_width, lt.origin_y + f64::from(lv.height) * lt.pixel_height); + let (fx1, fy) = (lt.origin_x + f64::from(lv.width) * lt.pixel_width, lt.origin_y + f64::from(lv.height) * lt.pixel_height); + let (south, north) = (fy.min(lt.origin_y), fy.max(lt.origin_y)); [ ("west", x0 < lt.origin_x - tolerance), ("east", x1 > fx1 + tolerance), - ("south", y0 < fy0 - tolerance), - ("north", y1 > lt.origin_y + tolerance), + ("south", y0 < south - tolerance), + ("north", y1 > north + tolerance), ] .into_iter() .filter_map(|(side, past)| past.then_some(side)) @@ -4721,26 +4743,40 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom if count > MAX_WINDOW_BANDS { return Err(named(format!("the file has {count} bands; a window reads {MAX_WINDOW_BANDS} at most"))); } - // One read a band, each waiting up to two minutes; no band is started once five minutes are - // up (the header's read counted), so the last one started may run two minutes more. + // One read a batch of bands (their tiles asked for together, so a file of many bands stored + // apart isn't read one band after another), each waiting up to two minutes; no batch is + // started once five minutes are up (the header's read counted), so the last one started may + // run two minutes more. // The values `f32` rounded (32- and 64-bit whole numbers and floats), a count a band, are said // when the layer is added, as for a file read whole. // Those past its range can't be held: left out (no value), and said apart. let (mut bands, mut rounded, mut overflowed) = (Vec::with_capacity(count), Vec::with_capacity(count), 0u64); - for band in 0..count { - band_in_time(band, count, started.elapsed(), WINDOW_WAIT).map_err(named)?; - let (values, changed, past) = - cog::read_values_counted_blocking(&info, url, level, band, (c0, c1), (r0, r1), stop).map_err(named)?; - bands.push(values); - rounded.push(changed); - overflowed += past; + let all: Vec = (0..count).collect(); + for batch in all.chunks(WINDOW_BATCH) { + band_in_time(batch.first().copied().unwrap_or(0), count, started.elapsed(), WINDOW_WAIT).map_err(named)?; + for (values, changed, past) in + cog::read_bands_counted_blocking(&info, url, level, batch, (c0, c1), (r0, r1), stop).map_err(named)? + { + bands.push(values); + rounded.push(changed); + overflowed += past; + } } let lt = layout.transform_of(lv); - let transform = rustgis_data::raster::GeoTransform { + let mut transform = rustgis_data::raster::GeoTransform { origin_x: lt.origin_x + f64::from(c0) * lt.pixel_width, origin_y: lt.origin_y + f64::from(r0) * lt.pixel_height, ..lt }; + if bottom_up { + let width = (c1 - c0) as usize; + for band in &mut bands { + let rows: Vec = band.chunks(width.max(1)).rev().flatten().copied().collect(); + *band = rows; + } + transform.origin_y = lt.origin_y + f64::from(r1) * lt.pixel_height; + transform.pixel_height = -lt.pixel_height; + } let color = match &layout.palette { Some(table) if bands.len() == 1 => rustgis_data::raster::ColorHint::Palette(table.clone()), _ => layout.color.clone(), @@ -4764,6 +4800,35 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom if let Some(described) = &layout.described { r.apply_pam(described, rustgis_data::raster::pam::GDAL_METADATA); } + let size = size_of(lv); + let of = if level == 0 { "the full image".to_string() } else { format!("overview {level} of {}", layout.levels.len() - 1) }; + let read = format!("a {} × {} window of {of}, cells of {size:.1}{unit}, read by range from its address", r.width, r.height); + let finer = finer.map(|c| format!("cellSize {c} is finer than the file's finest cells ({size:.1}{unit}): the full image is read")); + let mut edges = Vec::new(); + if !cut.is_empty() { + edges.push(format!("the box reaches past the file's {} edge(s): the window is cut to the file", cut.join(", "))); + } + if unrefined > 0 { + edges.push(format!( + "{unrefined} piece(s) of the box's edges not followed to a quarter of a pixel: the window may fall short of a bent edge" + )); + } + if unplaced > 0 { + edges.push(format!( + "{unplaced} of the {points} points tested along the box's edges have no place in the file's coordinate system: the window is placed from the others" + )); + } + Ok(WindowRaster { raster: r, read, finer, edges, columns: [c0, c1], rows: [r0, r1], level, cell_size: size }) +} + +/// [`read_cog_window`], giving up within a moment of `stop` being set (the app's Cancel of the +/// download, or its project closed): in the wait on the header, before each band and in the wait +/// on its tiles. Making the raster and writing its GeoTIFF, once the values are in, don't look. +#[cfg(not(target_arch = "wasm32"))] +pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::AtomicBool) -> Result { + let named = |e: String| crate::sources::message_with_address(&asked.url, &e); + let WindowRaster { raster: r, read, finer, edges, columns, rows, level, cell_size } = read_window_raster(asked, stop)?; + let name = asked.name.clone().unwrap_or_else(|| cog_name(&asked.url)); // Kept in the project as a GeoTIFF of the window: a cloud-optimised one, which keeps a colour // table; one it can't write (a palette with no index left for no-data) is kept plain, and said so. // Neither writes more bands than colour (or grey and alpha) takes: the others are said. @@ -4784,32 +4849,39 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom bytes } }; - let (width, height, size) = (r.width, r.height, size_of(lv)); let layer = rustgis_map::RasterLayer::from_bytes(r, format!("{name}.tif"), bytes); - let of = if level == 0 { "the full image".to_string() } else { format!("overview {level} of {}", layout.levels.len() - 1) }; - let mut notes = vec![format!("a {width} × {height} window of {of}, cells of {size:.1}{unit}, read by range from its address")]; + let mut notes = vec![read]; notes.extend(plain); - if let Some(c) = finer { - notes.push(format!("cellSize {c} is finer than the file's finest cells ({size:.1}{unit}): the full image is read")); - } + notes.extend(finer); if left_out > 0 { let kept = band_count - left_out; notes.push(format!("the project keeps {kept} of its {band_count} bands: {left_out} band(s) are left out once it is reopened")); } - if !cut.is_empty() { - notes.push(format!("the box reaches past the file's {} edge(s): the window is cut to the file", cut.join(", "))); - } - if unrefined > 0 { - notes.push(format!( - "{unrefined} piece(s) of the box's edges not followed to a quarter of a pixel: the window may fall short of a bent edge" - )); - } - if unplaced > 0 { - notes.push(format!( - "{unplaced} of the {points} points tested along the box's edges have no place in the file's coordinate system: the window is placed from the others" - )); + notes.extend(edges); + Ok(CogWindow { name, layer, notes, columns, rows, level, cell_size }) +} + +/// A window's raster as [`read_window_raster`] reads it, every band kept, and what to say of the +/// read: its size and level, a cell size finer than the file's, and the box's edges (cut to the +/// file, not followed, unplaced). +#[cfg(not(target_arch = "wasm32"))] +pub(crate) struct WindowRaster { + pub(crate) raster: rustgis_data::raster::Raster, + read: String, + finer: Option, + edges: Vec, + columns: [u32; 2], + rows: [u32; 2], + level: usize, + cell_size: f64, +} + +#[cfg(not(target_arch = "wasm32"))] +impl WindowRaster { + /// What to say of the read, in order. + pub(crate) fn notes(&self) -> Vec { + std::iter::once(self.read.clone()).chain(self.finer.clone()).chain(self.edges.iter().cloned()).collect() } - Ok(CogWindow { name, layer, notes, columns: [c0, c1], rows: [r0, r1], level, cell_size: size }) } /// Adds a window read by [`read_cog_window`] and says what it read. `p` is the command adding it diff --git a/crates/engine/src/cmd/tiles.rs b/crates/engine/src/cmd/tiles.rs index c6ac8f7922..3fdb784bed 100644 --- a/crates/engine/src/cmd/tiles.rs +++ b/crates/engine/src/cmd/tiles.rs @@ -49,6 +49,8 @@ pub const NETWORK: &[&str] = &[ "embeddings.search", "embeddings.add", "embeddings.addCube", + "embeddings.similarity", + "embeddings.change", "earthdata.collections", "earthdata.granules", "nldi.flowline", diff --git a/crates/engine/src/cmd/workflows.rs b/crates/engine/src/cmd/workflows.rs index 6b19b655cb..5a7c47b969 100644 --- a/crates/engine/src/cmd/workflows.rs +++ b/crates/engine/src/cmd/workflows.rs @@ -201,6 +201,8 @@ pub(crate) const IN_BACKGROUND: &[(&str, &str, Start)] = &[ ("raster.process", "Process", super::imagery::process_work), ("imagery.mosaic", "Build Mosaic", super::imagery::mosaic_work), ("dl.classify", "Deep Learning", super::deeplearning::classify_work), + ("embeddings.similarity", "Satellite Embedding Similarity", super::embeddings::similarity_work), + ("embeddings.change", "Satellite Embedding Change", super::embeddings::change_work), ]; /// `command` and what it is called, when it makes its raster on another thread from the app (see diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index fe4d24cafc..7f7e8d1cd8 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -37758,6 +37758,33 @@ fn a_cog_windows_read_is_apart_from_adding_it() { assert!(e.contains("/a.tif") && !e.contains("hidden-1330"), "{e}"); } +/// A window of a file stored bottom-up, as AlphaEarth's are (planar signed bytes, no-data −128, a +/// positive Y pixel size; #1720): its rows turned over once read, so the raster is north up, its +/// values where they lie and its no-data kept. +#[test] +fn a_bottom_up_cog_window_comes_in_north_up() { + use rustgis_data::raster::cog::{Example, example_with}; + // 1024 pixels over 10°–11° E, 45°–46° N, the file's row y at 45° + y/1024; band b of pixel + // (x, y) is (x + y + 10 b) % 100 − 50, and pixel (0, 0), the south-west corner, is no-data. + let e = Example { size: 1024, tile: 256, bands: 2, planar: true, int8: true, bottom_up: true, ..Example::default() }; + let (base, _) = serve_ranges(example_with(&e)); + let mut s = world(); + let url = format!("{base}/aef.tif"); + let r = s.run("layer.addUrl", &json!({"url": url, "bbox": [10.25, 45.5, 10.5, 45.75], "name": "Up"})).unwrap(); + assert_eq!(r["window"]["columns"], json!([256, 512])); + let w = s.map().layer_by_name("Up").and_then(|l| l.raster.as_ref()?.data.clone()).unwrap(); + assert_eq!((w.width, w.height, w.band_count()), (256, 256, 2)); + assert_eq!((w.transform.origin_x, w.transform.origin_y), (10.25, 45.75)); + assert!(w.transform.pixel_height < 0.0); + // The window's north-west cell is the file's (256, 767); five rows down and ten across, (266, 762). + assert_eq!((w.value(0, 0, 0), w.value(1, 0, 0), w.value(0, 10, 5)), (Some(-27.0), Some(-17.0), Some(-22.0))); + // At the file's south-west corner, the window's bottom-left cell is the file's no-data. + s.run("layer.addUrl", &json!({"url": url, "bbox": [10.0, 45.0, 10.01, 45.01], "name": "Corner"})).unwrap(); + let c = s.map().layer_by_name("Corner").and_then(|l| l.raster.as_ref()?.data.clone()).unwrap(); + assert_eq!((c.value(0, 0, i64::from(c.height) - 1), c.value(0, 1, i64::from(c.height) - 1)), (None, Some(-49.0))); + assert_eq!(c.transform.origin_y, 45.0 + f64::from(c.height) / 1024.0); +} + /// `layer.addUrl` with `"bbox"` (#1204): a window of a cloud-optimised GeoTIFF, read by range as a /// raster layer, at full resolution or at the overview a cell size asks for; a palette file's /// colours and class names come with it; the window is kept in a saved project, class names too. @@ -43302,6 +43329,9 @@ fn long_commands_stop_when_cancelled_while_they_run() { "dl.classify", json!({"layer": "scene", "training": "training", "classField": "class", "bands": [1, 2], "epochs": 30, "model": "landcover"}), ), + // Cancelled before the index is read: nothing reaches the network. + ("embeddings.similarity", json!({"dataset": "alphaearth", "point": [10.01, 45.01], "bbox": [10.0, 45.0, 10.02, 45.02]})), + ("embeddings.change", json!({"dataset": "alphaearth", "bbox": [10.0, 45.0, 10.02, 45.02]})), ]; // Every command that runs in the background is here, and only those. fn listed<'a>(l: &[(&'a str, Value)]) -> std::collections::BTreeSet<&'a str> { diff --git a/crates/tiles/src/cog.rs b/crates/tiles/src/cog.rs index 229460081d..947d975b4e 100644 --- a/crates/tiles/src/cog.rs +++ b/crates/tiles/src/cog.rs @@ -1512,9 +1512,27 @@ pub fn read_values_counted_blocking( rows: (u32, u32), stop: &std::sync::atomic::AtomicBool, ) -> Result<(Vec, u64, u64), String> { + let mut read = read_bands_counted_blocking(info, url, level, &[band], cols, rows, stop)?; + read.pop().ok_or_else(|| "no band was read".to_string()) +} + +/// [`read_values_counted_blocking`] for several bands of the window at once (in their order): their +/// tiles are asked for together, so the reads of a file whose bands are stored apart (a chunk a +/// band, as AlphaEarth's 64) overlap instead of following one another. The two minutes are for +/// them all. +#[cfg(not(target_arch = "wasm32"))] +pub fn read_bands_counted_blocking( + info: &Arc, + url: &str, + level: usize, + bands: &[usize], + cols: (u32, u32), + rows: (u32, u32), + stop: &std::sync::atomic::AtomicBool, +) -> Result, u64, u64)>, String> { let url = split(url).0.to_string(); let l = info.layout.levels.get(level).ok_or("no such overview")?; - if band >= info.layout.bands.max(1) { + if bands.iter().any(|b| *b >= info.layout.bands.max(1)) { return Err(format!("the file has {} band(s)", info.layout.bands)); } // The window's size checked before its values are allocated: a caller's window, not the file. @@ -1526,8 +1544,13 @@ pub fn read_values_counted_blocking( // The part of the window inside the file. let (x0, x1) = (cols.0.min(l.width), cols.1.min(l.width)); let (y0, y1) = (rows.0.min(l.height), rows.1.min(l.height)); + // Reserved first: a window the machine can't hold is an error, not a crash (#1291). + let mut outs = bands + .iter() + .map(|_| rustgis_data::raster::filled(w, h, f32::NAN).map(|v| (v, 0u64, 0u64)).map_err(|e| e.to_string())) + .collect::, String>>()?; if x1 <= x0 || y1 <= y0 { - return Ok((rustgis_data::raster::filled(w, h, f32::NAN).map_err(|e| e.to_string())?, 0, 0)); + return Ok(outs); } let (tw, th, across) = (l.tile_width.max(1), l.tile_height.max(1), l.across().max(1)); // The tiles the window takes, counted before they are listed, in checked arithmetic: a @@ -1539,39 +1562,38 @@ pub fn read_values_counted_blocking( } let tiles: Vec = (r0..=r1).flat_map(|ty| (c0..=c1).filter_map(move |tx| ty.checked_mul(across).and_then(|t| t.checked_add(tx)))).collect(); - // Reserved first: a window the machine can't hold is an error, not a crash (#1291). - let (mut out, mut rounded, mut overflowed) = (rustgis_data::raster::filled(w, h, f32::NAN).map_err(|e| e.to_string())?, 0u64, 0u64); if stop.load(std::sync::atomic::Ordering::Relaxed) { return Err(message_with_address(&url, STOPPED)); } let (tx, rx) = std::sync::mpsc::channel(); - fetch_bands(info.clone(), url.clone(), level, tiles.clone(), vec![band], Box::new(move |r| tx.send(r).unwrap_or_default())); + fetch_bands(info.clone(), url.clone(), level, tiles.clone(), bands.to_vec(), Box::new(move |r| tx.send(r).unwrap_or_default())); let picked = wait_until(&rx, Duration::from_secs(120), stop).map_err(|stopped| stopped_or(stopped, &url, "tiles not read in two minutes"))??; let nodata = info.layout.nodata.map(|v| v as f32); for (&t, p) in tiles.iter().zip(&picked) { - let Some((chunk, b)) = p.first() else { continue }; - let Some(values) = chunk.get(*b) else { continue }; let (tx0, ty0) = ((t % across).saturating_mul(tw), (t / across).saturating_mul(th)); - for py in ty0.max(y0)..ty0.saturating_add(th).min(y1) { - for px in tx0.max(x0)..tx0.saturating_add(tw).min(x1) { - let i = (py - ty0) as usize * tw as usize + (px - tx0) as usize; - let Some(&v) = values.get(i) else { continue }; - // A marked value past `f32`'s range is infinite: left out as no value, and - // counted apart from those rounded. No-data isn't marked. - if chunk.rounded_at(*b, i) { - if v.is_infinite() { overflowed += 1 } else { rounded += 1 } - } - if v.is_finite() - && Some(v) != nodata - && let Some(slot) = out.get_mut((py - rows.0) as usize * w + (px - cols.0) as usize) - { - *slot = v; + for ((chunk, b), (out, rounded, overflowed)) in p.iter().zip(outs.iter_mut()) { + let Some(values) = chunk.get(*b) else { continue }; + for py in ty0.max(y0)..ty0.saturating_add(th).min(y1) { + for px in tx0.max(x0)..tx0.saturating_add(tw).min(x1) { + let i = (py - ty0) as usize * tw as usize + (px - tx0) as usize; + let Some(&v) = values.get(i) else { continue }; + // A marked value past `f32`'s range is infinite: left out as no value, and + // counted apart from those rounded. No-data isn't marked. + if chunk.rounded_at(*b, i) { + if v.is_infinite() { *overflowed += 1 } else { *rounded += 1 } + } + if v.is_finite() + && Some(v) != nodata + && let Some(slot) = out.get_mut((py - rows.0) as usize * w + (px - cols.0) as usize) + { + *slot = v; + } } } } } - Ok((out, rounded, overflowed)) + Ok(outs) } #[cfg(test)] diff --git a/docs/user-guide/web-data.md b/docs/user-guide/web-data.md index df7f4bedb9..568594147d 100644 --- a/docs/user-guide/web-data.md +++ b/docs/user-guide/web-data.md @@ -756,4 +756,28 @@ rustgis-cli run --cmd 'map.zoomToExtent={"extent":[-42.91,-20.78,-42.85,-20.735] rustgis-cli run --cmd 'map.zoomToExtent={"extent":[-83.96,35.94,-83.9,35.98]}' --cmd 'embeddings.add={"dataset":"tessera","year":2024}' --cmd 'share.exportMap={"path":"tessera.png"}' ``` +AlphaEarth's 64 values have no meaning one by one, so a picture of three of them only shows where +places differ. What they are for is comparing places and years, which two commands do over the map's +extent (or `"bbox"`), reading one AlphaEarth tile's window by range, all 64 bands (at most about +1000 × 1000 cells, 10 × 10 km; `"cellSize"` reads an overview for a larger area). Each makes a +32-bit raster in the tile's UTM coordinate system; a cell with no embedding (AlphaEarth's −128) has +no value. + +- `embeddings.similarity` (`"point"`: [longitude, latitude], or `"points"`: up to 1000 of them, + averaged; `"year"`, 2024 by default): each cell's cosine similarity to the reference's embedding, + from −1 to 1. 1 is a place like the reference. Reference points outside the area read, or on no + data, are left out and said. +- `embeddings.change` (`"from"`, 2017 by default, and `"to"`, 2025): how far each cell's embedding + moved between the two years, 1 − their cosine, from 0 (unchanged) to 2. + +The vectors are dequantised (`sign(v)·(v/127.5)²`) and scaled to unit length first. When the area +meets several tiles, the one nearest its centre with the years asked for is read, and the others +are said: keep the area within one tile. They run on the desktop and the command line (in the web +app, not yet), and there is no button for them yet: + +```sh +rustgis-cli run --cmd 'embeddings.similarity={"dataset":"alphaearth","year":2024,"point":[-42.88,-20.75],"bbox":[-42.91,-20.78,-42.85,-20.735]}' --cmd 'share.exportMap={"path":"aef_similarity.png"}' +rustgis-cli run --cmd 'embeddings.change={"dataset":"alphaearth","from":2017,"to":2025,"bbox":[-42.91,-20.78,-42.85,-20.735]}' --cmd 'share.exportMap={"path":"aef_change.png"}' +``` + These reach the network: the AI Assistant asks first and plugins need the network permission. From 3d3fa079f4a4960ea0d010ecd3a8d132d044fa55 Mon Sep 17 00:00:00 2001 From: elpidioassinaturas Date: Thu, 12 Nov 2026 21:30:59 -0300 Subject: [PATCH 2/4] fix(embeddings): review round 1 for similarity and change (#1720) - Tiles past a search's 60 are said, counted in the tiles the area meets, and named when none of the kept ones has the years; the pick moved into pick_tile, tested with the notices both ways. - A batch of window bands waits two minutes a band, within the bound band-by-band reading had (batch_wait). - An AlphaEarth file without 64 bands is refused from its header. - Doc comments: why the commands run on their caller's thread, the batch wording, and why change says the first window's notes. Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/cmd/embeddings.rs | 125 +++++++++++++++++++++++----- crates/engine/src/cmd/layer.rs | 43 +++++++--- crates/engine/src/cmd/workflows.rs | 2 +- crates/engine/src/tests.rs | 9 ++ crates/tiles/src/cog.rs | 14 +++- 5 files changed, 159 insertions(+), 34 deletions(-) diff --git a/crates/engine/src/cmd/embeddings.rs b/crates/engine/src/cmd/embeddings.rs index 2f40334baf..0577e0595b 100644 --- a/crates/engine/src/cmd/embeddings.rs +++ b/crates/engine/src/cmd/embeddings.rs @@ -549,10 +549,18 @@ const AEF_NODATA: f32 = -128.0; #[cfg(not(target_arch = "wasm32"))] const AEF_BANDS: usize = 64; +/// `embeddings.similarity` (#1720), the raster [`similarity_work`] makes. Run as a command, it +/// works on its caller's thread, waiting for AlphaEarth's index and the window: the command line +/// and Python have no window to hold, and the app's workflows start it on a thread +/// ([`super::workflows::raster_start`]) and add what it made with `ran`. The app's assistant runs +/// its tools on the frame, so there the window waits, as it does for `raster.change` and the other +/// commands that read the network; a plugin's command in the app is refused ([`analysis`]). fn similarity(s: &mut Session, p: &Value) -> CmdResult { super::workflows::made_or_ran(s, p, "embeddings.similarity") } +/// `embeddings.change` (#1720), the raster [`change_work`] makes: on its caller's thread, as +/// [`similarity`] says. fn change(s: &mut Session, p: &Value) -> CmdResult { super::workflows::made_or_ran(s, p, "embeddings.change") } @@ -636,12 +644,7 @@ pub(crate) fn similarity_work(s: &Session, p: &Value) -> Result 0 { - notes.push(format!( - "{missed} of the {} reference points have no embedding in the area read (outside it, or no data there) and were left out", - points.len() - )); - } + notes.extend(missed_points(missed, points.len())); let band = similarity_band(r, &reference)?; let name = name.unwrap_or_else(|| format!("AlphaEarth {year} similarity")); let raster = rustgis_analysis::rasterops::derive(r, &name, vec![band])?; @@ -670,6 +673,8 @@ pub(crate) fn change_work(s: &Session, p: &Value) -> Result, extra: Value #[cfg(not(target_arch = "wasm32"))] fn tile_files(area: [f64; 4], years: &[i32]) -> Result<(Vec, String, Vec), String> { let span = (years.iter().copied().min().unwrap_or(2024), years.iter().copied().max().unwrap_or(2024)); - let found = emb::search_aef_series_blocking(area, span)?; + pick_tile(&emb::search_aef_series_blocking(area, span)?, years) +} + +/// [`tile_files`]'s pick from what the search `found`: the first tile (the nearest the area's +/// centre) with files for all of `years`, and what to say of the search (part of the index read, +/// tiles past a search's list left out, the others the area meets). +#[cfg(not(target_arch = "wasm32"))] +fn pick_tile(found: &emb::SeriesFound, years: &[i32]) -> Result<(Vec, String, Vec), String> { let listed = years.iter().map(i32::to_string).collect::>().join(" and "); - let tile = found.series.iter().find(|t| years.iter().all(|y| t.years.contains_key(y))).ok_or_else(|| { - if found.series.is_empty() { - "AlphaEarth has no tiles there".to_string() - } else { - format!("AlphaEarth has no tile there with files for {listed}") - } + let (kept, dropped) = (found.series.len(), found.dropped); + let tile = found.series.iter().find(|t| years.iter().all(|y| t.years.contains_key(y))).ok_or_else(|| match (kept, dropped) { + (0, 0) => "AlphaEarth has no tiles there".to_string(), + (_, 0) => format!("AlphaEarth has no tile there with files for {listed}"), + _ => format!( + "none of the {kept} AlphaEarth tiles nearest the area's centre has files for {listed}, and {dropped} more were left out: take a smaller box" + ), })?; let files: Vec = years.iter().filter_map(|y| tile.years.get(y).cloned()).collect(); let place = files.first().and_then(|u| emb::aef_place(u)).unwrap_or_else(|| tile.tile.title.clone()); @@ -724,22 +737,36 @@ fn tile_files(area: [f64; 4], years: &[i32]) -> Result<(Vec, String, Vec .to_string(), ); } - if found.series.len() > 1 { + if dropped > 0 { + notes.push(format!( + "{dropped} AlphaEarth tiles past the {} nearest the area's centre were left out, not looked at: take a smaller box", + emb::MAX_TILES + )); + } + if kept + dropped > 1 { notes.push(format!( "the area meets {} AlphaEarth tiles: one is read ({place}), the nearest its centre with files for {listed}; a box within one tile is read whole", - found.series.len() + kept + dropped )); } Ok((files, place, notes)) } +/// What a similarity says of its reference points that have no embedding in the area read. +#[cfg(not(target_arch = "wasm32"))] +fn missed_points(missed: usize, of: usize) -> Option { + (missed > 0).then(|| { + format!("{missed} of the {of} reference points have no embedding in the area read (outside it, or no data there) and were left out") + }) +} + /// A window of AlphaEarth's file `url` over `area`, every band, read on a thread of its own while /// this one looks at the run's Cancel and stops the read once it is set. A thread the system /// refuses costs only that: the read runs here, Cancel looked at once it is in. #[cfg(not(target_arch = "wasm32"))] fn read_window(url: &str, area: [f64; 4], cell: Option) -> Result { use std::sync::atomic::{AtomicBool, Ordering}; - let asked = super::layer::WindowAsked::of(url, area, cell); + let asked = super::layer::WindowAsked::of(url, area, cell, AEF_BANDS); let stop = AtomicBool::new(false); let w = std::thread::scope(|scope| { let reader = std::thread::Builder::new() @@ -755,9 +782,6 @@ fn read_window(url: &str, area: [f64; 4], cell: Option) -> Result| { + let raster = rustgis_analysis::rasterops::derive(&r, name, vec![vec![0.5; 4]]).unwrap(); + made_saying(raster, notes, json!({"year": 2024})).unwrap() + }; + let mark = s.notice_mark(); + let v = super::super::workflows::add_made(&mut s, made("Sim", notes.clone())).unwrap(); + assert_eq!(v["year"], 2024); + let said: Vec = s.notices_since(mark).iter().map(|n| n.text.clone()).collect(); + assert_eq!(said.iter().filter(|n| n.starts_with("Sim: ")).count(), 3, "{said:?}"); + let mark = s.notice_mark(); + super::super::workflows::add_made(&mut s, made("Clean", Vec::new())).unwrap(); + assert!(!s.notices_since(mark).iter().any(|n| n.text.starts_with("Clean: "))); + } } diff --git a/crates/engine/src/cmd/layer.rs b/crates/engine/src/cmd/layer.rs index eb3ecec829..7d73bdbaf4 100644 --- a/crates/engine/src/cmd/layer.rs +++ b/crates/engine/src/cmd/layer.rs @@ -4398,6 +4398,10 @@ const WINDOW_WAIT: std::time::Duration = std::time::Duration::from_secs(300); #[cfg(not(target_arch = "wasm32"))] const WINDOW_BATCH: usize = 16; +/// How long a window's band may be waited for: a batch of bands has this much a band. +#[cfg(not(target_arch = "wasm32"))] +const BAND_WAIT: std::time::Duration = std::time::Duration::from_secs(120); + /// The extension an address's file name has (lowercase, without the dot), if it has one: the /// query and fragment aside. pub(crate) fn address_extension(url: &str) -> Option { @@ -4489,15 +4493,19 @@ pub struct WindowAsked { bbox: [f64; 4], cell: Option, name: Option, + /// The bands the file must have, when the caller needs a number of them (checked from its + /// header, before anything else is read). + bands: Option, } #[cfg(not(target_arch = "wasm32"))] impl WindowAsked { /// A window of the file at `url` over `bbox` (west, south, east, north in degrees), with the /// coarsest level whose cells are at most `cell` (the full image without), as `layer.addUrl` - /// with that box and `"cellSize"` reads it. - pub(crate) fn of(url: &str, bbox: [f64; 4], cell: Option) -> WindowAsked { - WindowAsked { url: url.to_string(), bbox, cell, name: None } + /// with that box and `"cellSize"` reads it; a file without `bands` bands is refused from its + /// header. + pub(crate) fn of(url: &str, bbox: [f64; 4], cell: Option, bands: usize) -> WindowAsked { + WindowAsked { url: url.to_string(), bbox, cell, name: None, bands: Some(bands) } } } @@ -4532,7 +4540,7 @@ fn window_settled(s: &Session, p: &Value, url: &str, seen: Option<[f64; 4]>) -> Some(v) => Some(v.as_f64().filter(|c| c.is_finite() && *c > 0.0).ok_or_else(|| named("cellSize is a size above 0".into()))?), }; let name = ps(p, "name").map(str::trim).filter(|n| !n.is_empty()).map(String::from); - Ok(WindowAsked { url: url.to_string(), bbox, cell, name }) + Ok(WindowAsked { url: url.to_string(), bbox, cell, name, bands: None }) } /// A window the app reads off the frame: `p`, a `layer.addUrl` with `"bbox"` and its address bound @@ -4740,13 +4748,17 @@ pub(crate) fn read_window_raster(asked: &WindowAsked, stop: &std::sync::atomic:: ))); } let count = layout.bands.max(1); + if let Some(want) = asked.bands.filter(|n| *n != count) { + return Err(named(format!("it has {count} band(s), where {want} are needed"))); + } if count > MAX_WINDOW_BANDS { return Err(named(format!("the file has {count} bands; a window reads {MAX_WINDOW_BANDS} at most"))); } // One read a batch of bands (their tiles asked for together, so a file of many bands stored - // apart isn't read one band after another), each waiting up to two minutes; no batch is - // started once five minutes are up (the header's read counted), so the last one started may - // run two minutes more. + // apart isn't read one band after another), each waiting up to two minutes a band + // ([`batch_wait`]); no batch is started once five minutes are up (the header's read counted), + // and none runs past two minutes more, as the last band started could when they were read + // one at a time. // The values `f32` rounded (32- and 64-bit whole numbers and floats), a count a band, are said // when the layer is added, as for a file read whole. // Those past its range can't be held: left out (no value), and said apart. @@ -4754,8 +4766,9 @@ pub(crate) fn read_window_raster(asked: &WindowAsked, stop: &std::sync::atomic:: let all: Vec = (0..count).collect(); for batch in all.chunks(WINDOW_BATCH) { band_in_time(batch.first().copied().unwrap_or(0), count, started.elapsed(), WINDOW_WAIT).map_err(named)?; + let wait = batch_wait(batch.len(), started.elapsed()); for (values, changed, past) in - cog::read_bands_counted_blocking(&info, url, level, batch, (c0, c1), (r0, r1), stop).map_err(named)? + cog::read_bands_counted_blocking(&info, url, level, batch, (c0, c1), (r0, r1), wait, stop).map_err(named)? { bands.push(values); rounded.push(changed); @@ -4822,8 +4835,9 @@ pub(crate) fn read_window_raster(asked: &WindowAsked, stop: &std::sync::atomic:: } /// [`read_cog_window`], giving up within a moment of `stop` being set (the app's Cancel of the -/// download, or its project closed): in the wait on the header, before each band and in the wait -/// on its tiles. Making the raster and writing its GeoTIFF, once the values are in, don't look. +/// download, or its project closed): in the wait on the header, before each batch of bands and in +/// the wait on their tiles. Making the raster and writing its GeoTIFF, once the values are in, +/// don't look. #[cfg(not(target_arch = "wasm32"))] pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::AtomicBool) -> Result { let named = |e: String| crate::sources::message_with_address(&asked.url, &e); @@ -4915,6 +4929,15 @@ pub(crate) fn band_in_time(band: usize, count: usize, elapsed: std::time::Durati Ok(()) } +/// How long a batch of `bands` bands of a window may wait for its tiles, `elapsed` into the +/// window's read: two minutes a band, but no later than two minutes past the window's wait (when +/// the last batch may still start), and never less than one band's two minutes. +#[cfg(not(target_arch = "wasm32"))] +pub(crate) fn batch_wait(bands: usize, elapsed: std::time::Duration) -> std::time::Duration { + let left = (WINDOW_WAIT + BAND_WAIT).saturating_sub(elapsed).max(BAND_WAIT); + BAND_WAIT.saturating_mul(u32::try_from(bands.max(1)).unwrap_or(u32::MAX)).min(left) +} + /// A window can't be read in the web app yet: nothing there may wait for the tiles. #[cfg(target_arch = "wasm32")] fn add_cog_window(_: &mut Session, _: &Value, url: &str) -> CmdResult { diff --git a/crates/engine/src/cmd/workflows.rs b/crates/engine/src/cmd/workflows.rs index 5a7c47b969..7550d1bb57 100644 --- a/crates/engine/src/cmd/workflows.rs +++ b/crates/engine/src/cmd/workflows.rs @@ -168,7 +168,7 @@ pub(crate) fn made_layer(name: String, layer: rustgis_map::RasterLayer, extra: O /// Adds a made raster as a layer: the command's answer is the layer's (its id, size and bands) and /// what the command says besides (`extra`), and what it does then. -fn add_made(s: &mut Session, m: Made) -> CmdResult { +pub(crate) fn add_made(s: &mut Session, m: Made) -> CmdResult { let Made { name, layer, extra, then, .. } = m; let mut v = super::raster::add_raster(s, &name, layer)?; if let (Some(Value::Object(more)), Some(o)) = (extra, v.as_object_mut()) { diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index 7f7e8d1cd8..f5e331442a 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -37510,6 +37510,15 @@ fn a_windows_bands_are_started_within_its_wait() { assert!(band_in_time(3, 4, Duration::from_secs(299), wait).is_ok()); let e = band_in_time(2, 4, Duration::from_secs(301), wait).unwrap_err(); assert_eq!(e, "2 of 4 bands read in 5 minutes, so the window is given up: take a smaller box or a larger cellSize"); + // A batch of bands waits two minutes a band, within the window's five minutes and the two + // past them the last band started had. + use crate::cmd::layer::batch_wait; + let s = Duration::from_secs; + assert_eq!(batch_wait(1, s(0)), s(120)); + assert_eq!(batch_wait(2, s(0)), s(240)); + assert_eq!(batch_wait(16, s(0)), s(420)); + assert_eq!(batch_wait(16, s(299)), s(121)); + assert_eq!(batch_wait(16, s(400)), s(120), "a band's two minutes at least"); } /// A script or model the desktop app runs off the frame, as a plugin's command, leaves a window to diff --git a/crates/tiles/src/cog.rs b/crates/tiles/src/cog.rs index 947d975b4e..b045f0af44 100644 --- a/crates/tiles/src/cog.rs +++ b/crates/tiles/src/cog.rs @@ -1512,15 +1512,16 @@ pub fn read_values_counted_blocking( rows: (u32, u32), stop: &std::sync::atomic::AtomicBool, ) -> Result<(Vec, u64, u64), String> { - let mut read = read_bands_counted_blocking(info, url, level, &[band], cols, rows, stop)?; + let mut read = read_bands_counted_blocking(info, url, level, &[band], cols, rows, Duration::from_secs(120), stop)?; read.pop().ok_or_else(|| "no band was read".to_string()) } /// [`read_values_counted_blocking`] for several bands of the window at once (in their order): their /// tiles are asked for together, so the reads of a file whose bands are stored apart (a chunk a -/// band, as AlphaEarth's 64) overlap instead of following one another. The two minutes are for +/// band, as AlphaEarth's 64) overlap instead of following one another. It waits up to `wait` for /// them all. #[cfg(not(target_arch = "wasm32"))] +#[allow(clippy::too_many_arguments)] pub fn read_bands_counted_blocking( info: &Arc, url: &str, @@ -1528,6 +1529,7 @@ pub fn read_bands_counted_blocking( bands: &[usize], cols: (u32, u32), rows: (u32, u32), + wait: Duration, stop: &std::sync::atomic::AtomicBool, ) -> Result, u64, u64)>, String> { let url = split(url).0.to_string(); @@ -1567,8 +1569,12 @@ pub fn read_bands_counted_blocking( } let (tx, rx) = std::sync::mpsc::channel(); fetch_bands(info.clone(), url.clone(), level, tiles.clone(), bands.to_vec(), Box::new(move |r| tx.send(r).unwrap_or_default())); - let picked = - wait_until(&rx, Duration::from_secs(120), stop).map_err(|stopped| stopped_or(stopped, &url, "tiles not read in two minutes"))??; + let late = if wait == Duration::from_secs(120) { + "tiles not read in two minutes".to_string() + } else { + format!("tiles not read in {} s", wait.as_secs()) + }; + let picked = wait_until(&rx, wait, stop).map_err(|stopped| stopped_or(stopped, &url, &late))??; let nodata = info.layout.nodata.map(|v| v as f32); for (&t, p) in tiles.iter().zip(&picked) { let (tx0, ty0) = ((t % across).saturating_mul(tw), (t / across).saturating_mul(th)); From 71498af32fef8bcd26815c8d33fa6832cb359311 Mon Sep 17 00:00:00 2001 From: elpidioassinaturas Date: Fri, 13 Nov 2026 00:03:26 -0300 Subject: [PATCH 3/4] fix(embeddings): say a window's header losses and the search's gaps (#1720) - WindowRaster::notes() ends with the raster's lost (what the header holds but isn't read), which a similarity or change made from the window said nowhere. - pick_tile says duplicate tile-years, and a part of the index read when no tile qualifies. - Docs: the examples save the result as a GeoTIFF with share.exportRaster; share.exportMap's PNG is a preview. Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/cmd/embeddings.rs | 47 +++++++++++++++++++---------- crates/engine/src/cmd/layer.rs | 10 ++++-- crates/engine/src/tests.rs | 20 ++++++++++++ docs/user-guide/web-data.md | 7 +++-- 4 files changed, 63 insertions(+), 21 deletions(-) diff --git a/crates/engine/src/cmd/embeddings.rs b/crates/engine/src/cmd/embeddings.rs index 0577e0595b..7522cd34f9 100644 --- a/crates/engine/src/cmd/embeddings.rs +++ b/crates/engine/src/cmd/embeddings.rs @@ -721,12 +721,16 @@ fn tile_files(area: [f64; 4], years: &[i32]) -> Result<(Vec, String, Vec fn pick_tile(found: &emb::SeriesFound, years: &[i32]) -> Result<(Vec, String, Vec), String> { let listed = years.iter().map(i32::to_string).collect::>().join(" and "); let (kept, dropped) = (found.series.len(), found.dropped); - let tile = found.series.iter().find(|t| years.iter().all(|y| t.years.contains_key(y))).ok_or_else(|| match (kept, dropped) { - (0, 0) => "AlphaEarth has no tiles there".to_string(), - (_, 0) => format!("AlphaEarth has no tile there with files for {listed}"), - _ => format!( - "none of the {kept} AlphaEarth tiles nearest the area's centre has files for {listed}, and {dropped} more were left out: take a smaller box" - ), + let tile = found.series.iter().find(|t| years.iter().all(|y| t.years.contains_key(y))).ok_or_else(|| { + let none = match (kept, dropped) { + (0, 0) => "AlphaEarth has no tiles there".to_string(), + (_, 0) => format!("AlphaEarth has no tile there with files for {listed}"), + _ => format!( + "none of the {kept} AlphaEarth tiles nearest the area's centre has files for {listed}, and {dropped} more were left out: take a smaller box" + ), + }; + // A part of the index read: the tile may be in the rest of it. + if found.complete { none } else { format!("{none}, in the part of the index that was read: take a smaller box to read it whole") } })?; let files: Vec = years.iter().filter_map(|y| tile.years.get(y).cloned()).collect(); let place = files.first().and_then(|u| emb::aef_place(u)).unwrap_or_else(|| tile.tile.title.clone()); @@ -743,6 +747,9 @@ fn pick_tile(found: &emb::SeriesFound, years: &[i32]) -> Result<(Vec, St emb::MAX_TILES )); } + if found.duplicates > 0 { + notes.push(format!("{} tile-years had a second file in AlphaEarth's index; the first was taken", found.duplicates)); + } if kept + dropped > 1 { notes.push(format!( "the area meets {} AlphaEarth tiles: one is read ({place}), the nearest its centre with files for {listed}; a box within one tile is read whole", @@ -1199,22 +1206,30 @@ mod tests { // The nearest tile without 2017: the next one is read. Part of the index read, and three // tiles past a search's list: each said, the tiles counted with them. let many = - emb::SeriesFound { series: vec![tile("0-0", &[2025]), tile("0-1", &[2017, 2025])], dropped: 3, duplicates: 0, complete: false }; + emb::SeriesFound { series: vec![tile("0-0", &[2025]), tile("0-1", &[2017, 2025])], dropped: 3, duplicates: 2, complete: false }; let (files, place, notes) = pick_tile(&many, &[2017, 2025]).unwrap(); assert_eq!((files.len(), place.as_str()), (2, "23S 0-1")); - assert_eq!(notes.len(), 3, "{notes:?}"); + assert_eq!(notes.len(), 4, "{notes:?}"); assert!(notes[0].contains("a tile nearer its centre may have been missed"), "{notes:?}"); assert_eq!(notes[1], "3 AlphaEarth tiles past the 60 nearest the area's centre were left out, not looked at: take a smaller box"); - assert!(notes[2].starts_with("the area meets 5 AlphaEarth tiles: one is read (23S 0-1)"), "{notes:?}"); - // No tile with the years: tiles left out are said, not taken for none there. + assert_eq!(notes[2], "2 tile-years had a second file in AlphaEarth's index; the first was taken"); + assert!(notes[3].starts_with("the area meets 5 AlphaEarth tiles: one is read (23S 0-1)"), "{notes:?}"); + // No tile with the years: tiles left out are said, not taken for none there, and so is a + // part of the index read. + let e = pick_tile(&many, &[2018]).unwrap_err(); + assert!(e.contains("none of the 2 AlphaEarth tiles nearest the area's centre has files for 2018, and 3 more"), "{e}"); assert!( - pick_tile(&many, &[2018]) - .unwrap_err() - .contains("none of the 2 AlphaEarth tiles nearest the area's centre has files for 2018, and 3 more") + e.ends_with( + "and 3 more were left out: take a smaller box, in the part of the index that was read: take a smaller box to read it whole" + ), + "{e}" ); - let kept = emb::SeriesFound { dropped: 0, complete: true, ..many.clone() }; + let kept = emb::SeriesFound { dropped: 0, duplicates: 0, complete: true, ..many.clone() }; assert_eq!(pick_tile(&kept, &[2018]).unwrap_err(), "AlphaEarth has no tile there with files for 2018"); - assert_eq!(pick_tile(&emb::SeriesFound::default(), &[2018]).unwrap_err(), "AlphaEarth has no tiles there"); + assert_eq!( + pick_tile(&emb::SeriesFound { complete: true, ..emb::SeriesFound::default() }, &[2018]).unwrap_err(), + "AlphaEarth has no tiles there" + ); // Reference points with no embedding: said with a count, nothing when all have one. assert_eq!(missed_points(0, 3), None); assert_eq!( @@ -1233,7 +1248,7 @@ mod tests { let v = super::super::workflows::add_made(&mut s, made("Sim", notes.clone())).unwrap(); assert_eq!(v["year"], 2024); let said: Vec = s.notices_since(mark).iter().map(|n| n.text.clone()).collect(); - assert_eq!(said.iter().filter(|n| n.starts_with("Sim: ")).count(), 3, "{said:?}"); + assert_eq!(said.iter().filter(|n| n.starts_with("Sim: ")).count(), 4, "{said:?}"); let mark = s.notice_mark(); super::super::workflows::add_made(&mut s, made("Clean", Vec::new())).unwrap(); assert!(!s.notices_since(mark).iter().any(|n| n.text.starts_with("Clean: "))); diff --git a/crates/engine/src/cmd/layer.rs b/crates/engine/src/cmd/layer.rs index 7d73bdbaf4..75c637d85c 100644 --- a/crates/engine/src/cmd/layer.rs +++ b/crates/engine/src/cmd/layer.rs @@ -4892,9 +4892,15 @@ pub(crate) struct WindowRaster { #[cfg(not(target_arch = "wasm32"))] impl WindowRaster { - /// What to say of the read, in order. + /// What to say of the read, in order, and what its raster left out (`lost`: what the header + /// holds but isn't read, values past `f32`'s range), for a caller that makes another raster + /// from it and so doesn't add this one (whose `lost` the layer would say). pub(crate) fn notes(&self) -> Vec { - std::iter::once(self.read.clone()).chain(self.finer.clone()).chain(self.edges.iter().cloned()).collect() + std::iter::once(self.read.clone()) + .chain(self.finer.clone()) + .chain(self.edges.iter().cloned()) + .chain(self.raster.lost.iter().cloned()) + .collect() } } diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index f5e331442a..cf5a754640 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -37794,6 +37794,26 @@ fn a_bottom_up_cog_window_comes_in_north_up() { assert_eq!(c.transform.origin_y, 45.0 + f64::from(c.height) / 1024.0); } +/// A window read for a raster made from it (AlphaEarth's similarity and change, #1720) says what +/// its header left out, as `layer.addUrl` says it when it adds the window; a clean file, nothing. +#[test] +fn a_window_read_for_another_raster_says_what_its_header_left_out() { + use crate::cmd::layer::{WindowAsked, read_window_raster}; + use rustgis_data::raster::cog::{Example, example, example_with}; + let stop = std::sync::atomic::AtomicBool::new(false); + let (lossy, _) = serve_ranges(example_with(&Example { size: 512, tile: 256, classes: true, lossy: true, ..Example::default() })); + let w = read_window_raster(&WindowAsked::of(&format!("{lossy}/lossy.tif"), [10.0, 45.0, 10.5, 45.5], None, 1), &stop).unwrap(); + let notes = w.notes(); + assert!(notes.iter().any(|n| n.starts_with("its colour table has 384 entries")), "{notes:?}"); + assert!(notes.iter().any(|n| n.contains("its GDAL metadata: 1 CLASS_ item(s)")), "{notes:?}"); + let (clean, _) = serve_ranges(example(512, 256)); + let w = read_window_raster(&WindowAsked::of(&format!("{clean}/clean.tif"), [10.0, 45.0, 10.5, 45.5], None, 1), &stop).unwrap(); + assert_eq!(w.notes().len(), 1, "only the read: {:?}", w.notes()); + // A file without the bands asked for is refused from its header. + let e = read_window_raster(&WindowAsked::of(&format!("{clean}/clean.tif"), [10.0, 45.0, 10.5, 45.5], None, 64), &stop).err().unwrap(); + assert!(e.contains("it has 1 band(s), where 64 are needed"), "{e}"); +} + /// `layer.addUrl` with `"bbox"` (#1204): a window of a cloud-optimised GeoTIFF, read by range as a /// raster layer, at full resolution or at the overview a cell size asks for; a palette file's /// colours and class names come with it; the window is kept in a saved project, class names too. diff --git a/docs/user-guide/web-data.md b/docs/user-guide/web-data.md index 568594147d..256c2f655c 100644 --- a/docs/user-guide/web-data.md +++ b/docs/user-guide/web-data.md @@ -773,11 +773,12 @@ no value. The vectors are dequantised (`sign(v)·(v/127.5)²`) and scaled to unit length first. When the area meets several tiles, the one nearest its centre with the years asked for is read, and the others are said: keep the area within one tile. They run on the desktop and the command line (in the web -app, not yet), and there is no button for them yet: +app, not yet), and there is no button for them yet. Each adds its raster as a layer: `share.exportRaster` +saves its values as a GeoTIFF, and `share.exportMap` a PNG preview of the map: ```sh -rustgis-cli run --cmd 'embeddings.similarity={"dataset":"alphaearth","year":2024,"point":[-42.88,-20.75],"bbox":[-42.91,-20.78,-42.85,-20.735]}' --cmd 'share.exportMap={"path":"aef_similarity.png"}' -rustgis-cli run --cmd 'embeddings.change={"dataset":"alphaearth","from":2017,"to":2025,"bbox":[-42.91,-20.78,-42.85,-20.735]}' --cmd 'share.exportMap={"path":"aef_change.png"}' +rustgis-cli run --cmd 'embeddings.similarity={"dataset":"alphaearth","year":2024,"point":[-42.88,-20.75],"bbox":[-42.91,-20.78,-42.85,-20.735]}' --cmd 'share.exportRaster={"layer":"AlphaEarth 2024 similarity","path":"aef_similarity.tif"}' --cmd 'share.exportMap={"path":"aef_similarity.png"}' +rustgis-cli run --cmd 'embeddings.change={"dataset":"alphaearth","from":2017,"to":2025,"bbox":[-42.91,-20.78,-42.85,-20.735]}' --cmd 'share.exportRaster={"layer":"AlphaEarth change 2017–2025","path":"aef_change.tif"}' --cmd 'share.exportMap={"path":"aef_change.png"}' ``` These reach the network: the AI Assistant asks first and plugins need the network permission. From 1d7c4a7fb7910b1ab61c78c525532b5558de5fbb Mon Sep 17 00:00:00 2001 From: elpidioassinaturas Date: Fri, 13 Nov 2026 02:01:39 -0300 Subject: [PATCH 4/4] fix(embeddings): a change says the second year's file losses too (#1720) The read's notes are said once (the two windows are on one grid), and each file's header losses by its year, once for both when both files lost the same thing (two_years_notes; WindowRaster::read_notes). Co-Authored-By: Claude Opus 5.5 --- crates/engine/src/cmd/embeddings.rs | 23 ++++++++++++++++++++--- crates/engine/src/cmd/layer.rs | 12 +++++++----- crates/engine/src/tests.rs | 14 ++++++++++++++ 3 files changed, 41 insertions(+), 8 deletions(-) diff --git a/crates/engine/src/cmd/embeddings.rs b/crates/engine/src/cmd/embeddings.rs index 7522cd34f9..f4953844a3 100644 --- a/crates/engine/src/cmd/embeddings.rs +++ b/crates/engine/src/cmd/embeddings.rs @@ -673,9 +673,7 @@ pub(crate) fn change_work(s: &Session, p: &Value) -> Result Result<(Vec, St Ok((files, place, notes)) } +/// What a change says of its two years' windows: what the first says of its read (the windows +/// are on one grid, so the second's says the same; anything it adds is said too, by its year), +/// and what each file's header left out, by year: once, for both, when both left it out. +#[cfg(not(target_arch = "wasm32"))] +pub(crate) fn two_years_notes(a: &super::layer::WindowRaster, b: &super::layer::WindowRaster, (from, to): (i32, i32)) -> Vec { + let mut notes = a.read_notes(); + for n in b.read_notes() { + if !notes.contains(&n) { + notes.push(format!("the {to} file: {n}")); + } + } + for l in &a.raster.lost { + let both = b.raster.lost.contains(l); + notes.push(if both { format!("the {from} and {to} files: {l}") } else { format!("the {from} file: {l}") }); + } + notes.extend(b.raster.lost.iter().filter(|l| !a.raster.lost.contains(l)).map(|l| format!("the {to} file: {l}"))); + notes +} + /// What a similarity says of its reference points that have no embedding in the area read. #[cfg(not(target_arch = "wasm32"))] fn missed_points(missed: usize, of: usize) -> Option { diff --git a/crates/engine/src/cmd/layer.rs b/crates/engine/src/cmd/layer.rs index 75c637d85c..a727f39034 100644 --- a/crates/engine/src/cmd/layer.rs +++ b/crates/engine/src/cmd/layer.rs @@ -4896,11 +4896,13 @@ impl WindowRaster { /// holds but isn't read, values past `f32`'s range), for a caller that makes another raster /// from it and so doesn't add this one (whose `lost` the layer would say). pub(crate) fn notes(&self) -> Vec { - std::iter::once(self.read.clone()) - .chain(self.finer.clone()) - .chain(self.edges.iter().cloned()) - .chain(self.raster.lost.iter().cloned()) - .collect() + self.read_notes().into_iter().chain(self.raster.lost.iter().cloned()).collect() + } + + /// What to say of the read alone (its size and level, a cell size finer than the file's, the + /// box's edges), without what the raster left out: the same for windows of one grid. + pub(crate) fn read_notes(&self) -> Vec { + std::iter::once(self.read.clone()).chain(self.finer.clone()).chain(self.edges.iter().cloned()).collect() } } diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index cf5a754640..a08ae6247a 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -37809,6 +37809,20 @@ fn a_window_read_for_another_raster_says_what_its_header_left_out() { let (clean, _) = serve_ranges(example(512, 256)); let w = read_window_raster(&WindowAsked::of(&format!("{clean}/clean.tif"), [10.0, 45.0, 10.5, 45.5], None, 1), &stop).unwrap(); assert_eq!(w.notes().len(), 1, "only the read: {:?}", w.notes()); + // A change says what each year's file left out, by its year, and once for both when both left + // it out; the read, the same for both, once. + use crate::cmd::embeddings::two_years_notes; + let lossy = read_window_raster(&WindowAsked::of(&format!("{lossy}/lossy.tif"), [10.0, 45.0, 10.5, 45.5], None, 1), &stop).unwrap(); + let said = two_years_notes(&w, &lossy, (2017, 2025)); + assert!(said.iter().any(|n| n.starts_with("the 2025 file: its colour table has 384 entries")), "{said:?}"); + assert!(!said.iter().any(|n| n.starts_with("the 2017")), "{said:?}"); + assert_eq!(said.iter().filter(|n| n.contains("window of the full image")).count(), 1, "{said:?}"); + let said = two_years_notes(&lossy, &w, (2017, 2025)); + assert!(said.iter().any(|n| n.starts_with("the 2017 file: its colour table has 384 entries")), "{said:?}"); + let said = two_years_notes(&lossy, &lossy, (2017, 2025)); + assert_eq!(said.iter().filter(|n| n.contains("its colour table has 384 entries")).count(), 1, "{said:?}"); + assert!(said.iter().any(|n| n.starts_with("the 2017 and 2025 files: its colour table")), "{said:?}"); + assert_eq!(two_years_notes(&w, &w, (2017, 2025)).len(), 1, "two clean files: only the read"); // A file without the bands asked for is refused from its header. let e = read_window_raster(&WindowAsked::of(&format!("{clean}/clean.tif"), [10.0, 45.0, 10.5, 45.5], None, 64), &stop).err().unwrap(); assert!(e.contains("it has 1 band(s), where 64 are needed"), "{e}");