diff --git a/crates/analysis/src/rasterops.rs b/crates/analysis/src/rasterops.rs index fffdcc7f8f..fdca36418b 100644 --- a/crates/analysis/src/rasterops.rs +++ b/crates/analysis/src/rasterops.rs @@ -434,51 +434,144 @@ pub fn line_of_sight( const MAX_VIEWSHED_WORK: usize = 400_000_000; pub(crate) const MAX_IDW_WORK: usize = 400_000_000; +/// How a viewshed reads the ground between the observer and a cell. +#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)] +pub enum Heights { + /// The cell each point of the ray falls in, as the viewshed has read it (each point now exact on + /// a cell's centre line, which can change a cell at a tie). On ground that bulges + /// (a hill seen from its top), a cell nearer the observer than the point stands in for it and + /// can hide cells just inside the horizon. + #[default] + Nearest, + /// Between the cells' centres, in proportion to how near the point is to each (bilinear): + /// smoother, and closer on bulging ground, though still an estimate. Where one of those cells + /// has no data, the cell the point falls in, as [`Heights::Nearest`] reads it (counted: + /// [`Viewshed::read_nearest`]). + Bilinear, +} + +impl Heights { + /// The one named `name` (`nearest`, `bilinear`, in any case); `None` for any other. + pub fn named(name: &str) -> Option { + if name.eq_ignore_ascii_case("nearest") { + Some(Heights::Nearest) + } else if name.eq_ignore_ascii_case("bilinear") { + Some(Heights::Bilinear) + } else { + None + } + } + + /// The ground at a point of a ray, `(col, row)` in cells (whole numbers at cell centres), and + /// whether it is the nearest cell's, read in place of cells between which a neighbour has + /// no data. `None` where the point's own cell has no data. + fn at(self, r: &Raster, b: usize, col: f64, row: f64) -> Option<(f64, bool)> { + let (nc, nr) = (col.round() as i64, row.round() as i64); + let nearest = |fell_back: bool| r.value(b, nc, nr).map(|v| (f64::from(v), fell_back)); + if self == Heights::Nearest { + return nearest(false); + } + let (c0, r0) = (col.floor(), row.floor()); + let (tx, ty) = (col - c0, row - r0); + let (c0, r0) = (c0 as i64, r0 as i64); + let mut sum = 0.0f64; + // A neighbour weighing nothing (the point on its row or column) isn't read, so a point + // on a cell's centre line needs only the two cells it lies between. + for (dc, dr, wgt) in [(0, 0, (1.0 - tx) * (1.0 - ty)), (1, 0, tx * (1.0 - ty)), (0, 1, (1.0 - tx) * ty), (1, 1, tx * ty)] { + if wgt == 0.0 { + continue; + } + match r.value(b, c0 + dc, r0 + dr) { + Some(v) => sum += wgt * f64::from(v), + None => return nearest(true), + } + } + Some((sum, false)) + } +} + +/// A viewshed: each cell visible (1) or not (0), no-data outside the radius, and how many cells' +/// rays read the ground less than fully. +#[derive(Clone, Debug, Default, PartialEq)] +pub struct Viewshed { + pub cells: Vec, + /// Cells seen across ground with no data, taken as hiding nothing there. + pub through_gaps: usize, + /// Cells whose ray, read [`Heights::Bilinear`], took the nearest cell's height somewhere, + /// a cell it would read between having no data. + pub read_nearest: usize, +} + /// Cells visible from an observer (1) or not (0) within `radius_m`; outside the radius no-data. -/// The Earth curves as visible light sees it (`SIGHT_RADIUS_M`). -pub fn viewshed(r: &Raster, b: usize, observer: Coord, height: f64, radius_m: f64) -> Result, String> { - viewshed_on(None, r, b, observer, height, radius_m) +/// The Earth curves as visible light sees it (`SIGHT_RADIUS_M`). The ground along each ray is read +/// as `heights` says; ground with no data hides nothing, and the cells whose rays crossed some are +/// counted. +pub fn viewshed(r: &Raster, b: usize, observer: Coord, height: f64, radius_m: f64, heights: Heights) -> Result { + viewshed_on(None, r, b, observer, height, radius_m, heights) } /// [`viewshed`] on `threads` threads, or as many as its work calls for. -fn viewshed_on(threads: Option, r: &Raster, b: usize, observer: Coord, height: f64, radius_m: f64) -> Result, String> { +fn viewshed_on( + threads: Option, + r: &Raster, + b: usize, + observer: Coord, + height: f64, + radius_m: f64, + heights: Heights, +) -> Result { let (oc, or) = r.pixel_at(observer).ok_or("the observer is outside the raster")?; let z0 = r.value(b, oc, or).ok_or("the observer stands on no-data")? as f64 + height; let (cx, cy) = r.cell_size_m(); if !(cx > 0.0 && cy > 0.0 && radius_m.is_finite() && radius_m > 0.0) { return Err("the raster's cells or the radius have no size".into()); } - // A tiny declared cell size would make the window overflow: bound it before converting. - if radius_m / cx > 100_000.0 || radius_m / cy > 100_000.0 { - return Err("the radius covers too many cells; use a smaller radius".into()); - } + // In cells (saturating: a radius of more cells than an i64 holds still reaches past the + // raster). Only the radius's cells within the raster are worked out, so a radius reaching + // past it (the whole DEM's diagonal, by default) costs no more than the raster, which is + // already in memory; the time is bounded by the ray steps below. let rad_c = (radius_m / cx).ceil() as i64; let rad_r = (radius_m / cy).ceil() as i64; + let (first, last) = (or.saturating_sub(rad_r).max(0), or.saturating_add(rad_r).min(r.height as i64 - 1)); + let (left, right) = (oc.saturating_sub(rad_c).max(0), oc.saturating_add(rad_c).min(r.width as i64 - 1)); // Each cell walks a ray back to the observer: bound cells × ray length, not just cells. - let cells = (2 * rad_c + 1).saturating_mul(2 * rad_r + 1); - let ray_work = usize::try_from(cells.saturating_mul(rad_c.max(rad_r) / 2 + 1)).unwrap_or(usize::MAX); - if cells > 25_000_000 { - return Err("the radius covers too many cells; use a smaller radius".into()); - } + let cells = (right - left + 1).saturating_mul(last - first + 1); + let longest = (oc - left).max(right - oc).max(or - first).max(last - or); + // A ray steps a whole cell along its longer axis, so a bilinear point lies on a cell's + // centre line and reads the two cells it falls between ([`Heights::at`] skips a neighbour + // that weighs nothing; next to no data, the nearest cell too) where a nearest one reads one: + // weighed as two. + let per_step = if heights == Heights::Bilinear { 2 } else { 1 }; + let ray_work = usize::try_from(cells.saturating_mul(longest / 2 + 1).saturating_mul(per_step)).unwrap_or(usize::MAX); // Each cell walks its own ray and writes only itself, so the rows within the radius are made // on several threads when the work is large (#1252), and may take as many times the work. - let (first, last) = ((or - rad_r).max(0), (or + rad_r).min(r.height as i64 - 1)); let rows = usize::try_from(last - first + 1).unwrap_or(0); let threads = threads.unwrap_or_else(|| crate::parallel::threads_for_rows(rows, ray_work, 0)); let cap = crate::parallel::work_cap(MAX_VIEWSHED_WORK, threads); if ray_work > cap { + // A radius reaching the raster's farthest corner covers all of it (as with no radius + // given, the raster's diagonal): said as the whole raster, not as a radius to shorten. + let corner = ((oc.max(r.width as i64 - 1 - oc)) as f64 * cx).hypot((or.max(r.height as i64 - 1 - or)) as f64 * cy); + let (what, fix) = if radius_m >= corner { + ("the whole raster", "give a radius to cover only part of it") + } else { + ("the radius", "use a smaller radius") + }; return Err(format!( - "the radius takes {ray_work} ray steps, more than the {cap} this computer takes on {threads} thread(s); use a smaller radius{}", + "{what} takes {ray_work} ray steps{}, more than the {cap} this computer takes on {threads} thread(s); {fix}{}", + if per_step > 1 { " (a step between cells counted as two)" } else { "" }, crate::parallel::UNCAPPED_HINT )); } let w = r.width as usize; let mut out = new_band(w, r.height as usize, NODATA)?; let window = out.chunks_mut(w).skip(usize::try_from(first).unwrap_or(0)).take(rows); + // Summed across threads: the same counts on any number. + let (through_gaps, read_nearest) = (std::sync::atomic::AtomicUsize::new(0), std::sync::atomic::AtomicUsize::new(0)); crate::control::begin(rows); crate::parallel::for_each_row(window, threads, crate::control::Pace::default, |pace, i, line: &mut [f32]| { let row = first + i as i64; - for col in (oc - rad_c).max(0)..=(oc + rad_c).min(r.width as i64 - 1) { + for col in left..=right { let (dx, dy) = ((col - oc) as f64 * cx, (row - or) as f64 * cy); let dist = dx.hypot(dy); if dist > radius_m { @@ -499,22 +592,39 @@ fn viewshed_on(threads: Option, r: &Raster, b: usize, observer: Coord, he return; } let mut visible = true; + let (mut gap, mut nearest) = (false, false); + // Along the longer axis the ray steps a whole cell at a time; along the other it falls + // between cells. Both are one division of whole numbers, so exact wherever the point + // lies on a cell's centre line (and no neighbour is weighed by a rounding error). + let (dc, dr) = (col - oc, row - or); + let along = |o: i64, d: i64, s: usize| o as f64 + (d * s as i64) as f64 / steps as f64; for s in 1..steps { let t = s as f64 / steps as f64; - let (c, rr) = ((oc as f64 + (col - oc) as f64 * t).round() as i64, (or as f64 + (row - or) as f64 * t).round() as i64); - let Some(zi) = r.value(b, c, rr) else { continue }; + let (c, rr) = (along(oc, dc, s), along(or, dr, s)); + let Some((zi, fell_back)) = heights.at(r, b, c, rr) else { + gap = true; + continue; + }; + nearest |= fell_back; let di = dist * t; - if (zi as f64 - di * di / (2.0 * SIGHT_RADIUS_M) - z0) / di > target { + if (zi - di * di / (2.0 * SIGHT_RADIUS_M) - z0) / di > target { visible = false; break; } } + // A hidden cell stays hidden whatever the missing ground is: only those seen count. + if gap && visible { + through_gaps.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + } + if nearest { + read_nearest.fetch_add(1, std::sync::atomic::Ordering::Relaxed); + } if let Some(o) = line.get_mut(col as usize) { *o = if visible { 1.0 } else { 0.0 }; } } })?; - Ok(out) + Ok(Viewshed { cells: out, through_gaps: through_gaps.into_inner(), read_nearest: read_nearest.into_inner() }) } /// Inverse distance weighted interpolation of point values onto a grid in `crs`, from each cell's @@ -1577,8 +1687,58 @@ mod tests { assert!(grid::(4, 5).is_ok_and(|g| g.is_empty() && g.capacity() >= 20)); } + /// A radius reaching far past the raster (the whole DEM's diagonal, as the command takes by + /// default) counts only the raster's cells: a strip 6,000 cells long, seen from one end, is + /// worked out, though the square the radius spans holds 144 million cells. So is a radius of + /// more cells than an `i64` holds. + #[test] + fn a_viewshed_radius_past_the_raster_counts_only_its_cells() { + let transform = GeoTransform { origin_x: 0.0, origin_y: 0.001, pixel_width: 0.001, pixel_height: -0.001 }; + let strip = Raster::new("strip", 6_000, 1, vec![vec![100.0; 6_000]], transform, Crs::LonLat, None, ColorHint::Gray, "Float32") + .unwrap_or_else(|e| panic!("{e}")); + let (cx, _) = strip.cell_size_m(); + let vs = viewshed(&strip, 0, Coord::new(0.0005, 0.0005), 2.0, cx * 6_000.0, Heights::Nearest).unwrap_or_else(|e| panic!("{e}")); + assert_eq!(vs.cells.len(), 6_000); + // Every cell worked out (none left no-data): seen up to the horizon, hidden past it. + assert!(vs.cells.iter().all(|v| *v == 1.0 || *v == 0.0), "every cell worked out"); + assert!(vs.cells.contains(&1.0) && vs.cells.contains(&0.0), "seen and hidden"); + // A radius of more cells than an i64 holds, on cells declared a millimetre wide. + let tiny = GeoTransform { pixel_width: 1e-8, pixel_height: -1e-8, ..transform }; + let strip = Raster::new("strip", 50, 1, vec![vec![100.0; 50]], tiny, Crs::LonLat, None, ColorHint::Gray, "Float32") + .unwrap_or_else(|e| panic!("{e}")); + let vs = viewshed(&strip, 0, Coord::new(5e-9, 0.001 - 5e-9), 2.0, 1e300, Heights::Nearest).unwrap_or_else(|e| panic!("{e}")); + assert!(vs.cells.iter().all(|v| *v == 1.0), "{:?}", vs.cells); + } + + /// A bilinear ray step is weighed as two in the work cap (it reads the two cells it falls + /// between), and a refusal says so: 1,000 × 1,000 cells from the middle on one thread take + /// 251 million nearest steps, under the cap, and 502 million weighed bilinear ones, over it. + /// A radius reaching every cell is refused as the whole raster; one short of the corners, + /// with the same window and steps, as a radius. + #[test] + fn a_bilinear_viewshed_step_is_weighed_as_two_in_the_work_cap() { + let w = 1_000u32; + let transform = GeoTransform { origin_x: 0.0, origin_y: 45.0, pixel_width: 0.0003, pixel_height: -0.0003 }; + let dem = Raster::new("dem", w, w, vec![vec![0.0; (w * w) as usize]], transform, Crs::LonLat, None, ColorHint::Gray, "Float32") + .unwrap_or_else(|e| panic!("{e}")); + let middle = Coord::new(500.5 * 0.0003, 45.0 - 500.5 * 0.0003); + let e = viewshed_on(Some(1), &dem, 0, middle, 2.0, 1e9, Heights::Bilinear).unwrap_err(); + assert!( + e.starts_with(&format!( + "the whole raster takes 502000000 ray steps (a step between cells counted as two), more than the {MAX_VIEWSHED_WORK} this computer takes on 1 thread(s); give a radius to cover only part of it" + )), + "{e}" + ); + // 600 of the longer cell side: past every edge (500 cells away), short of the corners + // (about 707 cells of the side's mean away; the cells are longer north–south at 45°). + let (cx, cy) = dem.cell_size_m(); + assert!(600.0 * cx.max(cy) < (500.0 * cx).hypot(500.0 * cy)); + let e = viewshed_on(Some(1), &dem, 0, middle, 2.0, 600.0 * cx.max(cy), Heights::Bilinear).unwrap_err(); + assert!(e.starts_with("the radius takes 502000000 ray steps") && e.contains("; use a smaller radius"), "{e}"); + } + /// Viewshed rows made on several threads see what one thread sees (#1252), with the radius - /// inside the raster and reaching past its edges. + /// inside the raster and reaching past its edges, with nearest and bilinear heights. #[test] fn viewshed_on_several_threads_is_viewshed_on_one() { let (w, h) = (90u32, 70u32); @@ -1596,12 +1756,24 @@ mod tests { for (at, radius, expected) in [(Coord::new(0.012, 44.990), 500.0, [207, 775, 5318]), (Coord::new(0.003, 44.985), 5_000.0, [185, 6050, 65])] { - let one = viewshed_on(Some(1), &dem, 0, at, 2.0, radius).unwrap_or_else(|e| panic!("{e}")); + let one_run = viewshed_on(Some(1), &dem, 0, at, 2.0, radius, Heights::Nearest).unwrap_or_else(|e| panic!("{e}")); + // Cells seen across the DEM's no-data cells are counted; nearest heights read no + // neighbours, so none falls back. + assert!(one_run.through_gaps > 0 && one_run.read_nearest == 0, "radius {radius}: {}", one_run.through_gaps); + let one = &one_run.cells; let counts = [1.0, 0.0, NODATA].map(|k| one.iter().filter(|v| v.to_bits() == k.to_bits()).count()); assert_eq!(counts, expected, "radius {radius}"); + // Bilinear heights read next to the no-data cells, so some cells take a nearest height. + let bilinear = viewshed_on(Some(1), &dem, 0, at, 2.0, radius, Heights::Bilinear).unwrap_or_else(|e| panic!("{e}")); + assert!(bilinear.through_gaps > 0 && bilinear.read_nearest > 0, "radius {radius}: {}", bilinear.read_nearest); for threads in [2, 7, 16] { - let many = viewshed_on(Some(threads), &dem, 0, at, 2.0, radius).unwrap_or_else(|e| panic!("{e}")); - assert!(one.iter().map(|v| v.to_bits()).eq(many.iter().map(|v| v.to_bits())), "{threads} threads, radius {radius}"); + for (heights, one_run) in [(Heights::Nearest, &one_run), (Heights::Bilinear, &bilinear)] { + let many = viewshed_on(Some(threads), &dem, 0, at, 2.0, radius, heights).unwrap_or_else(|e| panic!("{e}")); + let what = format!("{heights:?}, {threads} threads, radius {radius}"); + assert_eq!((many.through_gaps, many.read_nearest), (one_run.through_gaps, one_run.read_nearest), "{what}"); + let bits = |c: &[f32]| c.iter().map(|v| v.to_bits()).collect::>(); + assert_eq!(bits(&one_run.cells), bits(&many.cells), "{what}"); + } } } } @@ -1789,7 +1961,7 @@ mod tests { let eye = Coord::new(0.0005, 0.0); // √(2 · 7/6 · 6,371 km · 10 m), written out so that the test pins the radius. let horizon = 12_192.0; - let vs = viewshed(&flat, 0, eye, 10.0, 20_000.0).unwrap_or_else(|e| panic!("{e}")); + let vs = viewshed(&flat, 0, eye, 10.0, 20_000.0, Heights::Nearest).unwrap_or_else(|e| panic!("{e}")).cells; let row = &vs[w as usize..2 * w as usize]; let last = row.iter().rposition(|v| *v == 1.0).unwrap_or(0); let (cx, _) = flat.cell_size_m(); @@ -1801,6 +1973,127 @@ mod tests { assert_eq!(seen(0.1155), Some(false)); } + /// Viewsheds on DEMs whose answer is known from their geometry: flat ground (the horizon at + /// √(2·R′·h)), a bowl (every cell seen), a dome (seen up to where the line from the eye + /// touches it, at √(h / k′)), and a wall lower than the eye (the cells in its shadow hidden, + /// those beyond it seen again). The Earth's + /// curvature for visible light (`SIGHT_RADIUS_M`) is part of each answer. Cells within a cell + /// and a half of a boundary, where a grid can't say which side a cell is on, aren't counted. + /// Bilinear heights get every cell counted right on all four; nearest heights hide some of the + /// dome just inside its horizon, and are right on the other three. + #[test] + fn viewsheds_give_the_known_answers_of_flat_ground_a_bowl_a_dome_and_a_wall() { + // 201 × 201 cells of 0.00027° (about 30 m) on the equator, the observer at the centre. + let (n, half, step) = (201u32, 100i64, 0.00027); + let transform = GeoTransform { origin_x: 0.0, origin_y: step * f64::from(n) / 2.0, pixel_width: step, pixel_height: -step }; + let blank = Raster::new("dem", n, n, vec![vec![0.0; (n * n) as usize]], transform, Crs::LonLat, None, ColorHint::Gray, "Float32") + .unwrap_or_else(|e| panic!("{e}")); + let (cx, cy) = blank.cell_size_m(); + let at = |col: i64, row: i64| ((col - half) as f64 * cx, (row - half) as f64 * cy); + let dem = |z: &dyn Fn(f64, f64) -> f64| { + let mut r = blank.clone(); + if let Some(b) = r.bands.get_mut(0) { + for (i, v) in b.data.iter_mut().enumerate() { + let (x, y) = at(i as i64 % i64::from(n), i as i64 / i64::from(n)); + *v = z(x, y) as f32; + } + } + r + }; + let eye = Coord::new(step * (half as f64 + 0.5), step * (f64::from(n) / 2.0 - half as f64 - 0.5)); + let radius = 3_000.0; + let band = 1.5 * cx.max(cy); + let drop = |d: f64| d * d / (2.0 * SIGHT_RADIUS_M); + // Cells seen wrongly, and those counted, for `expected` (None: on a boundary, or outside). + let wrong = |r: &Raster, h: f64, heights: Heights, expected: &dyn Fn(i64, i64, f64) -> Option| { + let vs = viewshed(r, 0, eye, h, radius, heights).unwrap_or_else(|e| panic!("{e}")).cells; + let (mut bad, mut counted) = (0usize, 0usize); + for row in 0..i64::from(n) { + for col in 0..i64::from(n) { + let (x, y) = at(col, row); + let d = x.hypot(y); + let Some(want) = (d > 0.0 && d <= radius).then(|| expected(col, row, d)).flatten() else { continue }; + let got = vs.get((row * i64::from(n) + col) as usize).copied(); + counted += 1; + bad += usize::from(got != Some(if want { 1.0 } else { 0.0 })); + } + } + (bad, counted) + }; + let before = |d: f64, edge: f64| if (d - edge).abs() <= band { None } else { Some(d < edge) }; + + // Flat ground, an eye 0.5 m up: the horizon at √(2·R′·h), about 2.7 km. + let flat = dem(&|_, _| 0.0); + let horizon = (2.0 * SIGHT_RADIUS_M * 0.5).sqrt(); + for heights in [Heights::Nearest, Heights::Bilinear] { + let (bad, counted) = wrong(&flat, 0.5, heights, &|_, _, d| before(d, horizon)); + assert!(bad == 0 && counted > 20_000, "flat, {heights:?}: {bad} of {counted} wrong"); + } + + // A bowl rising 4 m a kilometre squared (z = k·d², far steeper than the Earth curves + // away): every cell is seen. + let bowl = dem(&|x, y| 4e-6 * (x * x + y * y)); + for heights in [Heights::Nearest, Heights::Bilinear] { + let (bad, counted) = wrong(&bowl, 2.0, heights, &|_, _, _| Some(true)); + assert!(bad == 0 && counted > 20_000, "bowl, {heights:?}: {bad} of {counted} wrong"); + } + + // A dome falling 10 m a kilometre squared from its top, the eye 10 m up there: with the + // Earth's curve, the ground falls k′ = k + 1/(2R′) a metre squared, and the line from the + // eye touches it at √(h / k′), about 1 km; beyond, the dome hides the ground. + let k = 1e-5; + let dome = dem(&|x, y| 500.0 - k * (x * x + y * y)); + let edge = (10.0 / (k + 1.0 / (2.0 * SIGHT_RADIUS_M))).sqrt(); + let (bad, counted) = wrong(&dome, 10.0, Heights::Bilinear, &|_, _, d| before(d, edge)); + assert!(bad == 0 && counted > 20_000, "dome, bilinear: {bad} of {counted} wrong"); + let (bad_nearest, _) = wrong(&dome, 10.0, Heights::Nearest, &|_, _, d| before(d, edge)); + assert!(bad_nearest > 0, "nearest heights hide some of the dome just inside its horizon"); + + // A wall 1 m high, a column of cells 20 cells (about 600 m) east of an eye 2 m up: beyond it, + // a cell is hidden while the line from the eye over the wall's top passes above it, and + // seen again once the line has come down below the ground (at about 1.2 km on a flat + // Earth, a little farther with its curve). Rays mostly east or west, + // which cross the wall at a cell's centre line, are counted; others cross it between + // columns, where it stands depends on how the ground is read. + let wall_col = half + 20; + let wall = dem(&|x, _| if (x - 20.0 * cx).abs() < cx / 2.0 { 1.0 } else { 0.0 }); + let z0 = 2.0; + // How far the line over the wall's top passes above the cell (negative: below it). + let over = |col: i64, d: f64| { + let dw = d * (20.0 / (col - half) as f64); + (1.0 - drop(dw) - z0) / dw * d - (-drop(d) - z0) + }; + let shadow = |col: i64, row: i64, d: f64| -> Option { + let (dc, dr) = (col - half, row - half); + if col == wall_col || dr.abs() > dc.abs() { + return None; + } + if col < wall_col { + return Some(true); + } + let over = over(col, d); + if over.abs() < 0.05 { None } else { Some(over < 0.0) } + }; + // Both sides of the shadow's edge are counted, not only the shadow. + let (mut hidden, mut seen_past) = (0usize, 0usize); + for row in 0..i64::from(n) { + for col in wall_col + 1..i64::from(n) { + let (x, y) = at(col, row); + let d = x.hypot(y); + match (d <= radius).then(|| shadow(col, row, d)).flatten() { + Some(false) => hidden += 1, + Some(true) => seen_past += 1, + None => {} + } + } + } + assert!(hidden > 1_000 && seen_past > 1_000, "{hidden} hidden, {seen_past} seen past the wall"); + for heights in [Heights::Nearest, Heights::Bilinear] { + let (bad, counted) = wrong(&wall, z0, heights, &shadow); + assert!(bad == 0 && counted > 10_000, "wall, {heights:?}: {bad} of {counted} wrong"); + } + } + /// A run past one thread's work, on one thread, is refused, naming the cap and the threads. #[test] fn idw_past_one_threads_work_is_refused_on_one_naming_the_cap() { @@ -2152,7 +2445,7 @@ mod tests { *v = if i % 20 == 10 { 500.0 } else { 0.0 }; } } - let vs = viewshed(&wall, 0, Coord::new(0.0025, 0.0105), 2.0, 5_000.0).unwrap_or_default(); + let vs = viewshed(&wall, 0, Coord::new(0.0025, 0.0105), 2.0, 5_000.0, Heights::Nearest).unwrap_or_default().cells; assert_eq!(vs[10 * 20 + 5], 1.0); assert_eq!(vs[10 * 20 + 15], 0.0); let (seen, prof) = diff --git a/crates/engine/src/cmd/workflows.rs b/crates/engine/src/cmd/workflows.rs index 06c151652f..7262852579 100644 --- a/crates/engine/src/cmd/workflows.rs +++ b/crates/engine/src/cmd/workflows.rs @@ -60,7 +60,7 @@ pub fn commands() -> Vec { r#"{"criteria": [{"layer": raster, "band"?: 1-based, "ranges": [[lo, hi, score]], "weight": number}], "name"?: output, "ran"?: (internal: a raster the app has worked out)}"#, ), C::new("analysis.viewshed", "Visibility Analysis", "Analyze › Workflows", viewshed).roles(&[]).effects(crate::policy::Effects::NONE) - .params(r#"{"layer": elevation raster, "lon", "lat", "band"?: 1-based, "height"?: observer metres, "radius"?: metres, "name"?: output, "ran"?: (internal: a viewshed the app has worked out)}"#), + .params(r#"{"layer": elevation raster, "lon", "lat", "band"?: 1-based, "height"?: observer metres, 0 to 10,000 (default 1.7), "radius"?: metres (default: the whole raster), "heights"?: "nearest" (default) | "bilinear" (the ground along each ray), "name"?: output, "ran"?: (internal: a viewshed the app has worked out)}"#), C::new("analysis.lineOfSight", "Line Of Sight", "Analyze › Workflows", line_of_sight).roles(&[]).effects(crate::policy::Effects::NONE).params( r#"{"layer": elevation raster, "from": [lon, lat], "to": [lon, lat], "band"?: 1-based, "observerHeight"?: m, "targetHeight"?: m, "name"?: output}"#, ), @@ -1118,14 +1118,99 @@ fn viewshed_work(s: &Session, p: &Value) -> Result { let at = Coord::new(f(p, "lon").ok_or("lon is required")?, f(p, "lat").ok_or("lat is required")?); let band = band_of(p, &dem)?; let (cx, cy) = dem.cell_size_m(); - // The whole raster by default: its diagonal reaches every cell from any observer. - let radius = f(p, "radius").unwrap_or((cx * dem.width as f64).hypot(cy * dem.height as f64)).clamp(1.0, 500_000.0); - let height = f(p, "height").unwrap_or(1.7).clamp(0.0, 10_000.0); + // The whole raster by default, however large: its diagonal reaches every cell from any + // observer, and only the raster's cells are worked out. A radius given past the diagonal + // covers the same cells, so it is taken as the diagonal: nothing is left out. + let diagonal = (cx * dem.width as f64).hypot(cy * dem.height as f64).max(1.0); + let radius = match p.get("radius") { + None | Some(Value::Null) => diagonal, + Some(v) => { + f(p, "radius").filter(|r| *r > 0.0).ok_or_else(|| format!("radius must be a number of metres above 0, not {v}"))?.min(diagonal) + } + }; + // A raster around the whole Earth (in longitude/latitude) has its east and west edges side + // by side, but rays don't cross from one to the other: said when the radius reaches an edge. + // (Within half a cell of 360°: a cell size stored rounded falls a little short.) + let pw = dem.transform.pixel_width.abs(); + let round_the_earth = dem.crs.is_geographic() && pw * f64::from(dem.width) >= 360.0 - pw / 2.0; + let (oc, or) = dem.pixel_at(at).unwrap_or((0, 0)); + let (w, h) = (i64::from(dem.width), i64::from(dem.height)); + let (near, far) = (oc.min(w - 1 - oc), oc.max(w - 1 - oc)); + // Only when the way across the edge is shorter than the way through the raster: the cell + // just across the near edge is `near + 1` cells away across it and `far` through the raster, + // and with no shorter way (the observer within a cell of the middle column) every cell is + // worked out as near as it is. + let seam = round_the_earth && near + 1 < far && (near as f64 + 1.0) * cx <= radius; + // The ground just across the edge is the far edge's column, reached only through the raster: + // worked out the long way round in the rows where the radius reaches it (cell centres, as the + // viewshed measures them). The rows with ground across the edge within the radius are those + // where it reaches a cell one past the near edge. All of them are worked out when the radius + // reaches the far column in the farthest of those rows, none when it doesn't reach the far + // column even on the observer's row. + let reaches = |dc: i64, dr: i64| (dc as f64 * cx).hypot(dr as f64 * cy) <= radius; + // The rows are walked only on a raster round the Earth, at most its height. + let last_row = if seam { (0..=or.max(h - 1 - or)).take_while(|dr| reaches(near + 1, *dr)).last().unwrap_or(0) } else { 0 }; + let across = if !reaches(far, 0) { + "left out of the viewshed" + } else if reaches(far, last_row) { + "worked out the long way round" + } else { + "worked out the long way round near the observer's row and left out farther from it" + }; + // Refused, naming it, when it isn't a height a viewshed takes: never another one used. + let height = match p.get("height") { + None | Some(Value::Null) => 1.7, + Some(v) => f(p, "height") + .filter(|h| (0.0..=10_000.0).contains(h)) + .ok_or_else(|| format!("height must be a number of metres from 0 to 10,000, not {v}"))?, + }; + // How the ground along each ray is read: the cell a point falls in, or between cells. + let heights = match p.get("heights") { + None | Some(Value::Null) => rasterops::Heights::Nearest, + Some(Value::String(h)) => { + rasterops::Heights::named(h).ok_or_else(|| format!("heights must be \"nearest\" or \"bilinear\", not \"{h}\""))? + } + Some(other) => return Err(format!("heights must be \"nearest\" or \"bilinear\", not {other}")), + }; let name = out_name(p, format!("{}_viewshed", dem.name)); + let dem_name = dem.name.clone(); Ok(Box::new(move || { - let vs = rasterops::viewshed(&dem, band, at, height, radius)?; - let seen = vs.iter().filter(|v| **v == 1.0).count(); - made(rasterops::derive(&dem, &name, vec![vs])?, Some(json!({"visibleCells": seen}))) + let vs = rasterops::viewshed(&dem, band, at, height, radius, heights)?; + let seen = vs.cells.iter().filter(|v| **v == 1.0).count(); + let (through_gaps, read_nearest) = (vs.through_gaps, vs.read_nearest); + let answer = json!({"visibleCells": seen, "acrossNoData": through_gaps, "readNearest": read_nearest}); + let m = made(rasterops::derive(&dem, &name, vec![vs.cells])?, Some(answer))?; + if through_gaps == 0 && read_nearest == 0 && !seam { + return Ok(m); + } + // Ground with no data hides nothing, and bilinear heights read the nearest cell beside + // it: said, with how many cells it touched. Rays that don't cross the raster's east–west + // edge, said too. + let then: Then = Box::new(move |s: &mut Session, _: &mut Value| { + if seam { + s.notify( + format!( + "{dem_name}: the raster goes round the Earth, but the viewshed's rays don't cross its east–west edge: ground just across it is {across}" + ), + false, + ); + } + if through_gaps > 0 { + s.notify( + format!( + "{dem_name}: {through_gaps} cell(s) of the viewshed were seen across ground with no data, taken as hiding nothing" + ), + false, + ); + } + if read_nearest > 0 { + s.notify( + format!("{dem_name}: {read_nearest} cell(s) were worked out with the nearest cell's height next to ground with no data, not between cells"), + false, + ); + } + }); + Ok(Made { then: Some(then), ..m }) })) } diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index 5a6e4ef1af..5432968b21 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -9891,6 +9891,171 @@ fn dem_b64() -> String { base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()) } +/// A viewshed whose rays cross ground with no data says how many cells it saw across it, taken as +/// hiding nothing, and, with bilinear heights, how many it saw with the nearest cell's height +/// beside it; one with data everywhere says neither (see +/// `analysis_workflows_models_scripts_and_raster_functions`). +#[test] +fn a_viewshed_says_what_ground_with_no_data_it_saw_across() { + use base64::Engine; + use rustgis_data::raster::{ColorHint, Crs, GeoTransform, Raster, geotiff}; + let mut s = world(); + // Flat ground with a column of no-data cells five cells east of the observer, and the same + // with a high wall ten cells farther, hiding what lies beyond it. + let gt = GeoTransform { origin_x: 10.0, origin_y: 45.04, pixel_width: 0.001, pixel_height: -0.001 }; + let mut dems = vec![]; + for (name, wall) in [("holes", 200.0), ("walled", 400.0)] { + let z: Vec = (0..1600) + .map(|i| match i % 40 { + 15 => -9999.0, + 25 => wall, + _ => 200.0, + }) + .collect(); + let r = Raster::new(name, 40, 40, vec![z], gt, Crs::LonLat, Some(-9999.0), ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": format!("{name}.tif"), "data": data})).unwrap(); + dems.push(s.map().layers.iter().rev().find(|l| l.is_raster() && l.name.starts_with(name)).unwrap().name.clone()); + } + let run = |s: &mut Session, dem: &str, heights: &str| { + s.run("analysis.viewshed", &json!({"layer": dem, "lon": 10.0105, "lat": 45.0205, "height": 2, "heights": heights})).unwrap() + }; + for heights in ["nearest", "bilinear"] { + // Only cells seen are counted: those the wall hides would stay hidden whatever the + // missing ground is. + let walled = run(&mut s, &dems[1], heights); + let walled_across = walled["acrossNoData"].as_u64().unwrap(); + let mark = s.notices.len(); + let v = run(&mut s, &dems[0], heights); + let across = v["acrossNoData"].as_u64().unwrap(); + assert!(across > 100 && across <= v["visibleCells"].as_u64().unwrap(), "{heights}: {v}"); + assert!(walled_across > 0 && walled_across + 100 < across, "{heights}: {walled_across} of {across}"); + let said: Vec<&str> = s.notices[mark..].iter().map(|n| n.text.as_str()).collect(); + assert!( + said.iter().any(|t| t.contains(&format!("{across} cell(s) of the viewshed were seen across ground with no data"))), + "{heights}: {said:?}" + ); + let nearest = v["readNearest"].as_u64().unwrap(); + if heights == "nearest" { + assert_eq!(nearest, 0); + } else { + assert!(nearest > 100, "{v}"); + assert!( + said.iter().any(|t| t.contains(&format!("{nearest} cell(s) were worked out with the nearest cell's height"))), + "{said:?}" + ); + } + } +} + +/// A viewshed's radius: one past the raster's diagonal works out the same cells as none; text or +/// 0 is refused, naming it; on a raster round the Earth whose edge the radius reaches, the rays +/// not crossing its east–west edge are said: the ground across left out when the radius doesn't +/// reach the far edge's column, worked out the long way round when it does in every row it +/// reaches the near one, and partly when only near the observer's row; nothing said when the way +/// across the edge is no shorter than through the raster. +#[test] +fn a_viewshed_says_what_it_did_with_its_radius_and_the_seam() { + use base64::Engine; + use rustgis_data::raster::{ColorHint, Crs, GeoTransform, Raster, geotiff}; + let mut s = world(); + // Flat ground round the Earth, 2° a cell. + let gt = GeoTransform { origin_x: -180.0, origin_y: 90.0, pixel_width: 2.0, pixel_height: -2.0 }; + let r = Raster::new("globe", 180, 90, vec![vec![0.0; 180 * 90]], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": "globe.tif", "data": data})).unwrap(); + let dem = s.map().layers.iter().find(|l| l.is_raster()).unwrap().name.clone(); + let said = |s: &mut Session, p: Value| { + let mark = s.notices.len(); + s.run("analysis.viewshed", &p).unwrap_or_else(|e| panic!("{p}: {e}")); + s.notices[mark..].iter().map(|n| n.text.clone()).collect::>() + }; + let seam = "rays don't cross its east–west edge"; + // By the edge with no radius (the whole raster): the seam is said. + let notes = said(&mut s, json!({"layer": dem, "lon": -179.0, "lat": 0.0})); + assert!(notes.iter().any(|n| n.contains(seam) && n.ends_with("worked out the long way round")), "{notes:?}"); + // By the edge with a radius past the edge line but short of the cell across it (2° is about + // 222 km there): nothing across it is within the radius, so nothing said. + let notes = said(&mut s, json!({"layer": dem, "lon": -179.0, "lat": 0.0, "radius": 150_000})); + assert!(notes.is_empty(), "{notes:?}"); + // Mid-way with a radius not reaching an edge: nothing said. + let notes = said(&mut s, json!({"layer": dem, "lon": 0.0, "lat": 0.0, "radius": 50_000})); + assert!(notes.is_empty(), "{notes:?}"); + // Given a radius reaching the near edge but not the far one, the ground across is left out. + let notes = said(&mut s, json!({"layer": dem, "lon": -177.0, "lat": 0.0, "radius": 600_000})); + assert_eq!(notes.len(), 1, "{notes:?}"); + assert!(notes[0].contains(seam) && notes[0].ends_with("left out of the viewshed"), "{notes:?}"); + // A radius past the raster's diagonal works out the same cells as none, with nothing to say + // about the radius. + let visible = |s: &mut Session, p: Value| s.run("analysis.viewshed", &p).unwrap_or_else(|e| panic!("{p}: {e}"))["visibleCells"].clone(); + let (none, huge) = (json!({"layer": dem, "lon": 0.0, "lat": 0.0}), json!({"layer": dem, "lon": 0.0, "lat": 0.0, "radius": 1e12})); + assert_eq!(visible(&mut s, none.clone()), visible(&mut s, huge.clone())); + assert_eq!(said(&mut s, none), said(&mut s, huge)); + // A geographic coordinate system other than WGS 84, and a cell size stored rounded + // (180 × 1.99999° = 359.9998°): still round the Earth. + let gt = GeoTransform { origin_x: -180.0, origin_y: 90.0, pixel_width: 1.99999, pixel_height: -2.0 }; + let r = Raster::new("nad83", 180, 90, vec![vec![0.0; 180 * 90]], gt, Crs::Epsg(4269), None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": "nad83.tif", "data": data})).unwrap(); + let nad83 = s.map().layers.iter().find(|l| l.name.starts_with("nad83")).unwrap().name.clone(); + let notes = said(&mut s, json!({"layer": nad83, "lon": -179.0, "lat": 0.0})); + assert!(notes.iter().any(|n| n.contains(seam)), "{notes:?}"); + // Stored from 0° to 360°, with its edge at 0°: the same. + let gt = GeoTransform { origin_x: 0.0, origin_y: 90.0, pixel_width: 2.0, pixel_height: -2.0 }; + let r = Raster::new("east", 180, 90, vec![vec![0.0; 180 * 90]], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": "east.tif", "data": data})).unwrap(); + let east = s.map().layers.iter().find(|l| l.name.starts_with("east")).unwrap().name.clone(); + let notes = said(&mut s, json!({"layer": east, "lon": 1.0, "lat": 0.0, "radius": 300_000})); + assert!(notes.iter().any(|n| n.contains(seam) && n.ends_with("left out of the viewshed")), "{notes:?}"); + // Near the pole, with cells of 90° (100 km each, as `cell_size_m` measures them there): a + // 350 km radius reaches the far column, so the ground across the edge is worked out through + // the raster. + let gt = GeoTransform { origin_x: -180.0, origin_y: 90.0, pixel_width: 90.0, pixel_height: -1.0 }; + let r = Raster::new("cap", 4, 1, vec![vec![0.0; 4]], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": "cap.tif", "data": data})).unwrap(); + let cap = s.map().layers.iter().find(|l| l.name.starts_with("cap")).unwrap().name.clone(); + let notes = said(&mut s, json!({"layer": cap, "lon": -170.0, "lat": 89.5, "radius": 350_000})); + assert!(notes.iter().any(|n| n.contains(seam) && n.ends_with("worked out the long way round")), "{notes:?}"); + // A radius between 2 and 3 cells: its window takes in the far column, + // but the far column's centre lies outside the radius, so the ground across is left out. + let (cx, _) = s.map().layer_by_name(&cap).and_then(|l| l.raster.as_ref()?.data.as_ref().map(|r| r.cell_size_m())).unwrap(); + let notes = said(&mut s, json!({"layer": cap, "lon": -170.0, "lat": 89.5, "radius": 2.5 * cx})); + assert!(notes.iter().any(|n| n.contains(seam) && n.ends_with("left out of the viewshed")), "{notes:?}"); + // Three rows of 0.1° there: a radius of three cells reaches the far column on the observer's + // row only, so the ground across is worked out there and left out in the rows beside it; + // three cells and three rows reach it in every row. + let gt = GeoTransform { origin_x: -180.0, origin_y: 90.0, pixel_width: 90.0, pixel_height: -0.1 }; + let r = Raster::new("rows", 4, 3, vec![vec![0.0; 12]], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": "rows.tif", "data": data})).unwrap(); + let rows = s.map().layers.iter().find(|l| l.name.starts_with("rows")).unwrap().name.clone(); + let (cx, cy) = s.map().layer_by_name(&rows).and_then(|l| l.raster.as_ref()?.data.as_ref().map(|r| r.cell_size_m())).unwrap(); + let notes = said(&mut s, json!({"layer": rows, "lon": -170.0, "lat": 89.95, "radius": 3.0 * cx + 1.0})); + assert!(notes.iter().any(|n| n.contains(seam) && n.ends_with("near the observer's row and left out farther from it")), "{notes:?}"); + let notes = said(&mut s, json!({"layer": rows, "lon": -170.0, "lat": 89.95, "radius": (3.0 * cx).hypot(2.0 * cy) + 1.0})); + assert!(notes.iter().any(|n| n.contains(seam) && n.ends_with("worked out the long way round")), "{notes:?}"); + // From the second column, the far column is the one across the edge, two cells away either + // way: nothing is shorter across the edge, so nothing is said. + let notes = said(&mut s, json!({"layer": rows, "lon": -45.0, "lat": 89.95, "radius": 2.0 * cx + 1.0})); + assert!(notes.is_empty(), "{notes:?}"); + // Nor from the middle of an odd number of columns (2 of 5), each edge two cells away. + let gt = GeoTransform { origin_x: -180.0, origin_y: 90.0, pixel_width: 72.0, pixel_height: -0.1 }; + let r = Raster::new("odd", 5, 3, vec![vec![0.0; 15]], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&r, 0).unwrap()); + s.run("layer.addDataBytes", &json!({"fileName": "odd.tif", "data": data})).unwrap(); + let odd = s.map().layers.iter().find(|l| l.name.starts_with("odd")).unwrap().name.clone(); + for p in [json!({"layer": odd, "lon": 0.0, "lat": 89.95}), json!({"layer": odd, "lon": 0.0, "lat": 89.95, "radius": 2.5 * cx})] { + let notes = said(&mut s, p); + assert!(notes.is_empty(), "{notes:?}"); + } + for bad in [json!("500km"), json!(0), json!(-5), json!(true)] { + let e = s.run("analysis.viewshed", &json!({"layer": dem, "lon": 0.0, "lat": 0.0, "radius": bad})).unwrap_err(); + assert_eq!(e, format!("radius must be a number of metres above 0, not {bad}")); + } +} + #[test] fn analysis_workflows_models_scripts_and_raster_functions() { let mut s = world(); @@ -9943,6 +10108,23 @@ fn analysis_workflows_models_scripts_and_raster_functions() { // On the flat northern edge: everything west of the wall is in view. let v = s.run("analysis.viewshed", &json!({"layer": dem, "lon": 10.0055, "lat": 45.0395, "height": 2})).unwrap(); assert!(v["visibleCells"].as_u64().unwrap() > 100, "{v}"); + // Bilinear heights read the ground between cells: on this hill and wall they see at least + // what the nearest cells do (a cell nearer the top no longer stands in for the ground), and + // little more. Any other name, or a value that isn't one, is refused, saying which there are. + let mark = s.notices.len(); + let b = s.run("analysis.viewshed", &json!({"layer": dem, "lon": 10.0055, "lat": 45.0395, "height": 2, "heights": "Bilinear"})).unwrap(); + let (near, bil) = (v["visibleCells"].as_u64().unwrap(), b["visibleCells"].as_u64().unwrap()); + assert!(bil >= near && bil <= near + near / 10, "nearest {near}, bilinear {bil}"); + // A DEM with every cell holding data: nothing to say about ground with none, and the answer + // says none. + assert!(s.notices[mark..].is_empty(), "{:?}", s.notices[mark..].iter().map(|n| &n.text).collect::>()); + for a in [&v, &b] { + assert_eq!((&a["acrossNoData"], &a["readNearest"]), (&json!(0), &json!(0)), "{a}"); + } + for bad in [json!("cubic"), json!(1)] { + let e = s.run("analysis.viewshed", &json!({"layer": dem, "lon": 10.0055, "lat": 45.0395, "heights": bad})).unwrap_err(); + assert!(e.to_string().contains(r#"heights must be "nearest" or "bilinear", not "#), "{e}"); + } let los = s.run("analysis.lineOfSight", &json!({"layer": dem, "from": [10.0205, 45.0395], "to": [10.0355, 45.0395]})).unwrap(); assert_eq!(los["visible"], false); let los = s.run("analysis.lineOfSight", &json!({"layer": dem, "from": [10.0205, 45.0395], "to": [10.0055, 45.0395]})).unwrap(); diff --git a/crates/ui-egui/src/analysispane.rs b/crates/ui-egui/src/analysispane.rs index cbb1ed5fa0..2f56d306aa 100644 --- a/crates/ui-egui/src/analysispane.rs +++ b/crates/ui-egui/src/analysispane.rs @@ -24,6 +24,8 @@ pub struct Workflow { pub field: String, pub number: String, pub number2: String, + /// The viewshed reads the ground between cells (bilinear heights), not the nearest cell. + pub bilinear: bool, pub text: String, pub function: String, pub chain: Vec, @@ -412,6 +414,25 @@ fn num(s: &str, d: f64) -> f64 { s.trim().parse().unwrap_or(d) } +/// The viewshed's parameters from the pane, seen from `at`: an empty radius field leaves the +/// radius out, so the command takes the whole DEM. +fn viewshed_params(w: &Workflow, at: rustgis_engine::geom::Coord) -> Value { + let mut params = json!({"layer": w.layer, "lon": at.x, "lat": at.y}); + // A number is the height or radius; other text goes as it is, for the command to refuse, + // naming it (`inf`, `NaN` and `1e400` parse, but aren't numbers JSON holds: they'd be null). + // Empty: the command's own (1.7 m up; the whole raster). + for (key, text) in [("height", &w.number), ("radius", &w.number2)] { + match text.trim() { + "" => {} + t => params[key] = t.parse::().ok().filter(|v| v.is_finite()).map_or_else(|| json!(t), |v| json!(v)), + } + } + if w.bilinear { + params["heights"] = json!("bilinear"); + } + params +} + /// The sections of the Workflows pane: (id, title). pub const SECTIONS: &[(&str, &str)] = &[ ("rasterFunctions", "Raster Functions"), @@ -702,12 +723,25 @@ pub fn workflows(app: &mut RustGisApp, ui: &mut Ui, t: &Tokens) { ui.add(egui::TextEdit::singleline(&mut app.workflow.number).hint_text(tl!("observer height m")).desired_width(110.0)); ui.add(egui::TextEdit::singleline(&mut app.workflow.number2).hint_text(tl!("radius m")).desired_width(80.0)); }); + // How the ground along each ray is read. + ui.horizontal(|ui| { + ui.label(tl!("Ground heights")); + let (nearest, between) = (tl!("Nearest cell"), tl!("Between cells (bilinear)")); + egui::ComboBox::from_id_salt("wf_v_heights") + .selected_text(if app.workflow.bilinear { between } else { nearest }) + .width(170.0) + .show_ui(ui, |ui| { + ui.selectable_value(&mut app.workflow.bilinear, false, nearest); + ui.selectable_value(&mut app.workflow.bilinear, true, between); + }) + .response + .on_hover_text(tl!( + "How the ground between the observer and a cell is read: the cell each point falls in, or between the cells' centres. Between cells is an estimate too, but closer on ground that bulges, a hill seen from its top, where the nearest cell can hide cells just inside the horizon." + )); + }); pick_button(app, ui, "viewshed", 1, "Click the observer on the map"); if let Some(p) = picked(app, "viewshed").and_then(|v| v.first().copied()) { - let mut params = json!({"layer": app.workflow.layer, "lon": p.x, "lat": p.y, "height": num(&app.workflow.number, 1.7)}); - if let Ok(r) = app.workflow.number2.trim().parse::() { - params["radius"] = json!(r); - } + let params = viewshed_params(&app.workflow, p); run(app, "analysis.viewshed", params); } } @@ -2131,6 +2165,71 @@ mod tests { use super::*; use egui_kittest::kittest::Queryable; + /// An empty radius field (or one of spaces) runs the viewshed over the whole DEM, about + /// 630 km long: one whose radius square, the DEM's diagonal each way, holds far more cells + /// than the DEM. + #[test] + fn a_viewshed_with_an_empty_radius_field_sees_the_whole_dem() { + use base64::Engine; + use rustgis_engine::geom::Coord; + let mut app = RustGisApp::with_sample(); + use rustgis_engine::data::raster::{ColorHint, Crs, GeoTransform, Raster, geotiff}; + // A strip 4,000 cells long and 2 high, 0.002° (about 160 m) a cell: about 630 km. The + // DEM's diagonal each way spans 8,001 × 8,001 cells, 64 million, of which 8,000 are the + // DEM's. + let (w, h) = (4_000u32, 2u32); + let gt = GeoTransform { origin_x: 10.0, origin_y: 45.004, pixel_width: 0.002, pixel_height: -0.002 }; + let dem = + Raster::new("strip", w, h, vec![vec![200.0; (w * h) as usize]], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let data = base64::engine::general_purpose::STANDARD.encode(geotiff::write(&dem, 0).unwrap()); + app.session.run("layer.addDataBytes", &json!({"fileName": "strip.tif", "data": data})).unwrap(); + let layer = app.session.map().layers.iter().rev().find(|l| l.is_raster()).unwrap().name.clone(); + // Cells of a viewshed worked out (not left no-data), and whether the strip's far end is. + let worked = |app: &RustGisApp, name: &str| { + let r = app.session.map().layer_by_name(name).and_then(|l| l.raster.as_ref()?.data.clone()).unwrap(); + let n = (0..h as i64) + .flat_map(|row| (0..w as i64).map(move |col| (col, row))) + .filter(|&(c, rr)| r.value(0, c, rr).is_some()) + .count(); + (n, r.value(0, i64::from(w) - 1, 0).is_some()) + }; + let at = Coord::new(10.001, 45.001); + // A radius given short of the far end leaves it out; one past the DEM's diagonal works + // out every cell, as an empty field does. + app.session + .run("analysis.viewshed", &json!({"layer": layer, "lon": at.x, "lat": at.y, "height": 2.0, "radius": 100_000, "name": "short"})) + .unwrap(); + assert!(!worked(&app, "short").1); + app.session + .run("analysis.viewshed", &json!({"layer": layer, "lon": at.x, "lat": at.y, "height": 2.0, "radius": 1e9, "name": "given"})) + .unwrap(); + assert_eq!(worked(&app, "given"), ((w * h) as usize, true)); + for (i, radius) in ["", " "].into_iter().enumerate() { + let workflow = Workflow { layer: layer.clone(), number: "2".into(), number2: radius.into(), ..Default::default() }; + let mut p = viewshed_params(&workflow, at); + assert!(p.get("radius").is_none(), "radius {radius:?}: {p}"); + let name = format!("empty{i}"); + p["name"] = json!(name); + app.session.run("analysis.viewshed", &p).unwrap_or_else(|e| panic!("radius {radius:?}: {e}")); + assert_eq!(worked(&app, &name), ((w * h) as usize, true), "radius {radius:?}: every cell worked out"); + } + // A number in the field is the radius; other text is refused, not taken as no radius. + let workflow = Workflow { layer: layer.clone(), number2: " 5000 ".into(), ..Default::default() }; + assert_eq!(viewshed_params(&workflow, Coord::new(10.0005, 45.0005))["radius"], json!(5000.0)); + // So is the height, and an empty one is the command's 1.7 m. + for (text, e) in [("abc", r#"not "abc""#), ("1,7", r#"not "1,7""#), ("-3", "not -3.0")] { + let workflow = Workflow { layer: layer.clone(), number: text.into(), ..Default::default() }; + let got = app.session.run("analysis.viewshed", &viewshed_params(&workflow, at)).unwrap_err(); + assert!(got.starts_with("height must be a number of metres from 0 to 10,000") && got.ends_with(e), "{got}"); + } + assert!(viewshed_params(&Workflow { layer: layer.clone(), ..Default::default() }, at).get("height").is_none()); + for text in ["500km", "inf", "NaN", "1e400", "-infinity"] { + let workflow = Workflow { layer: layer.clone(), number2: text.into(), ..Default::default() }; + let e = app.session.run("analysis.viewshed", &viewshed_params(&workflow, at)).unwrap_err(); + assert_eq!(e, format!(r#"radius must be a number of metres above 0, not "{text}""#)); + } + } + /// A Script pane run works its tools out on a thread of its own: the results say Running… /// until it lands, runs land in the order asked, and one cancelled or left says so. #[cfg(not(target_arch = "wasm32"))] diff --git a/crates/ui-egui/src/mapmenu.rs b/crates/ui-egui/src/mapmenu.rs index f84a351c29..df7fceb130 100644 --- a/crates/ui-egui/src/mapmenu.rs +++ b/crates/ui-egui/src/mapmenu.rs @@ -187,6 +187,16 @@ pub fn show(app: &mut RustGisApp, ui: &mut Ui, c: Coord) { } } +/// A viewshed of `radius` metres from `c` on `dem`, reading the ground as the Workflows pane's +/// Ground heights says (`bilinear`): the pane its progress shows in. +fn viewshed_here(bilinear: bool, dem: &str, c: Coord, radius: f64, name: &str) -> serde_json::Value { + let mut p = json!({"layer": dem, "lon": c.x, "lat": c.y, "radius": radius, "name": name}); + if bilinear { + p["heights"] = json!("bilinear"); + } + p +} + /// Quick Analysis: the Buffer tool at a few distances, a viewshed and a line of sight on an /// elevation raster in the map, and the Buffer tool's own pane. fn quick_analysis(app: &mut RustGisApp, ui: &mut Ui, c: Coord) { @@ -212,7 +222,7 @@ fn quick_analysis(app: &mut RustGisApp, ui: &mut Ui, c: Coord) { { let name = i18n::fmt("Viewshed {radius}", &[("radius", &radius)]); // In the background on the desktop, its progress and Cancel in the Workflows pane. - let p = json!({"layer": dem, "lon": c.x, "lat": c.y, "radius": r, "name": name}); + let p = viewshed_here(app.workflow.bilinear, dem, c, r, &name); crate::analysispane::run_elsewhere(app, "visibility", "analysis.viewshed", p); ui.close(); } @@ -240,6 +250,16 @@ fn quick_analysis(app: &mut RustGisApp, ui: &mut Ui, c: Coord) { mod tests { use super::*; + /// Viewshed N km Here reads the ground between cells when the Workflows pane, where its + /// progress shows, is set to. + #[test] + fn a_viewshed_here_reads_the_ground_as_the_workflows_pane_says() { + let c = Coord::new(8.5, 47.4); + let nearest = viewshed_here(false, "dem", c, 2000.0, "Viewshed 2 km"); + assert_eq!(nearest, json!({"layer": "dem", "lon": 8.5, "lat": 47.4, "radius": 2000.0, "name": "Viewshed 2 km"})); + assert_eq!(viewshed_here(true, "dem", c, 2000.0, "Viewshed 2 km")["heights"], json!("bilinear")); + } + /// A place on a world copy reaches the commands within ±180 (they refuse it otherwise), and /// a failed action shows in the status bar instead of doing nothing. #[test] diff --git a/docs/user-guide/analysis.md b/docs/user-guide/analysis.md index f2d004b2ec..e195ec96a3 100644 --- a/docs/user-guide/analysis.md +++ b/docs/user-guide/analysis.md @@ -103,8 +103,11 @@ times more work as the threads it runs on. Threads share cores and memory, so a can take up to about twice as long as a one-thread run at its own (measured on one machine, a Xeon Silver 4114; it can be longer on others); in the web app, on one thread, the limits stay as they are. The error names the limit on this computer and the threads it counted. The limits on memory -(the cells a grid may have, and those on the following pages) hold everywhere, as does Viewshed's on -its window: a radius covering more than 25 million cells, or 100,000 cells across, is refused. A +(the cells a grid may have, and those on the following pages) hold everywhere. Viewshed has no limit +on its window (a radius past the raster's diagonal is taken as the diagonal), only on its ray steps: +with no radius it covers the whole raster, so on a large one it can be refused where nobody can stop +the run (the web app, a script, the assistant). A smaller radius, or a run from its pane on the +desktop or with `rustgis-cli run`, gets it through. A tool's own default cell size still follows the one-thread limit, so it makes the same grid on any computer and from any caller; a finer cell size given is what a larger limit, or none, lets through. @@ -1235,7 +1238,7 @@ click them on the map: | Raster Functions | Slope, aspect, hillshade, NDVI, band math (`(b4-b3)/(b4+b3)`), remapping, thresholds, resampling | | Function Editor | Chains raster functions, each on the previous output | | Suitability Modeler | Scores rasters 1–10 and adds them with weights | -| Visibility Analysis | A viewshed from a point on an elevation raster, with the Earth's curvature and the refraction of visible light (1/7, as `gdal_viewshed`) | +| Visibility Analysis | A viewshed from a point on an elevation raster, with the Earth's curvature and the refraction of visible light (1/7, as `gdal_viewshed`). The ground along each ray is the cell each point falls in by default; `heights: "bilinear"` (**Ground heights › Between cells (bilinear)** in the Workflows pane) reads it between the cells' centres instead. Both are estimates of the ground between cell centres; between cells is closer on ground that bulges (a hill seen from its top), where the nearest cell can hide cells just inside the horizon. With no radius, or one longer than the raster's diagonal, the viewshed covers the whole raster. The map's **Viewshed N km Here** reads the ground as the Workflows pane's **Ground heights** says. On a raster round the whole Earth the rays don't cross its east–west edge, which the analysis says when the radius reaches it and the way across is shorter: the ground just across the edge is left out, worked out the long way round where the radius reaches the far edge through the raster too (always with no radius), or partly both, near the observer's row and not farther from it. The observer's height must be from 0 to 10,000 m. Ground with no data hides nothing, and next to it bilinear heights take the nearest cell's height; the analysis says how many cells this touched, in a notice. The answer gives both counts (0 when there is nothing to say): `acrossNoData` counts the visible cells whose rays crossed ground with no data (a hidden cell stays hidden whatever that ground is, so it isn't counted, and 0 doesn't mean no ray crossed any); `readNearest` counts every cell, visible or hidden, whose ray took a nearest height next to no data in bilinear mode | | Exploratory 3D Analysis | A line of sight between two points, split into seen and hidden parts, with the same curvature and refraction | | Geostatistical Wizard | An IDW surface from feature values, using 12 nearest neighbours by default | | Network Analysis | The shortest (or cheapest, by a cost field) route over a line layer |