diff --git a/crates/engine/src/cmd/embeddings.rs b/crates/engine/src/cmd/embeddings.rs index 5f89d5f042..f4953844a3 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,364 @@ 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; + +/// `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") +} + +/// 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)?; + 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])?; + 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(two_years_notes(&a, &b, (from, to))); + 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)); + 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 (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(|| { + 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()); + 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 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 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", + kept + dropped + )); + } + 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 { + (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, AEF_BANDS); + 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())?; + 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 +1113,161 @@ 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}"); + } + + #[test] + fn similarity_and_change_say_what_the_search_and_the_points_left_out() { + let tile = |place: &str, years: &[i32]| emb::Series { + tile: emb::Tile { + dataset: "alphaearth", + id: place.into(), + title: place.into(), + detail: String::new(), + url: String::new(), + year: None, + bbox: [0.0; 4], + footprint: Vec::new(), + }, + years: years.iter().map(|y| (*y, format!("https://x.org/{y}/23S/h{y}-{place}.tiff"))).collect(), + }; + // One tile, the index read whole: nothing to say. + let one = emb::SeriesFound { series: vec![tile("0-0", &[2017, 2025])], dropped: 0, duplicates: 0, complete: true }; + let (files, place, notes) = pick_tile(&one, &[2017, 2025]).unwrap(); + assert_eq!(files, ["https://x.org/2017/23S/h2017-0-0.tiff", "https://x.org/2025/23S/h2025-0-0.tiff"]); + assert_eq!((place.as_str(), notes.len()), ("23S 0-0", 0)); + // 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: 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(), 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_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!( + 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, 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 { 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!( + missed_points(1, 3).as_deref(), + Some("1 of the 3 reference points have no embedding in the area read (outside it, or no data there) and were left out") + ); + // What the work says is said once its raster is added, under the layer's name; a raster + // with nothing to say adds none. + let mut s = Session::new(Project::default()); + let r = quantised([[1.0; 3]; 4]); + let made = |name: &str, notes: Vec| { + 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(), 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 51572354b5..a727f39034 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,14 @@ 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; + +/// 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 { @@ -4485,6 +4493,20 @@ 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; 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) } + } } #[cfg(all(test, not(target_arch = "wasm32")))] @@ -4518,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 @@ -4563,11 +4585,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 +4604,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 +4693,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 +4720,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)) @@ -4718,29 +4748,48 @@ pub fn read_cog_window_until(asked: &WindowAsked, stop: &std::sync::atomic::Atom ))); } 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 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 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. 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)?; + 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), wait, 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 +4813,36 @@ 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 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); + 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 +4863,47 @@ 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" - )); + 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, 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 { + self.read_notes().into_iter().chain(self.raster.lost.iter().cloned()).collect() } - 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" - )); + + /// 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() } - 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 @@ -4843,6 +4937,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/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..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()) { @@ -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..a08ae6247a 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 @@ -37758,6 +37767,67 @@ 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); +} + +/// 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 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}"); +} + /// `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 +43372,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..b045f0af44 100644 --- a/crates/tiles/src/cog.rs +++ b/crates/tiles/src/cog.rs @@ -1512,9 +1512,29 @@ 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, 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. 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, + level: usize, + 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(); 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 +1546,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 +1564,42 @@ 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())); - let picked = - wait_until(&rx, Duration::from_secs(120), stop).map_err(|stopped| stopped_or(stopped, &url, "tiles not read in two minutes"))??; + fetch_bands(info.clone(), url.clone(), level, tiles.clone(), bands.to_vec(), Box::new(move |r| tx.send(r).unwrap_or_default())); + 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 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..256c2f655c 100644 --- a/docs/user-guide/web-data.md +++ b/docs/user-guide/web-data.md @@ -756,4 +756,29 @@ 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. 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.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.