diff --git a/crates/engine/src/cmd/layout.rs b/crates/engine/src/cmd/layout.rs index f1488262ce..601a63b4c3 100644 --- a/crates/engine/src/cmd/layout.rs +++ b/crates/engine/src/cmd/layout.rs @@ -4047,7 +4047,7 @@ fn layout_bytes_inner(s: &mut Session, li: usize, pdf: bool, dpi: f64, all: bool // The map frames a PDF can't georeference, and those it georeferences by their corners only, // each with the page (from 1) it is on. let (mut left_out, mut by_corners): (Vec<(usize, u32, String, &'static str)>, Vec<(usize, u32, String)>) = (Vec::new(), Vec::new()); - let mut render_pages = || -> Result<(Vec, Option>), String> { + let render_pages = || -> Result<(Vec, Option>), String> { let mut out = Vec::new(); let mut png = None; let mut held = 0usize; @@ -4107,7 +4107,15 @@ fn layout_bytes_inner(s: &mut Session, li: usize, pdf: bool, dpi: f64, all: bool } Ok((out, png)) }; - let result = render_pages(); + // Layers its frames drew without their cast shadows (read in place, too large for the + // browser, no memory, still being worked out on the interface's thread): said, as the map's + // export says them. + let (result, said) = rustgis_render::shadows_said(render_pages); + if result.is_ok() { + for w in super::share::shadow_warnings("The layout", &said) { + s.warn(w); + } + } // Stepping through the series moved the frame; put the layout back however that went. if stepping && let Some(cur) = s.project.layouts.get_mut(li) { *cur = saved.clone(); diff --git a/crates/engine/src/cmd/presentation.rs b/crates/engine/src/cmd/presentation.rs index 247c9c9f1f..2a980f797a 100644 --- a/crates/engine/src/cmd/presentation.rs +++ b/crates/engine/src/cmd/presentation.rs @@ -449,7 +449,7 @@ pub fn export_bytes(s: &mut Session, i: usize, format: &str, dpi: f64) -> Result })) }; let before = revision(s); - let result = export_bytes_inner(s, i, format, dpi); + let result = super::share::saying_shadows(s, "The presentation", |s| export_bytes_inner(s, i, format, dpi)); before.finish_revision(revision(s), Some(result), "could not draw the presentation")? } diff --git a/crates/engine/src/cmd/raster.rs b/crates/engine/src/cmd/raster.rs index 59d33304b1..3960b0f0a0 100644 --- a/crates/engine/src/cmd/raster.rs +++ b/crates/engine/src/cmd/raster.rs @@ -36,7 +36,7 @@ pub fn commands() -> Vec { C::new("layer.addDataBytes", "Add Data (from file contents)", "Home › Add", add_bytes).roles(&[]).effects(crate::policy::Effects::NONE) .params(r#"{"fileName": "name.tif|.tiff|.asc|.geojson|.csv|.zip|.kml|.kmz|.gpx|.parquet|.fgb|.gpkg|.mbtiles|.jp2|.j2k (JPEG 2000: desktop, through GDAL)", "data": base64, "zoom"?: bool, "layer"?: "one layer of a zip, KML or GPX by name", "name"?: text, "x"?, "y"?, "wkt"?, "crs"?, "delimiter"?, "paperSpace"?, "stream"?, "as"? (as layer.addData)}"#), C::new("raster.symbology", "Symbology", "Style › Rendering", symbology).when(need_raster).roles(&[]).effects(crate::policy::Effects::NONE).params( - r#"{"layer"?, "type": "stretch"|"rgb"|"classify"|"unique"|"colormap"|"shadedRelief", "band"?: 1.., "ramp"?, "invert"?: bool, "classes"?: 1..32, "method"?, "azimuth"?, "altitude"?, "zFactor"?, "grey"?: bool (shadedRelief without its colour ramp)}"#, + r#"{"layer"?, "type": "stretch"|"rgb"|"classify"|"unique"|"colormap"|"shadedRelief", "band"?: 1.., "ramp"?, "invert"?: bool, "classes"?: 1..32, "method"?, "azimuth"?, "altitude"?, "zFactor"?, "shadow"?: 0..1 (shadedRelief: how dark the shadows the terrain casts are; left out, kept; 0 casts none), "grey"?: bool (shadedRelief without its colour ramp)}"#, ), C::new("raster.stretch", "Stretch Type", "Style › Rendering", stretch).inputs(stretch_inputs).roles(&[]).effects(crate::policy::Effects::NONE) .when(need_raster) @@ -777,13 +777,21 @@ fn symbology(s: &mut Session, p: &Value) -> CmdResult { } RasterRenderer::Colormap } - "shadedrelief" | "hillshade" => RasterRenderer::ShadedRelief { - band: bi, - ramp: ramp.or(Some(Ramp::Terrain)).filter(|_| !b(p, "grey").unwrap_or(false)), - azimuth: f(p, "azimuth").unwrap_or(315.0).rem_euclid(360.0), - altitude: f(p, "altitude").unwrap_or(45.0).clamp(0.0, 90.0), - z_factor: f(p, "zFactor").unwrap_or(1.0).clamp(0.001, 1000.0), - }, + "shadedrelief" | "hillshade" => { + // Left out, a Shaded Relief keeps its own shadows; a new one casts none. + let cur_shadow = match rl.style.renderer { + RasterRenderer::ShadedRelief { shadow, .. } => shadow, + _ => 0.0, + }; + RasterRenderer::ShadedRelief { + band: bi, + ramp: ramp.or(Some(Ramp::Terrain)).filter(|_| !b(p, "grey").unwrap_or(false)), + azimuth: f(p, "azimuth").unwrap_or(315.0).rem_euclid(360.0), + altitude: f(p, "altitude").unwrap_or(45.0).clamp(0.0, 90.0), + z_factor: f(p, "zFactor").unwrap_or(1.0).clamp(0.001, 1000.0), + shadow: f(p, "shadow").unwrap_or(cur_shadow).clamp(0.0, 1.0), + } + } other => return Err(format!("unknown raster symbology '{other}'")), }; if matches!(rl.style.renderer, RasterRenderer::Colormap | RasterRenderer::UniqueValues { .. } | RasterRenderer::Classify { .. }) { diff --git a/crates/engine/src/cmd/report.rs b/crates/engine/src/cmd/report.rs index 0c4834d09a..1ed192e40e 100644 --- a/crates/engine/src/cmd/report.rs +++ b/crates/engine/src/cmd/report.rs @@ -1094,7 +1094,7 @@ fn drawn_bytes(s: &mut Session, i: usize, dpi: f64, pdf: bool) -> Result<(Vec Result, String> { Ok(png) } -/// Renders the active map at the current view (or a requested size) to PNG bytes. +/// Renders the active map at the current view (or a requested size) to PNG bytes. Layers drawn +/// without their cast shadows are said ([`saying_shadows`]). pub fn map_png(s: &mut Session, width: Option, height: Option, dpi: Option) -> Result, String> { let view_size = s.view_size; - png_of(s.map_mut(), view_size, width, height, dpi) + saying_shadows(s, "The map image", |s| png_of(s.map_mut(), view_size, width, height, dpi)) +} + +/// Runs `draw`, which draws maps or pages for `s` (an image, an export, a shared item), and says +/// as warnings about `what` what its frames said of their cast shadows once it drew (see +/// [`shadow_warnings`]). Whatever the engine draws for someone goes through it, or through +/// [`rustgis_render::shadows_said`] off the session (Never silent). +pub(crate) fn saying_shadows(s: &mut Session, what: &str, draw: impl FnOnce(&mut Session) -> Result) -> Result { + let (drawn, said) = rustgis_render::shadows_said(|| draw(s)); + if drawn.is_ok() { + for w in shadow_warnings(what, &said) { + s.warn(w); + } + } + drawn +} + +/// What frames said of their cast shadows, as warnings about `what`: layers drawn without them, +/// and, drawn on the interface's thread (which doesn't wait for them), that some were still +/// being worked out. What was drawn is written all the same. +pub(crate) fn shadow_warnings(what: &str, said: &rustgis_render::ShadowsSaid) -> Vec { + let mut out: Vec = said.notices.iter().map(|e| format!("{what}: {e}")).collect(); + if said.to_come { + out.push(format!( + "{what}: some layers are drawn without their cast shadows, still being worked out: draw it again once the map shows them" + )); + } + out } /// Renders `map` at its camera in a view of `(vw, vh)` points (or a requested size) to PNG bytes. @@ -344,7 +372,7 @@ fn export_view( /// inch of screen, kept as vectors with what is pixels by nature drawn at `dpi`. pub fn map_pdf(s: &mut Session, dpi: f64) -> Result, String> { let revisions = rustgis_render::archive_revisions([s.map()]); - let result = map_pdf_inner(s, dpi); + let result = saying_shadows(s, "The map PDF", |s| map_pdf_inner(s, dpi)); revisions.finish_revision(rustgis_render::archive_revisions([s.map()]), Some(result), "could not draw the map")? } @@ -411,14 +439,23 @@ pub(crate) fn map_work(s: &Session, p: &Value) -> Result { } let (mut map, view_size) = (s.map().detached(), s.view_size); Ok(Box::new(move || { + let mut shadows = Vec::new(); let written = (|| { - let png = png_of(&mut map, view_size, width, height, dpi)?; + let (png, said) = rustgis_render::shadows_said(|| png_of(&mut map, view_size, width, height, dpi)); + let png = png?; + shadows = shadow_warnings(&path, &said); rustgis_data::progress::check().map_err(|e| e.to_string())?; rustgis_data::io::write_atomic(Path::new(&path), &png).map_err(|e| format!("{path}: {e}"))?; Ok(json!({"path": path, "bytes": png.len()})) })(); - // What the size limit did is said of a file written. - let sized = if written.is_ok() { sized } else { Vec::new() }; + // What the size limit did, and layers drawn without their cast shadows, are said of a + // file written. + let sized = if written.is_ok() { + let warn = rustgis_data::diagnostics::Severity::Warning; + sized.into_iter().chain(shadows.into_iter().map(|e| (warn, e))).collect() + } else { + Vec::new() + }; super::exports::drawn(std::slice::from_ref(&map), sized, written, path) })) } diff --git a/crates/engine/src/cmd/sharing.rs b/crates/engine/src/cmd/sharing.rs index 600d2ce9b7..7aa3fa4685 100644 --- a/crates/engine/src/cmd/sharing.rs +++ b/crates/engine/src/cmd/sharing.rs @@ -190,8 +190,18 @@ pub fn commands() -> Vec { ] } -/// The shared item bytes of a kind: its name, bytes and source. +/// The shared item bytes of a kind: its name, bytes and source. Rasters drawn into it without +/// their cast shadows are said (see [`super::share::saying_shadows`]). pub fn share_bytes(s: &mut Session, kind: &str, p: &Value) -> Result<(String, Vec, String), String> { + let what = match kind { + "webMap" => "The web map", + "webLayer" => "The web layer", + _ => "The shared item", + }; + super::share::saying_shadows(s, what, |s| share_bytes_inner(s, kind, p)) +} + +fn share_bytes_inner(s: &mut Session, kind: &str, p: &Value) -> Result<(String, Vec, String), String> { match kind { "webMap" => { let mut m = map_of(s, p)?; diff --git a/crates/engine/src/tests.rs b/crates/engine/src/tests.rs index bd2a0198e7..39731f4f3b 100644 --- a/crates/engine/src/tests.rs +++ b/crates/engine/src/tests.rs @@ -3117,6 +3117,130 @@ fn custom_projections_switch_keep_scale_query_and_render() { } } +/// Shaded Relief's cast shadows: set, kept when left out, clamped, a new one without; saved with +/// the project only when there are some, and drawn in an export (waited for). +#[test] +fn shaded_relief_keeps_its_cast_shadows() { + let mut s = with_raster(); + let shadow = |s: &Session| match s.map().layers.first().and_then(|l| l.raster.as_ref()).map(|r| &r.style.renderer) { + Some(rustgis_map::RasterRenderer::ShadedRelief { shadow, .. }) => *shadow, + other => panic!("{other:?}"), + }; + s.run("raster.symbology", &json!({"type": "shadedRelief"})).unwrap(); + assert_eq!(shadow(&s), 0.0); + let shadows_saved = |s: &mut Session| s.project.saved_text(None).unwrap().0.matches("\"shadow\"").count(); + let before = shadows_saved(&mut s); + s.run("raster.symbology", &json!({"type": "shadedRelief", "shadow": 0.7})).unwrap(); + s.run("raster.symbology", &json!({"type": "shadedRelief", "azimuth": 200})).unwrap(); + assert_eq!(shadow(&s), 0.7, "left out, kept"); + s.run("raster.symbology", &json!({"type": "shadedRelief", "shadow": 4})).unwrap(); + assert_eq!(shadow(&s), 1.0); + assert_eq!(shadows_saved(&mut s), before + 1, "saved only when there are some"); + assert!(crate::cmd::share::map_png(&mut s, Some(300.0), Some(200.0), None).unwrap().len() > 1000); + s.run("raster.symbology", &json!({"type": "stretch"})).unwrap(); + s.run("raster.symbology", &json!({"type": "shadedRelief"})).unwrap(); + assert_eq!(shadow(&s), 0.0, "a new Shaded Relief casts none"); +} + +/// A map export that draws a layer without its cast shadows says so, as such (not as a tile layer +/// that failed), in a PNG, a GeoTIFF and the app's map image alike; one with nothing missing says +/// nothing. +#[test] +fn a_map_export_says_a_layer_drawn_without_its_cast_shadows() { + let mut s = with_raster(); + s.run("layer.zoomTo", &json!({"layer": "scene"})).unwrap(); + s.run("raster.symbology", &json!({"type": "shadedRelief", "shadow": 1})).unwrap(); + let dir = std::env::temp_dir().join(format!("rustgis-cast-notice-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let said = + |s: &Session| s.notices.iter().filter(|n| n.text.contains("cast shadows aren't drawn")).map(|n| n.text.clone()).collect::>(); + s.run("share.exportMap", &json!({"path": dir.join("clean.png").display().to_string(), "width": 200, "height": 150})).unwrap(); + assert!(said(&s).is_empty(), "{:?}", said(&s)); + // Read in place with only its overview held: no whole grid to trace. + let rl = s.map_mut().layers.iter_mut().find_map(|l| l.raster.as_mut()).unwrap(); + rl.in_place = true; + let mut r = (**rl.data.as_ref().unwrap()).clone(); + r.overview = Some((800, 600)); + rl.data = Some(std::sync::Arc::new(r)); + for name in ["shadowless.png", "shadowless.tif"] { + let before = said(&s).len(); + s.run("share.exportMap", &json!({"path": dir.join(name).display().to_string(), "width": 200, "height": 150})).unwrap(); + let now = said(&s); + assert_eq!(now.len(), before + 1, "{name}: {now:?}"); + let last = now.last().unwrap(); + assert!(last.contains("scene: its cast shadows aren't drawn") && last.contains("read in place"), "{name}: {last}"); + assert!(!last.contains("tile layer"), "{name}: {last}"); + } + // The app's Capture To Clipboard and Export Map download (`map_png`) say it too. + let before = said(&s).len(); + crate::cmd::share::map_png(&mut s, Some(200.0), Some(150.0), None).unwrap(); + assert_eq!(said(&s).len(), before + 1, "{:?}", said(&s)); + std::fs::remove_dir_all(&dir).ok(); +} + +/// Whatever draws the map for someone says a layer drawn without its cast shadows, named by the +/// layer: the map's image, PDF and web map, and the exports of a layout, a presentation and a +/// report showing it. Drawn on the interface's thread, which doesn't wait for them, shadows still +/// being worked out are said too. +#[test] +fn every_drawing_of_the_map_says_a_layer_drawn_without_its_cast_shadows() { + let mut s = with_raster(); + s.run("layer.zoomTo", &json!({"layer": "scene"})).unwrap(); + s.run("raster.symbology", &json!({"type": "shadedRelief", "shadow": 1})).unwrap(); + s.run("layout.new", &json!({"page": "a5", "template": "map"})).unwrap(); + s.run("presentation.new", &json!({"name": "Relief"})).unwrap(); + // First, as a PNG of the presentation is its first page. + s.run("presentation.mapPage", &json!({"title": "Relief", "at": 0})).unwrap(); + assert_eq!(s.project.presentations[0].pages[0].kind.code(), "map"); + s.run("report.new", &json!({"layer": "Countries", "name": "Relief", "fields": ["name"], "where": "name LIKE 'F%'"})).unwrap(); + s.run("report.newTemplate", &json!({"report": "Relief"})).unwrap(); + // Read in place with only its overview held: no whole grid to trace. + let rl = s.map_mut().layers.iter_mut().find_map(|l| l.raster.as_mut()).unwrap(); + rl.in_place = true; + let mut r = (**rl.data.as_ref().unwrap()).clone(); + r.overview = Some((800, 600)); + rl.data = Some(std::sync::Arc::new(r)); + let said = |s: &Session| s.notices.iter().filter(|n| n.text.contains("scene: its cast shadows aren't drawn")).count(); + let dir = std::env::temp_dir().join(format!("rustgis-cast-every-{}", std::process::id())); + std::fs::create_dir_all(&dir).unwrap(); + let path = |name: &str| dir.join(name).display().to_string(); + let draws: Vec<(&str, Box)> = vec![ + ("map image", Box::new(|s| drop(crate::cmd::share::map_png(s, Some(200.0), Some(150.0), None).unwrap()))), + ("map PDF", Box::new(|s| drop(crate::cmd::share::map_pdf(s, 72.0).unwrap()))), + ( + "map export", + Box::new(|s| drop(s.run("share.exportMap", &json!({"path": path("map.png"), "width": 200, "height": 150})).unwrap())), + ), + ("web map", Box::new(|s| drop(crate::cmd::sharing::share_bytes(s, "webMap", &json!({})).unwrap()))), + ("layout PNG", Box::new(|s| drop(s.run("layout.export", &json!({"layout": 0, "path": path("page.png"), "dpi": 36})).unwrap()))), + ("layout PDF", Box::new(|s| drop(s.run("layout.export", &json!({"layout": 0, "path": path("page.pdf"), "dpi": 36})).unwrap()))), + ("presentation PDF", Box::new(|s| drop(s.run("presentation.export", &json!({"path": path("deck.pdf"), "dpi": 36})).unwrap()))), + ("presentation PNG", Box::new(|s| drop(s.run("presentation.export", &json!({"path": path("deck.png"), "dpi": 36})).unwrap()))), + ( + "report PDF", + Box::new(|s| drop(s.run("report.export", &json!({"report": "Relief", "path": path("report.pdf"), "dpi": 36})).unwrap())), + ), + ]; + for (what, draw) in &draws { + // A notice repeating the last one is kept once (two presentation exports in a row). + s.notices.clear(); + draw(&mut s); + assert!(said(&s) > 0, "{what}: {:?}", s.notices.iter().map(|n| &n.text).collect::>()); + } + std::fs::remove_dir_all(&dir).ok(); + // On the interface's thread a new sun's shadows aren't waited for: the image says so. + let mut s = with_raster(); + s.run("layer.zoomTo", &json!({"layer": "scene"})).unwrap(); + s.run("raster.symbology", &json!({"type": "shadedRelief", "azimuth": 123, "shadow": 1})).unwrap(); + crate::render::on_the_interface_thread(); + crate::cmd::share::map_png(&mut s, Some(200.0), Some(150.0), None).unwrap(); + assert!( + s.notices.iter().any(|n| n.text.contains("still being worked out")), + "{:?}", + s.notices.iter().map(|n| &n.text).collect::>() + ); +} + #[test] fn raster_layers_open_style_identify_and_round_trip() { let mut s = with_raster(); diff --git a/crates/map/src/lib.rs b/crates/map/src/lib.rs index af59997e67..c37a53aebc 100644 --- a/crates/map/src/lib.rs +++ b/crates/map/src/lib.rs @@ -24,6 +24,7 @@ pub mod projection; pub mod qgis; pub mod raster; pub mod report; +pub mod shadow; pub mod slots; pub mod source; pub use slots::{LayerRole, Slot, SlotAt, SlotPos, TileRole}; diff --git a/crates/map/src/qgis/raster.rs b/crates/map/src/qgis/raster.rs index 97861256c4..0bf86b4335 100644 --- a/crates/map/src/qgis/raster.rs +++ b/crates/map/src/qgis/raster.rs @@ -94,6 +94,7 @@ fn renderer_style(node: Node, pipe: Node, r: Node, kind: &str, layer: &str, repo azimuth: num("azimuth", 315.0).rem_euclid(360.0), altitude: num("angle", 45.0).clamp(0.0, 90.0), z_factor: num("zfactor", 1.0).clamp(0.0001, 10_000.0), + shadow: 0.0, }; (renderer, Stretch::None) } diff --git a/crates/map/src/qgis/tests.rs b/crates/map/src/qgis/tests.rs index 14bf27c0ba..71578a7a16 100644 --- a/crates/map/src/qgis/tests.rs +++ b/crates/map/src/qgis/tests.rs @@ -845,7 +845,7 @@ fn raster_renderers_read_as_rustgis_raster_styles() { ); assert_eq!( s.raster.unwrap().renderer, - RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 300.0, altitude: 35.0, z_factor: 2.0 } + RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 300.0, altitude: 35.0, z_factor: 2.0, shadow: 0.0 } ); assert!(report.notes.iter().any(|n| n.text.contains("saturation"))); let (s, report) = read(r#""#, ""); diff --git a/crates/map/src/raster.rs b/crates/map/src/raster.rs index e54be60c54..eccaf4c545 100644 --- a/crates/map/src/raster.rs +++ b/crates/map/src/raster.rs @@ -58,6 +58,9 @@ pub struct RasterLayer { /// Statistics of the pixels the style's mask leaves, worked out on the first draw. #[serde(skip)] masked: MaskedStats, + /// The light its cast shadows leave, worked out off the frame (see [`RasterLayer::cast_shadows`]). + #[serde(skip)] + cast: CastLight, /// A remote reload shared with render snapshots, never serialized. #[serde(skip)] opening: Option, @@ -192,6 +195,7 @@ impl RasterLayer { pub fn reset_replacement_read(&mut self) { self.read_generation = next_read_generation(); self.masked = MaskedStats::default(); + self.cast = CastLight::default(); self.opening = None; self.read_still = None; self.restyle = false; @@ -236,6 +240,7 @@ impl RasterLayer { data: Some(Arc::new(r)), error: None, masked: MaskedStats::default(), + cast: CastLight::default(), opening: None, read_still: None, read_generation: next_read_generation(), @@ -284,6 +289,7 @@ impl RasterLayer { data: Some(Arc::new(raster)), error: None, masked: MaskedStats::default(), + cast: CastLight::default(), opening: None, read_still: None, read_generation: next_read_generation(), @@ -315,6 +321,7 @@ impl RasterLayer { data: Some(Arc::new(raster)), error: None, masked: MaskedStats::default(), + cast: CastLight::default(), opening: None, read_still: None, read_generation: next_read_generation(), @@ -351,6 +358,7 @@ impl RasterLayer { data: None, error: None, masked: MaskedStats::default(), + cast: CastLight::default(), opening: None, read_still: None, read_generation: next_read_generation(), @@ -717,6 +725,291 @@ impl RasterLayer { } Some(stats) } + + /// Whether it is drawn with cast shadows (Shaded Relief with a shadow above 0): its frames are + /// drawn again as they land (see [`RasterLayer::cast_shadows`]). + pub fn casts_shadows(&self) -> bool { + matches!(self.style.renderer, RasterRenderer::ShadedRelief { shadow, .. } if shadow > 0.0) + } + + /// The light its cast shadows leave on each cell (see [`crate::shadow::light`]), when it is + /// drawn as Shaded Relief with shadows. Worked out once per pixels, band, sun, Z factor and + /// mask and kept: each owner's latest, and a few of suns left, for going back. + /// `owner` is who draws it (its map's and its layer's live identities, see + /// [`crate::Layer::instance_id`]; a layer's id repeats from map to map): a new sun from the + /// same owner stops the work + /// for its last one, unless something waits for it. Natively it is worked out on a thread of + /// its own, then `landed` is called (the map asks to be drawn again); with `wait`, as an + /// export does, this waits for it. The browser, which has one thread, works it out here, for + /// at most [`crate::shadow::MAX_BROWSER_CELLS`] cells. + pub fn cast_shadows(&self, wait: bool, owner: (u64, u64), landed: impl FnOnce() + Send + 'static) -> CastShadows { + let RasterRenderer::ShadedRelief { band, azimuth, altitude, z_factor, shadow, .. } = self.style.renderer else { + return CastShadows::None; + }; + let finite = [azimuth, altitude, z_factor].iter().all(|v| v.is_finite()); + let Some(r) = self.data.as_ref().filter(|_| shadow > 0.0 && finite) else { return CastShadows::None }; + // Read in place, the layer holds an overview; the part in view is read as the map draws. + if self.in_place && r.overview.is_some_and(|(w, _)| w > r.width) { + return CastShadows::Unavailable("its cast shadows aren't drawn: it is read in place, and only its overview is held".into()); + } + let cells = r.width as usize * r.height as usize; + if cfg!(target_arch = "wasm32") && cells > crate::shadow::MAX_BROWSER_CELLS { + return CastShadows::Unavailable(format!( + "its cast shadows aren't drawn: in the browser they are worked out for rasters of at most {} cells, and it has {cells}", + crate::shadow::MAX_BROWSER_CELLS + )); + } + let key = LightKey { band, azimuth, altitude, z_factor, mask: self.style.mask.clone() }; + let mut start = None; + let work = { + let Ok(mut jobs) = self.cast.0.lock() else { return CastShadows::None }; + // Grids of pixels no longer held go (their work stops as it is dropped), and so does + // work stopped part-way (a cancelled run), to be started again. + jobs.retain(|j| j.pixels.strong_count() > 0 && !j.work.was_stopped()); + let pixels = Arc::downgrade(r); + let same = |j: &LightJob| j.key == key && Weak::ptr_eq(&j.pixels, &pixels); + // The same owner's work for another sun, not done and not waited for, is superseded + // (going back to a sun kept too): it stops, as it is dropped. Grids done are kept, for + // going back. + jobs.retain(|j| same(j) || j.owner != owner || j.work.is_done() || j.work.waited()); + match jobs.iter().position(same) { + Some(i) => { + // The latest used last, so the oldest goes first. + let mut job = jobs.remove(i); + job.owner = owner; + let work = job.work.clone(); + jobs.push(job); + // Joining work under way (an export's, another frame's): drawn again when it + // lands too. + work.on_landing(landed); + work + } + None => { + // Each owner's latest grid is kept: it is what that owner draws, and letting it go + // would only have it worked out again, letting another go (a page of more maps, + // lit otherwise, than were kept never got its shadows). The grids of suns + // owners have left, done and waited for by nothing, are kept for going back: the + // oldest goes past a few. + let left: Vec = (0..jobs.len()) + .filter(|i| { + jobs.get(*i).is_some_and(|j| { + j.work.is_done() && !j.work.waited() && jobs.iter().skip(i + 1).any(|later| later.owner == j.owner) + }) + }) + .collect(); + if left.len() >= KEPT_LIGHTS + && let Some(i) = left.first() + { + jobs.remove(*i); + } + let work = Arc::new(LightWork::default()); + work.on_landing(landed); + jobs.push(LightJob { key: key.clone(), pixels: Arc::downgrade(r), owner, work: work.clone() }); + start = Some((r.clone(), key)); + work + } + } + }; + // Started without holding the lock: a thread the system refuses runs it here. + if let Some((r, key)) = start { + start_light(r, key, work.clone()); + } + work.result(wait) + } +} + +/// [`RasterLayer::cast_shadows`]: what the map draws its cast shadows with. +#[derive(Clone, Debug, PartialEq)] +pub enum CastShadows { + /// It casts none (another renderer, or a shadow of 0). + None, + /// The light left on each cell (0–255), row by row as the pixels are. + Ready(Arc>), + /// Being worked out: drawn without, and again once it has landed. + Pending, + /// Drawn without them, and why. + Unavailable(String), +} + +/// What a light grid is worked out for, besides the pixels. +#[derive(Clone, Debug, PartialEq)] +struct LightKey { + band: usize, + azimuth: f64, + altitude: f64, + z_factor: f64, + mask: RasterMask, +} + +/// A light grid's work, shared with the thread doing it. +#[derive(Default)] +struct LightWork { + stop: std::sync::atomic::AtomicBool, + /// The grid, or why there is none, once it is done. + done: Mutex>, String>>>, + landed: std::sync::Condvar, + /// How many wait for it (exports): it is neither superseded nor let go meanwhile. + waiting: std::sync::atomic::AtomicUsize, + /// Called once it is done: each frame or page drawn while it was to come asks to be drawn + /// again (at most [`MAX_LANDINGS`] are kept; the first already redraws them all). + landings: Mutex>>, +} + +/// The most landing calls a light grid's work keeps. +const MAX_LANDINGS: usize = 32; + +impl LightWork { + /// Calls `landed` once the work is done; nothing when it is already (the caller has it). + fn on_landing(&self, landed: impl FnOnce() + Send + 'static) { + // Checked under the calls' lock, which `land` takes after the work is done: a call is + // either kept and made, or not needed. + let Ok(mut calls) = self.landings.lock() else { return }; + if !self.is_done() && calls.len() < MAX_LANDINGS { + calls.push(Box::new(landed)); + } + } + + /// Makes the landing calls, once the work is done. + fn land(&self) { + let calls = self.landings.lock().map(|mut c| std::mem::take(&mut *c)).unwrap_or_default(); + for call in calls { + call(); + } + } + + fn is_done(&self) -> bool { + self.done.lock().is_ok_and(|d| d.is_some()) + } + + /// Whether it was stopped part-way, rather than done. + fn was_stopped(&self) -> bool { + self.done.lock().is_ok_and(|d| matches!(d.as_ref(), Some(Err(e)) if e == STOPPED)) + } + + fn waited(&self) -> bool { + self.waiting.load(std::sync::atomic::Ordering::SeqCst) > 0 + } + + fn finish(&self, out: Result>, String>) { + if let Ok(mut done) = self.done.lock() { + *done = Some(out); + } + self.landed.notify_all(); + } + + /// What it has: with `wait`, once it is done, unless the run waiting is cancelled (see + /// [`rustgis_data::progress`]). A cancelled run that was the only one waiting stops the work + /// too (the worker has no probe of its own): the map, drawing again, starts it over. + fn result(&self, wait: bool) -> CastShadows { + let _waiting = wait.then(|| Waiting::on(&self.waiting)); + let Ok(mut done) = self.done.lock() else { return CastShadows::None }; + while wait && done.is_none() && rustgis_data::progress::check().is_ok() { + done = match self.landed.wait_timeout(done, std::time::Duration::from_millis(100)) { + Ok((d, _)) => d, + Err(_) => return CastShadows::None, + }; + } + if wait && done.is_none() && self.waiting.load(std::sync::atomic::Ordering::SeqCst) == 1 { + self.stop.store(true, std::sync::atomic::Ordering::Relaxed); + } + match done.as_ref() { + Some(Ok(grid)) => CastShadows::Ready(grid.clone()), + Some(Err(why)) => CastShadows::Unavailable(why.clone()), + None => CastShadows::Pending, + } + } +} + +/// Counts one waiting for a light grid while it lives. +struct Waiting<'a>(&'a std::sync::atomic::AtomicUsize); + +impl<'a> Waiting<'a> { + fn on(count: &'a std::sync::atomic::AtomicUsize) -> Self { + count.fetch_add(1, std::sync::atomic::Ordering::SeqCst); + Waiting(count) + } +} + +impl Drop for Waiting<'_> { + fn drop(&mut self) { + self.0.fetch_sub(1, std::sync::atomic::Ordering::SeqCst); + } +} + +/// The light grid kept for a layer, and the work for it. +struct LightJob { + key: LightKey, + /// Held weakly, so their address isn't reused. + pixels: Weak, + /// Who drew it last (see [`RasterLayer::cast_shadows`]). + owner: (u64, u64), + work: Arc, +} + +impl Drop for LightJob { + /// Replaced, or its layer gone: the work for it stops. + fn drop(&mut self) { + self.work.stop.store(true, std::sync::atomic::Ordering::Relaxed); + } +} + +/// The light grids kept for a layer and its copies, the latest used last. +#[derive(Clone, Default)] +struct CastLight(Arc>>); + +/// Why a light grid stopped part-way has none: superseded, or its run cancelled. +const STOPPED: &str = "its cast shadows were stopped"; + +/// The most grids of suns their owners have left that a layer and its copies keep, besides +/// each owner's latest. +const KEPT_LIGHTS: usize = 3; + +/// Works out a light grid: natively on a thread of its own (here if the system refuses one), +/// in the browser here. +fn start_light(r: Arc, key: LightKey, work: Arc) { + let run = move || { + let threads = rustgis_data::threads::max(); + let traced = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| { + crate::shadow::light(&r, key.band, &key.mask, key.azimuth, key.altitude, key.z_factor, threads, &work.stop) + })); + match traced { + // Stopped (superseded, or its export cancelled): a frame or page drawn while it was + // to come is drawn again, and asks for what it draws now. + Ok(Err(crate::shadow::Unlit::Stopped)) => { + work.finish(Err(STOPPED.into())); + work.land(); + } + Ok(out) => { + work.finish(out.map(Arc::new).map_err(|e| match e { + crate::shadow::Unlit::Failed => "its cast shadows aren't drawn: working them out failed".into(), + _ => "its cast shadows aren't drawn: there isn't the memory for them".into(), + })); + work.land(); + } + // Said, rather than leaving an export waiting. + Err(_) => { + work.finish(Err("its cast shadows aren't drawn: working them out failed".into())); + work.land(); + } + } + }; + #[cfg(not(target_arch = "wasm32"))] + { + let run = std::sync::Arc::new(Mutex::new(Some(run))); + let on_thread = run.clone(); + let spawned = std::thread::Builder::new().name("cast shadows".into()).spawn(move || { + if let Some(f) = on_thread.lock().ok().and_then(|mut f| f.take()) { + f(); + } + }); + if spawned.is_err() + && let Some(f) = run.lock().ok().and_then(|mut f| f.take()) + { + f(); + } + } + #[cfg(target_arch = "wasm32")] + run(); } /// Reapplies a scan's placement to pixels read again, without copying their bands. @@ -784,6 +1077,10 @@ impl Default for ZarrTime { } } +fn is_no_shadow(v: &f64) -> bool { + *v == 0.0 +} + fn is_zero(v: &u64) -> bool { *v == 0 } @@ -983,8 +1280,17 @@ pub enum RasterRenderer { UniqueValues { band: usize, ramp: Ramp, values: Vec<(f64, Rgba)> }, /// The file's own colour table. Colormap, - /// Hillshade, optionally tinted by elevation. - ShadedRelief { band: usize, ramp: Option, azimuth: f64, altitude: f64, z_factor: f64 }, + /// Hillshade, optionally tinted by elevation. `shadow` (0 to 1) is how dark the shadows the + /// terrain casts are drawn (see [`crate::shadow`]); 0, the default, casts none. + ShadedRelief { + band: usize, + ramp: Option, + azimuth: f64, + altitude: f64, + z_factor: f64, + #[serde(default, skip_serializing_if = "is_no_shadow")] + shadow: f64, + }, } impl RasterRenderer { @@ -1675,6 +1981,7 @@ impl RasterLayer { data: _, error: _, masked: _, + cast: _, opening: _, read_still: _, read_generation: _, @@ -2036,4 +2343,183 @@ mod tests { assert!(plain.reload().is_err()); assert!(plain.opening.is_none(), "an anonymous web raster is not fetched whole"); } + + /// A tower lit from the east, drawn as Shaded Relief with `shadow`. + fn tower(shadow: f64) -> RasterLayer { + let gt = GeoTransform { origin_x: 0.0, origin_y: 0.0, pixel_width: 30.0, pixel_height: -30.0 }; + let data: Vec = (0..400).map(|i| if i == 10 * 20 + 10 { 900.0 } else { 0.0 }).collect(); + let r = Raster::new("tower", 20, 20, vec![data], gt, Crs::WebMercator, None, ColorHint::Gray, "Float32").unwrap(); + let mut rl = RasterLayer::from_path(r, "tower.tif"); + rl.style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 90.0, altitude: 30.0, z_factor: 1.0, shadow }; + rl + } + + /// A shadow of 0 casts none and starts no work; one above it is worked out once, kept, waited + /// for by an export, and worked out again for another sun. + #[test] + fn cast_shadows_are_worked_out_once_per_sun() { + assert_eq!(tower(0.0).cast_shadows(true, (0, 1), || {}), CastShadows::None); + let mut rl = tower(0.8); + // Each landing is sent: `landed` is called on the worker just after the grid is kept, so + // it is waited for, not read at once. + let (sent, landings) = std::sync::mpsc::channel::<()>(); + let landed = |tx: &std::sync::mpsc::Sender<()>| { + let tx = tx.clone(); + move || { + let _ = tx.send(()); + } + }; + let CastShadows::Ready(grid) = rl.cast_shadows(true, (0, 1), landed(&sent)) else { panic!("waited for") }; + assert!(landings.recv_timeout(std::time::Duration::from_secs(60)).is_ok(), "landed once"); + // West of the tower, in its shadow; east of it, lit. + assert_eq!(grid[10 * 20 + 9], 0); + assert_eq!(grid[10 * 20 + 11], 255); + // Kept: the same grid, nothing worked out again, and nothing more lands. + assert!(matches!(rl.cast_shadows(false, (0, 1), landed(&sent)), CastShadows::Ready(g) if Arc::ptr_eq(&g, &grid))); + drop(sent); + assert!(landings.recv().is_err(), "landed again"); + // The shadow's strength is drawn, not worked out: the grid is kept for another. + if let RasterRenderer::ShadedRelief { shadow, .. } = &mut rl.style.renderer { + *shadow = 0.3; + } + assert!(matches!(rl.cast_shadows(false, (0, 1), || {}), CastShadows::Ready(g) if Arc::ptr_eq(&g, &grid))); + // Another sun: worked out again, lit from the west now. + if let RasterRenderer::ShadedRelief { azimuth, .. } = &mut rl.style.renderer { + *azimuth = 270.0; + } + let CastShadows::Ready(west) = rl.cast_shadows(true, (0, 1), || {}) else { panic!("waited for") }; + assert_eq!((west[10 * 20 + 9], west[10 * 20 + 11]), (255, 0)); + // A copy lit from elsewhere (another map, whose layer has the same id) keeps its own grid + // beside it: neither stops the other's. + let mut copy = rl.clone(); + if let RasterRenderer::ShadedRelief { azimuth, .. } = &mut copy.style.renderer { + *azimuth = 0.0; + } + assert!(matches!(copy.cast_shadows(true, (9, 1), || {}), CastShadows::Ready(_))); + assert!(matches!(rl.cast_shadows(false, (0, 1), || {}), CastShadows::Ready(g) if Arc::ptr_eq(&g, &west))); + } + + /// A new sun from the same owner stops the work for its last one, unless it is done; another + /// owner's (a copy on another map) goes on. + #[test] + fn a_new_sun_supersedes_the_owners_last_work() { + let gt = GeoTransform { origin_x: 0.0, origin_y: 0.0, pixel_width: 30.0, pixel_height: -30.0 }; + let data: Vec = (0..1200 * 1200).map(|i| (((i % 1200) as f32 / 7.0).sin() * 300.0) + (i / 1200) as f32).collect(); + let r = Raster::new("hills", 1200, 1200, vec![data], gt, Crs::WebMercator, None, ColorHint::Gray, "Float32").unwrap(); + let mut rl = RasterLayer::from_path(r, "hills.tif"); + let lit = |rl: &mut RasterLayer, az: f64| { + rl.style.renderer = + RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: az, altitude: 10.0, z_factor: 1.0, shadow: 1.0 }; + }; + let other = |az: f64, rl: &RasterLayer| { + let mut c = rl.clone(); + lit(&mut c, az); + c + }; + let work_of = |rl: &RasterLayer, az: f64| rl.cast.0.lock().unwrap().iter().find(|j| j.key.azimuth == az).map(|j| j.work.clone()); + lit(&mut rl, 10.0); + rl.cast_shadows(false, (0, 1), || {}); + let copy = other(20.0, &rl); + copy.cast_shadows(false, (9, 1), || {}); + let first = work_of(&rl, 10.0).unwrap(); + lit(&mut rl, 30.0); + rl.cast_shadows(false, (0, 1), || {}); + // Owner 1's last sun is stopped and let go, unless it was done; owner 2's goes on. + let stopped = first.stop.load(std::sync::atomic::Ordering::SeqCst); + assert!(first.is_done() || (stopped && work_of(&rl, 10.0).is_none())); + let second = work_of(&rl, 20.0).unwrap(); + assert!(!second.stop.load(std::sync::atomic::Ordering::SeqCst)); + assert!(work_of(&rl, 30.0).is_some()); + // Going back to a sun kept stops the one just left, as a new sun would. + lit(&mut rl, 40.0); + rl.cast_shadows(false, (0, 1), || {}); + let left = work_of(&rl, 40.0).unwrap(); + lit(&mut rl, 30.0); + rl.cast_shadows(false, (0, 1), || {}); + assert!(left.is_done() || (left.stop.load(std::sync::atomic::Ordering::SeqCst) && work_of(&rl, 40.0).is_none())); + assert!(matches!(copy.cast_shadows(true, (9, 1), || {}), CastShadows::Ready(_))); + // Waited for, the latest is drawn. + assert!(matches!(rl.cast_shadows(true, (0, 1), || {}), CastShadows::Ready(_))); + } + + /// An export cancelled while it waits for a grid it alone waits for stops the work (the + /// worker has no probe of its own), and the grid isn't kept: the next draw starts it over. + #[test] + fn a_cancelled_export_stops_the_work_it_waited_for() { + struct Cancelled; + impl rustgis_data::progress::Probe for Cancelled { + fn cancelled(&self) -> bool { + true + } + fn begin(&self, _: u64) {} + fn advance(&self, _: u64) {} + } + // Gentle ground under a sun at 2°: every cell traces to the raster's edge, far longer + // than the stop takes. + let gt = GeoTransform { origin_x: 0.0, origin_y: 0.0, pixel_width: 30.0, pixel_height: -30.0 }; + let data: Vec = (0..2000 * 2000).map(|i| ((i % 2000) as f32 * 0.01) + ((i / 2000) as f32 * 0.01)).collect(); + let r = Raster::new("plain", 2000, 2000, vec![data], gt, Crs::WebMercator, None, ColorHint::Gray, "Float32").unwrap(); + let mut rl = RasterLayer::from_path(r, "plain.tif"); + rl.style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 135.0, altitude: 2.0, z_factor: 1.0, shadow: 1.0 }; + let (sent, landings) = std::sync::mpsc::channel::<()>(); + { + let _cancelled = rustgis_data::progress::install(Some(std::sync::Arc::new(Cancelled))); + let tx = sent.clone(); + let out = rl.cast_shadows(true, (0, 1), move || { + let _ = tx.send(()); + }); + assert_eq!(out, CastShadows::Pending, "the cancelled export gives up"); + } + // The worker stops and says so (the map draws again), with no grid. + assert!(landings.recv_timeout(std::time::Duration::from_secs(60)).is_ok(), "landed"); + let work = rl.cast.0.lock().unwrap().first().map(|j| j.work.clone()).unwrap(); + assert!(work.was_stopped()); + // Asked again, it starts over. + rl.cast_shadows(false, (0, 1), || {}); + let again = rl.cast.0.lock().unwrap().first().map(|j| j.work.clone()).unwrap(); + assert!(!Arc::ptr_eq(&work, &again)); + again.stop.store(true, std::sync::atomic::Ordering::Relaxed); + } + + /// A frame joining work under way (an export started it) is drawn again when it lands too. + #[test] + fn who_joins_work_under_way_is_told_when_it_lands() { + let gt = GeoTransform { origin_x: 0.0, origin_y: 0.0, pixel_width: 30.0, pixel_height: -30.0 }; + let data: Vec = (0..800 * 800).map(|i| ((i % 800) as f32 * 0.01) + ((i / 800) as f32 * 0.01)).collect(); + let r = Raster::new("plain", 800, 800, vec![data], gt, Crs::WebMercator, None, ColorHint::Gray, "Float32").unwrap(); + let mut rl = RasterLayer::from_path(r, "plain.tif"); + rl.style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 135.0, altitude: 3.0, z_factor: 1.0, shadow: 1.0 }; + let (sent, landings) = std::sync::mpsc::channel::<&'static str>(); + let told = |who: &'static str| { + let tx = sent.clone(); + move || { + let _ = tx.send(who); + } + }; + let first = rl.cast_shadows(false, (0, 1), told("starter")); + let joined = rl.cast_shadows(false, (5, 1), told("joiner")); + // Joined while under way (it traces far under a 3° sun), both are told; done already, the + // joiner has the grid and needs no call. + if first == CastShadows::Pending && joined == CastShadows::Pending { + let mut heard = vec![landings.recv_timeout(std::time::Duration::from_secs(120)).unwrap()]; + heard.push(landings.recv_timeout(std::time::Duration::from_secs(120)).unwrap()); + heard.sort_unstable(); + assert_eq!(heard, ["joiner", "starter"]); + } + assert!(matches!(rl.cast_shadows(true, (0, 1), || {}), CastShadows::Ready(_))); + } + + /// Read in place with only its overview held, it is drawn without cast shadows, and says so; + /// with the whole image held, it has them. + #[test] + fn cast_shadows_of_a_raster_read_in_place_need_the_whole_image() { + let mut rl = tower(1.0); + rl.in_place = true; + assert!(matches!(rl.cast_shadows(true, (0, 1), || {}), CastShadows::Ready(_))); + let mut r = (**rl.data.as_ref().unwrap()).clone(); + r.overview = Some((80, 80)); + rl.data = Some(Arc::new(r)); + let CastShadows::Unavailable(why) = rl.cast_shadows(true, (0, 1), || {}) else { panic!("said") }; + assert!(why.contains("read in place"), "{why}"); + } } diff --git a/crates/map/src/shadow.rs b/crates/map/src/shadow.rs new file mode 100644 index 0000000000..e30eb07195 --- /dev/null +++ b/crates/map/src/shadow.rs @@ -0,0 +1,324 @@ +//! Cast shadows for Shaded Relief (opengeos/RustGIS#1782): how much of the sun each cell of an +//! elevation raster sees over the terrain between it and the sun. +//! +//! The sun is a disc [`SOFT_EDGE`] degrees either side of its altitude, so a shadow has a soft +//! edge. Each cell traces the terrain toward the sun's azimuth one column or row at a time, +//! reading heights between cells (bilinear: reading the nearest cell instead over-shadows diagonal +//! suns, franciscoparrao/surtgis#153), and keeps the steepest angle up to the terrain it passes. +//! The share of the disc above that angle is the light the cell keeps. The trace stops once +//! nothing farther can change it: the terrain left can't rise above the angle kept (or the disc's +//! lower edge), or the disc is already hidden. Cells outside the raster cast no shadow on it. + +use std::sync::atomic::{AtomicBool, Ordering}; + +use rustgis_data::raster::Raster; + +use crate::raster::RasterMask; + +/// Half the sun's apparent size, in degrees: how wide a shadow's soft edge is. Far larger than the +/// real sun's quarter of a degree, for a soft edge at map scale. +pub const SOFT_EDGE: f64 = 5.0; + +/// The most cells a raster's shadows are worked out for in the browser, which has one thread: past +/// it, the relief is drawn without them, and said. +pub const MAX_BROWSER_CELLS: usize = 500_000; + +/// Cells below which the work stays on one thread: starting threads costs more. +const ONE_THREAD_BELOW: usize = 64 * 1024; + +/// Why there is no light grid. +#[derive(Clone, Debug, PartialEq, Eq)] +pub enum Unlit { + /// `stop` was set: a newer sun or raster replaced it. + Stopped, + /// The grid couldn't be held. + NoMemory, + /// A thread working it out failed (panicked). + Failed, +} + +/// The light left by cast shadows on each cell of `band` (`0` in shadow to `255` lit), row by row +/// as the raster's pixels are, for a sun at `azimuth` (degrees clockwise from north) and `altitude` +/// (degrees above the horizon), heights scaled by `z_factor`. Cells that are no data or masked are +/// lit and cast no shadow. Rows are split over up to `threads` threads, each the same as on one. +/// Looks at `stop` between rows, and at the run's Cancel (see [`rustgis_data::progress`]) on a +/// thread that has one (the browser, which works it out where it is asked). On the desktop the +/// worker has none: a cancelled export that waited for it alone sets `stop`. A sun under about 5° +/// traces far over gentle ground: the cost grows with the raster's width as well as its cells. +pub fn light( + r: &Raster, + band: usize, + mask: &RasterMask, + azimuth: f64, + altitude: f64, + z_factor: f64, + threads: usize, + stop: &AtomicBool, +) -> Result, Unlit> { + let (w, h) = (r.width as usize, r.height as usize); + let cells = w.checked_mul(h).ok_or(Unlit::NoMemory)?; + let mut out = Vec::new(); + out.try_reserve_exact(cells).map_err(|_| Unlit::NoMemory)?; + out.resize(cells, 255u8); + let Some(data) = r.bands.get(band).map(|b| b.data.as_slice()).filter(|d| d.len() >= cells) else { + return Ok(out); + }; + let height = |v: f32| (r.is_valid(v) && !mask.hides(v)).then(|| f64::from(v) * z_factor); + let top = data.iter().filter_map(|v| height(*v)).fold(f64::NEG_INFINITY, f64::max); + if !top.is_finite() || w == 0 { + return Ok(out); + } + let sun = Sun::new(r, azimuth, altitude); + let trace = Trace { data, w, h, top, sun: &sun, height: &height }; + let threads = if cells < ONE_THREAD_BELOW { 1 } else { threads.clamp(1, h) }; + let rows = h.div_ceil(threads); + let chunks: Vec<(usize, &mut [u8])> = out.chunks_mut(rows * w).enumerate().collect(); + let run = |(i, chunk): (usize, &mut [u8])| -> Result<(), Unlit> { + for (dy, row) in chunk.chunks_mut(w).enumerate() { + if stop.load(Ordering::Relaxed) || rustgis_data::progress::check().is_err() { + return Err(Unlit::Stopped); + } + trace.row(i * rows + dy, row); + } + Ok(()) + }; + if threads <= 1 { + chunks.into_iter().try_for_each(run)?; + } else { + let run = &run; + // Each part in a slot its thread takes it from: one the system refuses to start leaves it + // there, and it runs here (a refused thread costs speed, not the grid). + let slots: Vec>> = chunks.into_iter().map(|c| std::sync::Mutex::new(Some(c))).collect(); + let results = std::thread::scope(|scope| { + let mut refused = Vec::new(); + let mut handles = Vec::new(); + for slot in &slots { + match std::thread::Builder::new().spawn_scoped(scope, move || take(slot).map_or(Ok(()), run)) { + Ok(handle) => handles.push(handle), + Err(_) => refused.push(slot), + } + } + let mut results: Vec> = refused.into_iter().filter_map(take).map(run).collect(); + results.extend(handles.into_iter().map(|h| h.join().unwrap_or(Err(Unlit::Failed)))); + results + }); + results.into_iter().collect::>()?; + } + Ok(out) +} + +/// What a slot holds, taken out once. +fn take(slot: &std::sync::Mutex>) -> Option { + slot.lock().ok().and_then(|mut c| c.take()) +} + +/// The sun as each cell's trace needs it. +struct Sun { + /// A step toward the sun, in columns and rows: one column or one row, whichever is more. + step: (f64, f64), + /// That step's length on the ground, in metres. + metres: f64, + /// The tangents of the disc's lower and upper edges. + low: f64, + high: f64, + altitude: f64, +} + +impl Sun { + fn new(r: &Raster, azimuth: f64, altitude: f64) -> Self { + let (cx, cy) = r.cell_size_m(); + let (cx, cy) = (cx.max(1e-9), cy.max(1e-9)); + let (sin, cos) = azimuth.to_radians().sin_cos(); + // East is along the columns when the pixel width is positive; north is up the rows when + // the pixel height is negative (north up), down them when it is positive (bottom up). + let east = sin / cx * r.transform.pixel_width.signum(); + let north = cos / cy * -r.transform.pixel_height.signum(); + let longest = east.abs().max(north.abs()).max(1e-12); + let step = (east / longest, north / longest); + let metres = ((step.0 * cx).powi(2) + (step.1 * cy).powi(2)).sqrt(); + let altitude = altitude.clamp(0.0, 90.0); + let edge = |a: f64| a.clamp(-89.9, 89.9).to_radians().tan(); + Sun { step, metres, low: edge(altitude - SOFT_EDGE), high: edge(altitude + SOFT_EDGE), altitude } + } + + /// The share of the disc above the steepest tangent `t` seen toward it, 0 to 255. + fn lit(&self, t: f64) -> u8 { + if t <= self.low { + return 255; + } + if t >= self.high { + return 0; + } + let seen = t.atan().to_degrees(); + let share = (self.altitude + SOFT_EDGE - seen) / (2.0 * SOFT_EDGE); + (share.clamp(0.0, 1.0) * 255.0).round() as u8 + } +} + +/// One raster's trace toward the sun. +struct Trace<'a, H: Fn(f32) -> Option> { + data: &'a [f32], + w: usize, + h: usize, + /// The highest cell, scaled. + top: f64, + sun: &'a Sun, + /// A cell's height, scaled, unless it is no data or masked. + height: &'a H, +} + +impl Option> Trace<'_, H> { + fn at(&self, col: usize, row: usize) -> Option { + (self.height)(*self.data.get(row * self.w + col)?) + } + + /// The height between cell centres at column `x` and row `y` (fractional, inside the grid), + /// bilinear between the four around it; with one of them missing, the nearest one. + fn between(&self, x: f64, y: f64) -> Option { + let (i, j) = (x.floor() as usize, y.floor() as usize); + let (fx, fy) = (x - i as f64, y - j as f64); + let (i1, j1) = ((i + 1).min(self.w - 1), (j + 1).min(self.h - 1)); + match (self.at(i, j), self.at(i1, j), self.at(i, j1), self.at(i1, j1)) { + (Some(a), Some(b), Some(c), Some(d)) => { + let top = a + (b - a) * fx; + let bottom = c + (d - c) * fx; + Some(top + (bottom - top) * fy) + } + _ => self.at(if fx < 0.5 { i } else { i1 }, if fy < 0.5 { j } else { j1 }), + } + } + + /// Fills `out` with the light left on each cell of row `row`. + fn row(&self, row: usize, out: &mut [u8]) { + let (sx, sy) = self.sun.step; + let (wmax, hmax) = ((self.w - 1) as f64, (self.h - 1) as f64); + for (col, cell) in out.iter_mut().enumerate() { + let Some(z0) = self.at(col, row) else { continue }; + let mut steepest = f64::NEG_INFINITY; + let mut k = 1.0; + loop { + let (x, y) = (col as f64 + sx * k, row as f64 - sy * k); + if !(0.0..=wmax).contains(&x) || !(0.0..=hmax).contains(&y) { + break; + } + let d = k * self.sun.metres; + if let Some(z) = self.between(x, y) { + steepest = steepest.max((z - z0) / d); + } + // Nothing farther rises above what is kept: the angle seen, or the disc's lower + // edge (below it the cell has the whole sun); or the whole disc is hidden. + if (self.top - z0) / d <= steepest.max(self.sun.low) || steepest >= self.sun.high { + break; + } + k += 1.0; + } + *cell = self.sun.lit(steepest); + } + } +} + +#[cfg(test)] +mod tests { + use rustgis_data::raster::{ColorHint, Crs, GeoTransform}; + + use super::*; + + const CELL: f64 = 30.0; + + fn dem(w: u32, h: u32, z: impl Fn(f64, f64) -> f64) -> Raster { + let gt = GeoTransform { origin_x: 500_000.0, origin_y: 7_000_000.0, pixel_width: CELL, pixel_height: -CELL }; + let mut data = Vec::with_capacity((w * h) as usize); + for row in 0..h { + for col in 0..w { + // Metres east and north of the north-west corner's cell centre. + data.push(z(f64::from(col) * CELL, -f64::from(row) * CELL) as f32); + } + } + Raster::new("dem", w, h, vec![data], gt, Crs::from_epsg(31983).unwrap_or(Crs::WebMercator), None, ColorHint::Gray, "Float32") + .unwrap_or_else(|e| panic!("{e}")) + } + + fn lit(r: &Raster, azimuth: f64, altitude: f64) -> Vec { + light(r, 0, &RasterMask::default(), azimuth, altitude, 1.0, 4, &AtomicBool::new(false)).unwrap_or_else(|e| panic!("{e:?}")) + } + + /// A plane rising toward the sun shades itself only when it is steeper than the sun is high + /// (past the soft edge): the same at every azimuth, the diagonals too (surtgis#153). + #[test] + fn a_plane_facing_away_is_shaded_only_past_the_suns_altitude() { + for azimuth in [0.0, 20.0, 45.0, 90.0, 135.0, 180.0, 225.0, 270.0, 300.0, 315.0] { + let (sin, cos) = f64::to_radians(azimuth).sin_cos(); + for (slope, want) in [(20.0, 255), (24.0, 255), (36.0, 0), (40.0, 0)] { + let t = f64::to_radians(slope).tan(); + let r = dem(40, 40, |e, n| (e * sin + n * cos) * t); + let g = lit(&r, azimuth, 30.0); + // Away from the edges facing the sun, where the trace leaves the raster at once. + for row in 10..30 { + for col in 10..30 { + assert_eq!(g[row * 40 + col], want, "azimuth {azimuth}, slope {slope}, cell {col},{row}"); + } + } + } + } + } + + /// Inside the soft edge, the light falls with the slope, by the share of the disc hidden. + #[test] + fn the_soft_edge_is_the_share_of_the_disc_hidden() { + let t = f64::to_radians(30.0).tan(); + let r = dem(40, 40, |e, _| e * t); + // Rising east, lit from the east at the slope's own angle: half the disc is hidden. + let g = lit(&r, 90.0, 30.0); + assert!((127..=128).contains(&g[20 * 40 + 20]), "{}", g[20 * 40 + 20]); + } + + /// A wall casts a shadow as long as its height over the sun's tangent, at each main azimuth. + #[test] + fn a_walls_shadow_has_the_length_its_height_gives() { + let (height, altitude) = (300.0, 45.0); + // Lit from the east, a north–south wall at column 40 shades the cells west of it. + let r = dem(60, 20, |e, _| if (e / CELL).round() == 40.0 { height } else { 0.0 }); + let g = lit(&r, 90.0, altitude); + let row = &g[10 * 60..11 * 60]; + // The whole disc is hidden up to height / tan(45° + 5°) away, none of it past + // height / tan(45° − 5°). + let full = (height / f64::to_radians(altitude + SOFT_EDGE).tan() / CELL).floor() as usize; + let none = (height / f64::to_radians(altitude - SOFT_EDGE).tan() / CELL).ceil() as usize; + for d in 1..=full { + assert_eq!(row[40 - d], 0, "{d} cells west"); + } + for d in none + 1..30 { + assert_eq!(row[40 - d], 255, "{d} cells west"); + } + // East of the wall, facing the sun, nothing is shaded. + assert!(row[41..].iter().all(|v| *v == 255)); + } + + /// A trace stopped part-way gives no grid; flat ground, no data and a mask cast nothing. + #[test] + fn stopped_flat_and_missing_cells() { + let flat = dem(300, 300, |_, _| 100.0); + let stop = AtomicBool::new(true); + assert_eq!(light(&flat, 0, &RasterMask::default(), 315.0, 30.0, 1.0, 4, &stop), Err(Unlit::Stopped)); + assert!(lit(&flat, 315.0, 30.0).iter().all(|v| *v == 255)); + // A tower masked out casts no shadow. + let tower = dem(40, 40, |e, n| if (e / CELL).round() == 20.0 && (n / CELL).round() == -20.0 { 1000.0 } else { 0.0 }); + assert!(lit(&tower, 90.0, 30.0).contains(&0)); + let masked = RasterMask { values: vec![1000.0], ..RasterMask::default() }; + let g = light(&tower, 0, &masked, 90.0, 30.0, 1.0, 1, &AtomicBool::new(false)).unwrap_or_default(); + assert!(g.iter().all(|v| *v == 255)); + // A band that isn't there leaves every cell lit. + let g = light(&tower, 3, &RasterMask::default(), 90.0, 30.0, 1.0, 1, &AtomicBool::new(false)).unwrap_or_default(); + assert!(g.iter().all(|v| *v == 255)); + } + + /// The grid is the same on one thread as on several, bit for bit. + #[test] + fn threads_give_the_same_grid() { + let r = dem(300, 300, |e, n| 400.0 * ((e / 900.0).sin() * (n / 700.0).cos()) + e * 0.05); + let one = light(&r, 0, &RasterMask::default(), 315.0, 25.0, 1.0, 1, &AtomicBool::new(false)); + let many = light(&r, 0, &RasterMask::default(), 315.0, 25.0, 1.0, 7, &AtomicBool::new(false)); + assert_eq!(one, many); + assert!(one.unwrap_or_default().iter().any(|v| *v < 255)); + } +} diff --git a/crates/render/src/layout.rs b/crates/render/src/layout.rs index 5de552d916..59e1fcff58 100644 --- a/crates/render/src/layout.rs +++ b/crates/render/src/layout.rs @@ -67,15 +67,27 @@ pub fn archive_revisions(layout: &Layout, maps: &[Map]) -> crate::ArchiveRevisio /// Renders a layout at `dpi` (dots per inch). `maps` are the project's maps, found by name. /// Refuses a linked archive changed while composing the page, including its different map frames. pub fn render(layout: &Layout, maps: &mut [Map], dpi: f64, info: &PageInfo) -> Result { - render_pending(layout, maps, dpi, info).map(|(pm, _)| pm) + render_page(layout, maps, dpi, info, true).map(|(pm, _)| pm) } /// [`render`], and whether a map frame on the page drew while some of its tiles, or a read of its /// streamed layers or rasters, were still on their way: in the browser, which doesn't wait for /// them, the page is drawn again once they land. +/// Drawn for the Layout view on the interface's thread, its frames don't wait for cast shadows +/// still being worked out: [`crate::shadows_said`] says so, and the page is drawn again as they +/// land (natively too, where its tiles were waited for). pub fn render_pending(layout: &Layout, maps: &mut [Map], dpi: f64, info: &PageInfo) -> Result<(Pixmap, bool), String> { + render_page(layout, maps, dpi, info, false) +} + +/// [`render_pending`], its frames waiting for cast shadows when `wait_shadows` (an export). +fn render_page(layout: &Layout, maps: &mut [Map], dpi: f64, info: &PageInfo, wait_shadows: bool) -> Result<(Pixmap, bool), String> { let revisions = archive_revisions(layout, maps); - let result = render_pending_inner(layout, maps, dpi, info); + let result = if wait_shadows { + render_pending_inner(layout, maps, dpi, info) + } else { + crate::without_shadow_wait(|| render_pending_inner(layout, maps, dpi, info)) + }; revisions.finish_revision(archive_revisions(layout, maps), result, "the page is too large to draw") } @@ -496,8 +508,13 @@ fn frame_canvas( grid: Option<(&Grid, bool)>, ) -> Option { let view = View { width: w, height: h, pixels_per_point: ppp, camera, sky: false }; - let img = if record { crate::render_complete_recorded(map, &view) } else { crate::render_complete(map, &view) }?; - *pending |= img.tiles_pending || img.data_pending; + // Why its layers were drawn without their cast shadows is kept for the page's caller (see + // `crate::shadows_said`). + let (img, shadows) = crate::frame_with_shadows_to_come(|| { + if record { crate::render_complete_recorded(map, &view) } else { crate::render_complete(map, &view) } + }); + let img = img?; + *pending |= img.tiles_pending || img.data_pending || shadows; Some(finish_frame(img, ppp, grid.map(|(g, comma)| (&*map, &view, g, comma)))) } @@ -3432,6 +3449,108 @@ mod tests { render(&l, &mut [map.clone()], 96.0, &PageInfo::default()).unwrap() } + /// A page whose frame draws a layer without its cast shadows says why, named by the layer; one + /// with them, or without any asked for, says nothing. + #[test] + fn a_page_says_why_a_frame_drew_no_cast_shadows() { + let relief = |shadow| rustgis_map::raster::RasterRenderer::ShadedRelief { + band: 0, + ramp: None, + azimuth: 315.0, + altitude: 30.0, + z_factor: 1.0, + shadow, + }; + for shadow in [0.0, 1.0] { + let map = ramp_map(relief(shadow), rustgis_map::raster::Stretch::MinMax); + let (_, said) = crate::shadows_said(|| colorbar_page(&map, Orientation::Horizontal, false, "")); + assert!(said.notices.is_empty() && !said.to_come, "shadow {shadow}: {said:?}"); + } + // Read in place with only its overview held: no whole grid to trace. + let mut map = ramp_map(relief(1.0), rustgis_map::raster::Stretch::MinMax); + let rl = map.layers.iter_mut().find_map(|l| l.raster.as_mut()).unwrap(); + rl.in_place = true; + let mut r = (**rl.data.as_ref().unwrap()).clone(); + r.overview = Some((1000, 10)); + rl.data = Some(std::sync::Arc::new(r)); + let (_, said) = crate::shadows_said(|| colorbar_page(&map, Orientation::Horizontal, false, "")); + let said = said.notices; + assert_eq!(said.len(), 1, "{said:?}"); + assert!(said[0].starts_with("dem: ") && said[0].contains("read in place"), "{said:?}"); + // What the map view's frame said is not a page's: a clean page drawn after it says nothing. + let camera = + rustgis_map::Camera { center: rustgis_geom::lonlat_to_merc(Coord::new(0.5, 0.5)), res: 2000.0, bearing: 0.0, pitch: 0.0 }; + crate::render(&mut map, &crate::View { width: 64.0, height: 64.0, pixels_per_point: 1.0, camera, sky: false }); + let clean = ramp_map(relief(0.0), rustgis_map::raster::Stretch::MinMax); + let (_, said) = crate::shadows_said(|| colorbar_page(&clean, Orientation::Horizontal, false, "")); + assert!(said.notices.is_empty(), "{said:?}"); + } + + /// A page with maps showing copies of one relief (each layer the first of its map, so with the + /// same id), each under its own sun, drawn again until it has no shadows to come, as the + /// Layout view draws it while they land. Panics if it never settles. + fn page_settles_with_suns(suns: &[f64]) { + use rustgis_data::raster::{ColorHint, Crs, GeoTransform, Raster}; + let n = 300usize; + let heights: Vec = (0..n * n).map(|i| (((i % n) as f32 / 9.0).sin() + ((i / n) as f32 / 7.0).cos()) * 400.0).collect(); + let gt = GeoTransform { origin_x: -1.0, origin_y: 1.0, pixel_width: 2.0 / n as f64, pixel_height: -2.0 / n as f64 }; + let dem = Raster::new("dem", n as u32, n as u32, vec![heights], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let rl = rustgis_map::raster::RasterLayer::from_path(dem, "dem.tif"); + let mut maps = Vec::new(); + let mut l = Layout::new("Layout", 100.0, 100.0); + for (i, azimuth) in suns.iter().enumerate() { + let name = format!("m{i}"); + let mut copy = rl.clone(); + copy.style.renderer = rustgis_map::raster::RasterRenderer::ShadedRelief { + band: 0, + ramp: None, + azimuth: *azimuth, + altitude: 10.0, + z_factor: 1.0, + shadow: 1.0, + }; + let mut m = Map::new(name.clone()); + assert_eq!(m.add_raster("dem", copy), 1); + maps.push(m); + let frame = ElementKind::MapFrame { + map: name.clone(), + center: Coord::new(0.0, 0.0), + scale: 1e7, + shape: FrameShape::Rectangle, + grid: None, + extent_of: None, + extent_color: rustgis_map::layout::INDICATOR_COLOR, + extent_width: rustgis_map::layout::INDICATOR_WIDTH, + bearing: 0.0, + pitch: 0.0, + }; + l.add(&name, (5.0 + 20.0 * i as f64, 5.0, 18.0, 18.0), frame); + } + let start = std::time::Instant::now(); + loop { + let (drawn, said) = crate::shadows_said(|| render_pending(&l, &mut maps, 48.0, &PageInfo::default())); + drawn.unwrap(); + assert!(said.notices.is_empty(), "{said:?}"); + if !said.to_come { + break; + } + assert!(start.elapsed() < std::time::Duration::from_secs(60), "the page never got its shadows"); + std::thread::yield_now(); + } + } + + /// Two maps lit otherwise on a page: neither map's grid stops the other's. + #[test] + fn two_maps_lit_otherwise_on_a_page_keep_their_own_shadows() { + page_settles_with_suns(&[315.0, 135.0]); + } + + /// More maps lit otherwise than the grids kept for going back: none is let go while it is drawn. + #[test] + fn many_maps_lit_otherwise_on_a_page_all_get_their_shadows() { + page_settles_with_suns(&[315.0, 135.0, 45.0, 225.0, 0.0]); + } + /// A map with one 100 × 1 raster valued 0–99 by column, styled by `renderer`. fn ramp_map(renderer: rustgis_map::raster::RasterRenderer, stretch: rustgis_map::raster::Stretch) -> Map { use rustgis_data::raster::{ColorHint, Crs, GeoTransform, Raster}; diff --git a/crates/render/src/lib.rs b/crates/render/src/lib.rs index 766203ca87..37c6809673 100644 --- a/crates/render/src/lib.rs +++ b/crates/render/src/lib.rs @@ -3681,6 +3681,9 @@ fn render_frame( record: bool, ) -> Option { let (w, h) = view.pixel_size(); + // Who draws a layer's cast shadows: this map and the layer, by their live identities (a + // layer's id repeats from map to map: a locator's and its main map's, say). + let map_instance = map.instance_id(); // Kept as vectors (`record`) on the CPU, for a flat frame without view effects or a // colour-vision simulation it applies (pixel filters over the whole frame; an export, // `full_res_rasters`, never simulates colour vision); anything else draws its pixels. @@ -4020,12 +4023,42 @@ fn render_frame( }; let stats = rl.masked_stats(); let stats = stats.as_ref().map(|s| s.as_slice()); + // Its cast shadows, never waited for here (an export waits before it draws, see + // `complete`): drawn without them meanwhile, and again once they land. A map's frame + // says so as tiles to come; a page's, as shadows to come. + let light = match rl.cast_shadows(false, (map_instance, layer.instance_id()), shadows_landed) { + rustgis_map::raster::CastShadows::Ready(grid) => Some(grid), + rustgis_map::raster::CastShadows::Pending => { + if full_res_rasters { + SHADOWS_TO_COME.with(|c| c.set(true)); + } else { + tile_out.pending = true; + } + None + } + rustgis_map::raster::CastShadows::Unavailable(why) => { + let e = format!("{}: {why}", layer.name); + // A page's frames say it on the page too (see `layout::shadow_notices`). + SHADOW_NOTICES.with(|n| { + let mut n = n.borrow_mut(); + if !n.contains(&e) { + n.push(e.clone()); + } + }); + if !tile_out.errors.contains(&e) { + tile_out.errors.push(e); + } + None + } + rustgis_map::raster::CastShadows::None => None, + }; + let light = light.as_deref().map(Vec::as_slice); // Read in place: the part in view, at the level the view needs. let address = rl.path.as_deref().filter(|_| rl.in_place); let mut draw_it = |pm: &mut Pixmap, opacity: f32| match address { // Drawn from less than the view needs (a coarser level, tiles that couldn't be // read): shown, and said with the tile errors. - Some(a) => match raster::draw_in_place(pm, a, data, &rl.style, stats, view, opacity, full_res_rasters, place) { + Some(a) => match raster::draw_in_place(pm, a, data, &rl.style, stats, view, opacity, full_res_rasters, place, light) { Ok(pending) => { tile_out.pending |= pending; if pending && !tile_out.pending_in_place.contains(&layer.id) { @@ -4042,7 +4075,7 @@ fn render_frame( } } }, - None => raster::draw(pm, data, &rl.style, stats, view, opacity, full_res_rasters, place), + None => raster::draw(pm, data, &rl.style, stats, view, opacity, full_res_rasters, place, light), }; if offscreen { let mut target = Pixmap::new(w, h)?; @@ -6305,6 +6338,90 @@ impl LabelGrid { } } +thread_local! { + /// Set on the interface's thread ([`on_the_interface_thread`]), and while the Layout view's + /// page is drawn: frames don't wait for cast shadows (see [`without_shadow_wait`]). + static NO_SHADOW_WAIT: std::cell::Cell = const { std::cell::Cell::new(false) }; + /// A frame drawn at full resolution had cast shadows still to come (see [`shadows_said`]). + static SHADOWS_TO_COME: std::cell::Cell = const { std::cell::Cell::new(false) }; + /// Why layers drawn on this thread were drawn without their cast shadows, each said once (see + /// [`shadows_said`]). + static SHADOW_NOTICES: std::cell::RefCell> = const { std::cell::RefCell::new(Vec::new()) }; +} + +/// What the frames drawn in [`shadows_said`] said of their cast shadows. +#[derive(Debug, Default, Clone, PartialEq)] +pub struct ShadowsSaid { + /// Why layers were drawn without them, each once, named by the layer ("Relief: its cast + /// shadows aren't drawn: …"). + pub notices: Vec, + /// Some were drawn without them still being worked out (on the interface's thread, which + /// doesn't wait): drawn again once they land, they show them. + pub to_come: bool, +} + +/// Runs `f`, which draws maps or pages on this thread, and gives what its frames said of their +/// cast shadows: the one way to read it, so whatever draws for someone says it (Never silent). +/// What frames drawn before on this thread left (the map view's, say) is not `f`'s. +pub fn shadows_said(f: impl FnOnce() -> T) -> (T, ShadowsSaid) { + take_said(); + let out = f(); + (out, take_said()) +} + +/// What frames drawn on this thread since the last call said of their cast shadows. +fn take_said() -> ShadowsSaid { + ShadowsSaid { notices: take_shadow_notices(), to_come: SHADOWS_TO_COME.with(|c| c.replace(false)) } +} + +fn take_shadow_notices() -> Vec { + SHADOW_NOTICES.with(|n| std::mem::take(&mut *n.borrow_mut())) +} + +/// Marks this thread as the interface's: frames drawn on it (an image, a print, a page drawn while +/// the window waits) never wait for cast shadows still being worked out (Never hold the window). +/// They are drawn without them, which [`shadows_said`] says; exports drawn off it wait for them. +pub fn on_the_interface_thread() { + NO_SHADOW_WAIT.with(|c| c.set(true)); +} + +/// Called when a layer's cast shadows land: the map, or the page, is drawn again. +fn shadows_landed() { + rustgis_tiles::cache::notify_at(web_time::Instant::now()); +} + +/// Runs `f` (the Layout view's page) with its frames drawn without the cast shadows still being +/// worked out, rather than waiting for them: they say so ([`shadows_said`]), and the page is +/// drawn again as they land. +pub(crate) fn without_shadow_wait(f: impl FnOnce() -> T) -> T { + let before = NO_SHADOW_WAIT.with(|c| c.replace(true)); + let out = f(); + NO_SHADOW_WAIT.with(|c| c.set(before)); + out +} + +/// Runs `f`, which draws one frame, and whether that frame had cast shadows still to come; what +/// frames before it said is kept for [`shadows_said`]. +pub(crate) fn frame_with_shadows_to_come(f: impl FnOnce() -> T) -> (T, bool) { + let before = SHADOWS_TO_COME.with(|c| c.replace(false)); + let out = f(); + let to_come = SHADOWS_TO_COME.with(|c| c.replace(before)); + if to_come { + SHADOWS_TO_COME.with(|c| c.set(true)); + } + (out, to_come) +} + +/// Waits for the cast shadows of the map's visible Shaded Relief layers, as an export does (it +/// runs off the interface's thread); the wait gives up when the run is cancelled. +fn wait_for_cast_shadows(map: &Map) { + for layer in map.layers.iter().filter(|l| l.visible) { + if let Some(rl) = &layer.raster { + rl.cast_shadows(true, (map.instance_id(), layer.instance_id()), shadows_landed); + } + } +} + /// Render passes [`render_complete`] makes at most with nothing come since the last (the wait ran /// out, or nothing was under way): passes that draw what came are bound by its minute alone. const IDLE_PASSES: usize = 6; @@ -6325,6 +6442,11 @@ pub(crate) fn render_complete_recorded(map: &mut Map, view: &View) -> Option Option { + // Cast shadows still being worked out are waited for first, unless this draws on the + // interface's thread (see `on_the_interface_thread`). + if !NO_SHADOW_WAIT.with(std::cell::Cell::get) { + wait_for_cast_shadows(map); + } // What had come when it drew: what lands meanwhile is news to the wait. let mut drawn_at = rustgis_tiles::cache::generation(); let mut r = render_cpu(map, view, true, record)?; @@ -6412,8 +6534,15 @@ pub struct Placed { /// [`render_png`] refuses. pub fn render_placed(map: &mut Map, view: &View) -> Result { let revisions = archive_revisions([&*map]); - let r = render_exported(map, view)?; - let mut gaps = Vec::new(); + // Layers drawn without their cast shadows are said as gaps, not as tile layers that failed; + // what frames before it said is kept for `shadows_said`. + let before = take_shadow_notices(); + let r = render_exported(map, view); + let shadows = take_shadow_notices(); + SHADOW_NOTICES.with(|n| *n.borrow_mut() = before); + let r = r?; + let tile_errors: Vec<&String> = r.tile_errors.iter().filter(|e| !shadows.contains(e)).collect(); + let mut gaps = shadows; if r.tiles_pending { gaps.push("some tiles were still on their way when the export stopped waiting, so parts of tile layers are empty: export again once the map has drawn them".to_string()); } @@ -6423,8 +6552,8 @@ pub fn render_placed(map: &mut Map, view: &View) -> Result { .to_string(), ); } - if let Some(first) = r.tile_errors.first() { - let n = r.tile_errors.len(); + if let Some(first) = tile_errors.first() { + let n = tile_errors.len(); gaps.push(if n == 1 { format!("a tile layer couldn't be drawn, so its part is empty: {first}") } else { @@ -8476,6 +8605,27 @@ mod tests { m } + /// An export waits for a layer's cast shadows, worked out off the frame, and draws them. + #[test] + fn an_export_waits_for_cast_shadows() { + let mut m = hill_map(); + let id = m.layers.iter().find(|l| l.raster.is_some()).map(|l| l.id).unwrap(); + let lit = |m: &mut Map, shadow: f64| { + let l = m.layer_mut(id).unwrap(); + l.visible = true; + l.raster.as_mut().unwrap().style.renderer = + rustgis_map::RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 5.0, z_factor: 1.0, shadow }; + }; + let camera = Camera { center: lonlat_to_merc(Coord::new(0.0, 0.0)), res: 1200.0, bearing: 0.0, pitch: 0.0 }; + let view = View { width: 200.0, height: 200.0, pixels_per_point: 1.0, camera, sky: false }; + lit(&mut m, 0.0); + let plain = render_complete(&mut m, &view).unwrap(); + lit(&mut m, 1.0); + let shaded = render_complete(&mut m, &view).unwrap(); + assert!(!shaded.tiles_pending); + assert_ne!(plain.pixmap.data(), shaded.pixmap.data(), "drawn with its shadows"); + } + #[test] fn a_raster_at_the_closest_zoom_is_drawn_where_it_is() { // At the deepest zoom (#902) the raster's far corners lie billions of pixels from the diff --git a/crates/render/src/raster.rs b/crates/render/src/raster.rs index 67fbeb07ef..48e653c442 100644 --- a/crates/render/src/raster.rs +++ b/crates/render/src/raster.rs @@ -86,7 +86,9 @@ fn place_is_flat(p: &Place) -> bool { } /// Draws a raster layer onto `pm` at `opacity`. `stats` are the renderer bands' statistics -/// without the masked pixels, when the style has a mask. +/// without the masked pixels, when the style has a mask. `light` is the light its cast shadows +/// leave on each of its cells, for Shaded Relief with shadows (see +/// [`rustgis_map::raster::RasterLayer::cast_shadows`]). #[allow(clippy::too_many_arguments)] pub(crate) fn draw( pm: &mut Pixmap, @@ -97,9 +99,10 @@ pub(crate) fn draw( opacity: f32, full_res: bool, place: Place, + light: Option<&[u8]>, ) { let threads = threads_for(pm.width() as usize * pm.height() as usize); - draw_with(pm, r, style, stats, view, opacity, full_res, place, threads); + draw_with(pm, r, style, stats, view, opacity, full_res, place, threads, light); } /// Screen points a side sampled to find the part of a raster read in place that is in view, and @@ -128,7 +131,7 @@ const UNBLENDED: &str = "no memory to blend the part in view with its overview, /// statistics (the overview's when not given), so the part in view is stretched as the whole is. /// Returns whether tiles are still to come (the map is drawn again as they land), or why it drew /// less than the view needs (the overview, or other levels for tiles that couldn't be read): the -/// map shows what it has, an export refuses it. +/// map shows what it has, an export refuses it. `light` is as [`draw`] takes it. #[allow(clippy::too_many_arguments)] pub(crate) fn draw_in_place( pm: &mut Pixmap, @@ -140,6 +143,7 @@ pub(crate) fn draw_in_place( opacity: f32, full_res: bool, place: Place, + light: Option<&[u8]>, ) -> Result { let bands = style.renderer.bands(); let own: Vec = match stats { @@ -147,7 +151,9 @@ pub(crate) fn draw_in_place( None => bands.iter().map(|b| r.bands.get(*b).map(|b| b.stats.clone()).unwrap_or_default()).collect(), }; let stats = stats.unwrap_or(&own); - let whole = |pm: &mut Pixmap| draw(pm, r, style, Some(stats), view, opacity, full_res, place); + // Its cast shadows are only worked out when the overview is the whole image (see + // `RasterLayer::cast_shadows`), so only it is drawn with them. + let whole = |pm: &mut Pixmap| draw(pm, r, style, Some(stats), view, opacity, full_res, place, light); let full = r.overview.unwrap_or((r.width, r.height)); if full.0 <= r.width { whole(pm); @@ -257,12 +263,12 @@ pub(crate) fn draw_in_place( if opacity >= 1.0 { whole(pm); for part in &parts { - draw(pm, part, &own_style, Some(stats), view, 1.0, full_res, place); + draw(pm, part, &own_style, Some(stats), view, 1.0, full_res, place, None); } } else if let Some(mut both) = Pixmap::new(pm.width(), pm.height()) { - draw(&mut both, r, style, Some(stats), view, 1.0, full_res, place); + draw(&mut both, r, style, Some(stats), view, 1.0, full_res, place, None); for part in &parts { - draw(&mut both, part, &own_style, Some(stats), view, 1.0, full_res, place); + draw(&mut both, part, &own_style, Some(stats), view, 1.0, full_res, place, None); } pm.draw_pixmap(0, 0, both.as_ref(), &PixmapPaint { opacity, ..PixmapPaint::default() }, Transform::identity(), None); } else { @@ -273,7 +279,7 @@ pub(crate) fn draw_in_place( } } else { for part in &parts { - draw(pm, part, &own_style, Some(stats), view, opacity, full_res, place); + draw(pm, part, &own_style, Some(stats), view, opacity, full_res, place, None); } } match (pending, failed) { @@ -382,6 +388,7 @@ fn draw_with( full_res: bool, place: Place, threads: usize, + light: Option<&[u8]>, ) { // On high-density screens, compute at logical-pixel resolution and scale up (unless asked // for full resolution, as exports are): a quarter of the work at 2×. @@ -470,6 +477,13 @@ fn draw_with( RasterRenderer::ShadedRelief { azimuth, altitude, z_factor, .. } => Some((azimuth, altitude, z_factor)), _ => None, }; + // Cast shadows darken the direct light by their strength, the ambient light left as it is. + let shadow = match style.renderer { + RasterRenderer::ShadedRelief { shadow, .. } if shadow > 0.0 => { + light.filter(|g| g.len() == r.width as usize * r.height as usize).map(|g| (g, shadow.min(1.0))) + } + _ => None, + }; // Blending neighbours would invent values that aren't classes or palette entries. let resampling = match style.renderer { RasterRenderer::UniqueValues { .. } | RasterRenderer::Colormap => Resampling::Nearest, @@ -498,6 +512,7 @@ fn draw_with( bands: &bands, data: bands.iter().map(|b| r.bands.get(*b).map(|b| b.data.as_slice())).collect(), relief, + shadow, resampling, alpha_band, alpha_max: rustgis_data::raster::alpha_max(&r.data_type), @@ -619,6 +634,8 @@ struct Pass1<'a> { /// The renderer's bands' values. data: Vec>, relief: Option<(f64, f64, f64)>, + /// The light cast shadows leave on each cell, and how dark they are drawn (0 to 1). + shadow: Option<(&'a [u8], f64)>, resampling: Resampling, alpha_band: Option, /// The alpha band's opaque value (its pixel type's: 65535 for 16 bits). @@ -726,6 +743,12 @@ impl Pass1<'_> { } if let Some(s) = shade.get_mut(i) { *s = hillshade(&z, self.cell.0, self.cell.1, az, alt, zf); + if let Some((grid, strength)) = self.shadow + && let Some(lit) = grid.get(ri as usize * r.width as usize + ci as usize) + { + let left = 1.0 - strength * (1.0 - f64::from(*lit) / 255.0); + *s = (f64::from(*s) * left).round().clamp(0.0, 255.0) as u8; + } } } } @@ -855,7 +878,7 @@ mod tests { let data = [0.0, 1_000_000.0, 2_000_000.0, 3_000_000.0].repeat(18); let r = Raster::new("regional relief", 4, 18, vec![data], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); let mut style = RasterStyle::default_for(&r); - style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 270.0, altitude: 45.0, z_factor: 1.0 }; + style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 270.0, altitude: 45.0, z_factor: 1.0, shadow: 0.0 }; style.resampling = Resampling::Nearest; let view = View { width: 1.0, @@ -865,7 +888,7 @@ mod tests { sky: false, }; let mut pm = Pixmap::new(1, 1).unwrap(); - draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), None); let z = [0.0, 0.0, 1_000_000.0, 0.0, 0.0, 1_000_000.0, 0.0, 0.0, 1_000_000.0]; let (cell_x, cell_y) = r.cell_size_m(); let shade = hillshade(&z, cell_x, cell_y, 270.0, 45.0, 1.0); @@ -874,6 +897,48 @@ mod tests { assert_eq!([actual.red(), actual.green(), actual.blue(), actual.alpha()], expected); } + /// Cast shadows darken the hillshade by their strength, the ambient light left; a shadow of 0 + /// draws today's pixels, with a light grid or without. + #[test] + fn cast_shadows_darken_the_direct_light_by_their_strength() { + let gt = GeoTransform { origin_x: 0.0, origin_y: 90.0, pixel_width: 10.0, pixel_height: -10.0 }; + let data = [0.0, 1_000_000.0, 2_000_000.0, 3_000_000.0].repeat(18); + let r = Raster::new("relief", 4, 18, vec![data], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); + let view = View { + width: 1.0, + height: 1.0, + pixels_per_point: 1.0, + camera: Camera { center: lonlat_to_merc(Coord::new(5.0, 0.0)), res: 1000.0, bearing: 0.0, pitch: 0.0 }, + sky: false, + }; + let z = [0.0, 0.0, 1_000_000.0, 0.0, 0.0, 1_000_000.0, 0.0, 0.0, 1_000_000.0]; + let (cell_x, cell_y) = r.cell_size_m(); + let lit = hillshade(&z, cell_x, cell_y, 270.0, 45.0, 1.0); + let dark = vec![0u8; 4 * 18]; + let drawn = |shadow: f64, light: Option<&[u8]>| { + let mut style = RasterStyle::default_for(&r); + style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 270.0, altitude: 45.0, z_factor: 1.0, shadow }; + style.resampling = Resampling::Nearest; + let mut pm = Pixmap::new(1, 1).unwrap(); + draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), light); + let p = pm.pixel(0, 0).unwrap(); + let want = |shade: u8| Colorizer::new(&style, &r, None).color(&[0.0], Some(shade)).unwrap(); + ([p.red(), p.green(), p.blue(), p.alpha()], want(lit), want(0), want((f64::from(lit) * 0.5).round() as u8)) + }; + let none = Some(dark.as_slice()); + // Without shadows, today's pixels, a grid or not; with them, the direct light by their strength. + for (shadow, light, which) in [(0.0, None, 0), (0.0, none, 0), (1.0, None, 0), (1.0, none, 1), (0.5, none, 2)] { + let (pixel, lit, unlit, half) = drawn(shadow, light); + assert_eq!(pixel, [lit, unlit, half][which], "shadow {shadow}, grid {}", light.is_some()); + } + // In full shadow the relief keeps its ambient light (a quarter of its colour), not black. + let (pixel, _, _, _) = drawn(1.0, none); + assert_eq!(pixel, [64, 64, 64, 255]); + // A grid of another size isn't read. + let (pixel, lit, _, _) = drawn(1.0, Some(&dark[..10])); + assert_eq!(pixel, lit); + } + /// A 0–360° grid seen across its seam: the part in view is two strips, one at each end of /// the grid, not the whole width. #[test] @@ -914,10 +979,11 @@ mod tests { let data: Vec = (0..36 * 18).map(|i| elevations[(i % 36 + shift) % 36]).collect(); let r = Raster::new("relief", 36, 18, vec![data], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap(); let mut style = RasterStyle::default_for(&r); - style.renderer = RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 270.0, altitude: 45.0, z_factor: 1.0 }; + style.renderer = + RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 270.0, altitude: 45.0, z_factor: 1.0, shadow: 0.0 }; style.resampling = Resampling::Nearest; let mut pm = Pixmap::new(80, 40).unwrap(); - draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), None); pm }; let seam = render(0.0, 0); @@ -942,7 +1008,7 @@ mod tests { style.resampling = Resampling::Bilinear; let draw_it = |style: &RasterStyle, stats: Option<&[BandStats]>| { let mut pm = Pixmap::new(200, 200).unwrap(); - draw(&mut pm, &r, style, stats, &view, 1.0, false, flat); + draw(&mut pm, &r, style, stats, &view, 1.0, false, flat, None); pm }; let px = |pm: &Pixmap, x: u32| pm.pixel(x, 100).map(|p| (p.alpha(), p.red())).unwrap_or((0, 0)); @@ -986,7 +1052,7 @@ mod tests { let camera = Camera { center: lonlat_to_merc(Coord::new(-81.0, 42.0)), res: 2000.0, bearing: 0.0, pitch: 0.0 }; let view = View { width: 200.0, height: 200.0, pixels_per_point: 1.0, camera, sky: false }; let mut pm = Pixmap::new(200, 200).unwrap(); - draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), None); let alpha = |x: u32, y: u32| pm.pixel(x, y).map(|p| p.alpha()).unwrap_or(0); assert_eq!(alpha(100, 100), 255, "the centre is covered"); assert_eq!(alpha(2, 2), 0, "the corner of the view is outside the raster"); @@ -1000,16 +1066,16 @@ mod tests { "rgb" => RasterRenderer::Rgb { red: 0, green: 0, blue: 0 }, "classify" => rustgis_map::raster::classify(&r, 0, 5, Default::default(), Default::default()), "unique" => rustgis_map::raster::unique_values(&r, 0, Default::default()), - _ => RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 45.0, z_factor: 1.0 }, + _ => RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 45.0, z_factor: 1.0, shadow: 0.0 }, }; s.dra = true; s.resampling = Resampling::Bilinear; - draw(&mut pm, &r, &s, None, &view, 0.5, false, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut pm, &r, &s, None, &view, 0.5, false, Place::Flat(&Flat::Mercator, "mercator"), None); } // High-density screens draw at logical resolution, scaled up. let hi = View { pixels_per_point: 2.0, ..view }; let mut pm2 = Pixmap::new(400, 400).unwrap(); - draw(&mut pm2, &r, &style, None, &hi, 1.0, false, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut pm2, &r, &style, None, &hi, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), None); assert_eq!(pm2.pixel(200, 200).map(|p| p.alpha()), Some(255)); assert_eq!(pm2.pixel(4, 4).map(|p| p.alpha()), Some(0)); // Spread over threads, every pixel comes out as drawn on one, for each renderer. @@ -1018,19 +1084,21 @@ mod tests { let mut s = style.clone(); s.renderer = match kind { "rgb" => RasterRenderer::Rgb { red: 0, green: 0, blue: 0 }, - "shadedRelief" => RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 45.0, z_factor: 1.0 }, + "shadedRelief" => { + RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 45.0, z_factor: 1.0, shadow: 0.0 } + } _ => s.renderer, }; let mut one = Pixmap::new(420, 300).unwrap(); let mut many = Pixmap::new(420, 300).unwrap(); - draw_with(&mut one, &r, &s, None, &wide, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), 1); - draw_with(&mut many, &r, &s, None, &wide, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), 7); + draw_with(&mut one, &r, &s, None, &wide, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), 1, None); + draw_with(&mut many, &r, &s, None, &wide, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), 7, None); assert!(one.data() == many.data(), "{kind}"); assert!(one.pixels().iter().any(|p| p.alpha() == 255), "{kind} draws"); } let far = View { width: 3.0, height: 1.0, pixels_per_point: 2.0, camera: Camera::world(), sky: false }; let mut tiny = Pixmap::new(6, 2).unwrap(); - draw(&mut tiny, &r, &style, None, &far, 1.0, true, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut tiny, &r, &style, None, &far, 1.0, true, Place::Flat(&Flat::Mercator, "mercator"), None); } /// #1792: a projected raster scaled up to a high-density screen, its reprojection grid and @@ -1054,8 +1122,8 @@ mod tests { let mut one = Pixmap::new(size.0, size.1).unwrap(); one.fill(tiny_skia::Color::from_rgba8(20, 120, 40, 255)); let mut many = one.clone(); - draw_with(&mut one, &r, &style, None, &view, opacity, false, Place::Flat(&Flat::Mercator, "mercator"), 1); - draw_with(&mut many, &r, &style, None, &view, opacity, false, Place::Flat(&Flat::Mercator, "mercator"), 7); + draw_with(&mut one, &r, &style, None, &view, opacity, false, Place::Flat(&Flat::Mercator, "mercator"), 1, None); + draw_with(&mut many, &r, &style, None, &view, opacity, false, Place::Flat(&Flat::Mercator, "mercator"), 7, None); assert!(one.data() == many.data(), "res {res} ppp {ppp} opacity {opacity} {resampling:?}"); assert!(one.pixels().iter().any(|p| p.green() != 120), "res {res} ppp {ppp}: the raster is drawn"); } @@ -1074,7 +1142,7 @@ mod tests { let camera = Camera { center: Coord::new(0.0, 0.0), res: 100_000.0, bearing: 0.0, pitch: 0.0 }; let view = View { width: 400.0, height: 200.0, pixels_per_point: 1.0, camera, sky: false }; let mut pm = Pixmap::new(400, 200).unwrap(); - draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator")); + draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&Flat::Mercator, "mercator"), None); let at = |lon: f64| { let (x, y) = view.to_screen(lonlat_to_merc(Coord::new(lon, 10.0))); pm.pixel(x as u32, y as u32).map(|p| (p.alpha(), p.red())).unwrap_or((0, 0)) @@ -1101,7 +1169,7 @@ mod tests { let camera = Camera { center: Coord::new(0.0, 0.0), res: 100_000.0, bearing: 0.0, pitch: 0.0 }; let view = View { width: 400.0, height: 200.0, pixels_per_point: 1.0, camera, sky: false }; let mut pm = Pixmap::new(400, 200).unwrap(); - draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&flat, "robinson +lon_0=150")); + draw(&mut pm, &r, &style, None, &view, 1.0, false, Place::Flat(&flat, "robinson +lon_0=150"), None); let screen = |lon: f64| view.to_screen(flat.forward(Coord::new(lon, 10.0)).unwrap()); let red = |x: f64, y: f64| pm.pixel(x as u32, y as u32).map(|p| (p.alpha(), p.red())).unwrap_or((0, 0)); let ((xa, y), (xb, _)) = (screen(170.5), screen(-170.5)); diff --git a/crates/render/src/raster_export.rs b/crates/render/src/raster_export.rs index b23c50d8b8..c39a4e39b0 100644 --- a/crates/render/src/raster_export.rs +++ b/crates/render/src/raster_export.rs @@ -59,6 +59,21 @@ pub fn export(layer: &RasterLayer, min_zoom: u8, max_zoom: u8, opacity: f32) -> ranges.push((z, x0, x1, y0, y1)); } let stats = layer.masked_stats(); + // Its cast shadows, waited for; ones that can't be drawn leave the archive unwritten, as a + // part drawn from less than it needs does. + let light = match layer.cast_shadows(true, (u64::MAX, u64::MAX), || {}) { + rustgis_map::raster::CastShadows::Ready(grid) => Some(grid), + rustgis_map::raster::CastShadows::Unavailable(why) => return Err(format!("{}: {why}, so the archive isn't written", r.name)), + // Only when the run is cancelled: nothing is written. + rustgis_map::raster::CastShadows::Pending => { + return Err(format!( + "{}: its cast shadows weren't worked out (the export was cancelled), so the archive isn't written", + r.name + )); + } + rustgis_map::raster::CastShadows::None => None, + }; + let light = light.as_deref().map(Vec::as_slice); // A raster read in place waits for its tiles natively, two minutes at most in all. let deadline = web_time::Instant::now() + rustgis_data::raster::IN_PLACE_WAIT; let mut tiles = Vec::new(); @@ -80,7 +95,7 @@ pub fn export(layer: &RasterLayer, min_zoom: u8, max_zoom: u8, opacity: f32) -> let mut idle = 0; loop { let drawn_at = crate::rustgis_tiles::cache::generation(); - match raster::draw_in_place(&mut image, address, r, &layer.style, stats, &view, opacity, true, place) { + match raster::draw_in_place(&mut image, address, r, &layer.style, stats, &view, opacity, true, place, light) { Ok(false) => break, Ok(true) => {} // Drawn from less than the tile needs: not written in its place. @@ -106,7 +121,7 @@ pub fn export(layer: &RasterLayer, min_zoom: u8, max_zoom: u8, opacity: f32) -> image.fill(tiny_skia::Color::TRANSPARENT); } } - None => raster::draw(&mut image, r, &layer.style, stats, &view, opacity, true, place), + None => raster::draw(&mut image, r, &layer.style, stats, &view, opacity, true, place, light), } if image.data().as_chunks::<4>().0.iter().all(|pixel| pixel[3] == 0) { continue; @@ -174,6 +189,37 @@ mod tests { let layer = RasterLayer::in_place(overview, "http://127.0.0.1:9/gone.tif"); let e = export(&layer, 2, 2, 1.0).err().unwrap_or_else(|| panic!("an archive of the overview")); assert!(e.contains("the archive isn't written"), "{e}"); + // With cast shadows, which only the whole image could have: refused for them, and said. + let mut layer = layer; + layer.style.renderer = + rustgis_map::RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 30.0, z_factor: 1.0, shadow: 1.0 }; + let e = export(&layer, 2, 2, 1.0).err().unwrap_or_else(|| panic!("an archive without its shadows")); + assert!(e.contains("cast shadows") && e.contains("read in place"), "{e}"); + } + + /// An export cancelled while it waits for a layer's cast shadows writes nothing, and says why. + #[test] + #[allow(clippy::panic)] + fn a_cancelled_wait_for_cast_shadows_writes_no_archive() { + struct Cancelled; + impl rustgis_data::progress::Probe for Cancelled { + fn cancelled(&self) -> bool { + true + } + fn begin(&self, _: u64) {} + fn advance(&self, _: u64) {} + } + let n = 1500u32; + let data: Vec = (0..n * n).map(|i| (i % n) as f32 * 0.01).collect(); + let gt = GeoTransform { origin_x: 0.0, origin_y: 1.0, pixel_width: 1.0 / f64::from(n), pixel_height: -1.0 / f64::from(n) }; + let raster = + Raster::new("plain", n, n, vec![data], gt, Crs::LonLat, None, ColorHint::Gray, "Float32").unwrap_or_else(|e| panic!("{e}")); + let mut layer = RasterLayer::from_path(raster, "plain.tif"); + layer.style.renderer = + rustgis_map::RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 90.0, altitude: 2.0, z_factor: 1.0, shadow: 1.0 }; + let _cancelled = rustgis_data::progress::install(Some(std::sync::Arc::new(Cancelled))); + let e = export(&layer, 0, 0, 1.0).err().unwrap_or_else(|| panic!("an archive without its shadows")); + assert!(e.contains("cancelled") && e.contains("isn't written"), "{e}"); } #[test] diff --git a/crates/ui-egui/src/docpanes.rs b/crates/ui-egui/src/docpanes.rs index 16255f98fe..d27d62eedd 100644 --- a/crates/ui-egui/src/docpanes.rs +++ b/crates/ui-egui/src/docpanes.rs @@ -275,16 +275,21 @@ struct PageText { fn preview(app: &mut RustGisApp, ui: &mut Ui, i: usize, t: &Tokens) { let key = format!("{i}#{}#{}", app.docs.page, app.session.revision); - if app.docs.preview.as_ref().is_none_or(|p| p.0 != key) { + if app.docs.preview.as_ref().is_none_or(|p| !crate::layoutview::preview_current(&p.0, &key)) { let (s, page) = (&mut app.session, app.docs.page); - let drawn = + let (drawn, said) = rustgis_engine::render::shadows_said(|| { std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| rustgis_engine::cmd::presentation::draw_page(s, i, page, 30.0))) - .unwrap_or_else(|_| Err("the preview failed unexpectedly".into())); + .unwrap_or_else(|_| Err("the preview failed unexpectedly".into())) + }); + crate::layoutview::say_frame_shadows(app, &said); let tex = drawn.map(|pm| { let img = egui::ColorImage::from_rgba_premultiplied([pm.width() as usize, pm.height() as usize], pm.data()); ui.ctx().load_texture("presentation_preview", img, egui::TextureOptions::LINEAR) }); - app.docs.preview = Some((key, tex)); + app.docs.preview = Some((crate::layoutview::preview_key(&key, &said), tex)); + } + if app.docs.preview.as_ref().is_some_and(|p| crate::layoutview::preview_waits(&p.0)) { + ui.ctx().request_repaint_after(std::time::Duration::from_millis(250)); } let tex = match &app.docs.preview { Some((_, Ok(tex))) => tex, diff --git a/crates/ui-egui/src/layoutview.rs b/crates/ui-egui/src/layoutview.rs index cb6c2b6894..9121c6f7ae 100644 --- a/crates/ui-egui/src/layoutview.rs +++ b/crates/ui-egui/src/layoutview.rs @@ -55,6 +55,34 @@ type Box4 = (f64, f64, f64, f64); /// wait ends once the page is whole. const FRAMES_REDRAW_S: f64 = 0.25; +/// Says, once each, why frames drawn for a page or a preview drew layers without their cast +/// shadows (see [`rustgis_engine::render::shadows_said`]), as the map view says them. +pub(crate) fn say_frame_shadows(app: &mut RustGisApp, said: &rustgis_engine::render::ShadowsSaid) { + for e in &said.notices { + if app.map.tile_errors.insert(e.clone()) { + app.session.warn(e.clone()); + } + } +} + +/// The key a preview drawn for `base` is kept under: with the tile cache's generation when its +/// frames drew without cast shadows still being worked out (on the interface's thread, which +/// doesn't wait for them), so it is drawn again as they land (see [`preview_current`]). +pub(crate) fn preview_key(base: &str, said: &rustgis_engine::render::ShadowsSaid) -> String { + if said.to_come { format!("{base}#shadows@{}", rustgis_engine::render::rustgis_tiles::cache::generation()) } else { base.to_string() } +} + +/// Whether a preview kept under `kept` (see [`preview_key`]) is still the one `base` asks for: +/// a preview waiting for cast shadows is drawn again once anything lands. +pub(crate) fn preview_current(kept: &str, base: &str) -> bool { + kept == base || kept == format!("{base}#shadows@{}", rustgis_engine::render::rustgis_tiles::cache::generation()) +} + +/// Whether a preview kept under `kept` waits for cast shadows: the frame is asked again shortly. +pub(crate) fn preview_waits(kept: &str) -> bool { + kept.contains("#shadows@") +} + /// What has landed so far: the tile cache's generation (tiles, styles, legend pictures, a raster's /// parts read in place) and the background reads' (a streamed layer's features, a source or /// raster opened by its address). Each goes up as something lands. @@ -697,17 +725,21 @@ pub fn show(app: &mut RustGisApp, ui: &mut Ui) { }); if (app.layout.key != Some(key) || due) && size[0] > 2 && size[1] > 2 { let info = page_info(app, li); - if let Ok((pm, frames_pending)) = rustgis_engine::render::layout::render_pending(&layout, &mut app.session.project.maps, dpi, &info) - { + let (drawn, said) = rustgis_engine::render::shadows_said(|| { + rustgis_engine::render::layout::render_pending(&layout, &mut app.session.project.maps, dpi, &info) + }); + if let Ok((pm, frames_pending)) = drawn { let img = egui::ColorImage::from_rgba_premultiplied([pm.width() as usize, pm.height() as usize], pm.data()); match &mut app.layout.texture { Some(tex) => tex.set(img, egui::TextureOptions::LINEAR), None => app.layout.texture = Some(ui.ctx().load_texture("layout", img, egui::TextureOptions::LINEAR)), } app.layout.key = Some(key); - // Natively the page waited for them already: drawn again, it would wait again. + // Natively the page waited for them already: drawn again, it would wait again. Cast + // shadows still being worked out weren't waited for: drawn again as they land. let web = cfg!(target_arch = "wasm32"); - let frames = web && frames_pending; + let frames = (web && frames_pending) || said.to_come; + say_frame_shadows(app, &said); // Waiting for the frames draws it again anyway: the legends are asked about once // they are whole. let legends = web && !frames && rustgis_engine::render::layout::legends_pending(&layout, &app.session.project.maps); diff --git a/crates/ui-egui/src/lib.rs b/crates/ui-egui/src/lib.rs index d0220e2688..e4388c787e 100644 --- a/crates/ui-egui/src/lib.rs +++ b/crates/ui-egui/src/lib.rs @@ -5265,6 +5265,10 @@ impl RustGisApp { /// Per-frame work that doesn't draw (theme, fonts, files that arrived). pub fn logic(&mut self, ctx: &egui::Context) { let _diagnostics = self.session.diagnostics.enter(); + // What this thread draws (an image, a print, a page, a preview, an agent's snapshot) + // never waits for cast shadows still being worked out: it says they were (Never hold the + // window). Exports drawn off it wait for them. + rustgis_engine::render::on_the_interface_thread(); // A pass egui asks to repeat is the same frame: `ui` sets the delay once, from the first pass. if ctx.current_pass_index() == 0 { self.frame_start = Some(web_time::Instant::now()); @@ -5606,6 +5610,8 @@ impl RustGisApp { pub fn ui(&mut self, ui: &mut egui::Ui) { let _diagnostics = self.session.diagnostics.enter(); + // See `logic`. + rustgis_engine::render::on_the_interface_thread(); let ctx = ui.ctx().clone(); // Fonts installed by `logic` take effect on the next frame. if self.fonts_frames < 2 { diff --git a/crates/ui-egui/src/mapview.rs b/crates/ui-egui/src/mapview.rs index 6100c20eb0..d055668340 100644 --- a/crates/ui-egui/src/mapview.rs +++ b/crates/ui-egui/src/mapview.rs @@ -337,8 +337,9 @@ pub struct MapView { pictures: crate::popupmedia::Pictures, /// The tile layers' credits, from the last render. attribution: Vec, - /// Tile layer errors already reported. - tile_errors: std::collections::HashSet, + /// Tile layer errors, and why layers were drawn without their cast shadows (in the map or + /// the Layout view), already reported. + pub(crate) tile_errors: std::collections::HashSet, /// When the map last rendered (seconds). last_render: f64, /// The map drawn flat and laid over the globe while it moves. @@ -907,6 +908,7 @@ fn main_view(app: &mut RustGisApp, ui: &mut Ui, t: &Tokens) { && cam.pitch == 0.0 && app.map.live_rev == Some(app.session.revision) && !reads_in_place(app.session.map()) + && !casts_shadows(app.session.map()) { key.tiles = 0; } else if fetches_tiles(app.session.map()) { @@ -1526,12 +1528,20 @@ fn drape_state(app: &RustGisApp) -> (crate::globe_drape::DrapeKey, u64) { (key, tiles) } -/// Whether the map draws from web tiles (its tile layers, or elevation tiles for its terrain): -/// tiles arriving draw it again. +/// Whether the map draws from web tiles (its tile layers, or elevation tiles for its terrain), or +/// draws cast shadows worked out off the frame: tiles or shadows arriving (both move the tile +/// cache's generation) draw it again. fn fetches_tiles(m: &rustgis_engine::map::Map) -> bool { !m.tiles.is_empty() || m.view.terrain.as_ref().is_some_and(|t| matches!(t.source, rustgis_engine::map::view::TerrainSource::Tiles { .. })) || reads_in_place(m) + || casts_shadows(m) +} + +/// Whether a visible raster layer of the map is drawn with cast shadows, which land after the +/// frame that asks for them (see `RasterLayer::cast_shadows`). +fn casts_shadows(m: &rustgis_engine::map::Map) -> bool { + m.layers.iter().any(|l| l.visible && l.raster.as_ref().is_some_and(|r| r.casts_shadows())) } /// Whether the map has raster layers read in place: the part in view arrives a tile at a time, @@ -4869,6 +4879,31 @@ mod picture_tests { mod tests { use super::*; + /// A map whose relief casts shadows is drawn again as the tile cache's generation moves, which + /// the shadows' landing moves, though it fetches no tiles: a map of a DEM alone gets its + /// shadows without being moved. Without shadows (or hidden) it isn't. + #[test] + fn a_relief_casting_shadows_is_drawn_again_as_they_land() { + use rustgis_engine::data::raster::{ColorHint, Crs, GeoTransform, Raster}; + use rustgis_engine::map::{Map, RasterLayer, RasterRenderer}; + let gt = GeoTransform { origin_x: 0.0, origin_y: 0.0, pixel_width: 30.0, pixel_height: -30.0 }; + let r = Raster::new("dem", 4, 4, vec![vec![0.0; 16]], gt, Crs::WebMercator, None, ColorHint::Gray, "Float32").unwrap(); + let mut map = Map::new("Relief"); + let id = map.add_raster("dem", RasterLayer::from_path(r, "dem.tif")); + let relief = |shadow| RasterRenderer::ShadedRelief { band: 0, ramp: None, azimuth: 315.0, altitude: 30.0, z_factor: 1.0, shadow }; + let set = |map: &mut Map, shadow: f64, visible: bool| { + let l = map.layer_mut(id).unwrap(); + l.visible = visible; + l.raster.as_mut().unwrap().style.renderer = relief(shadow); + }; + set(&mut map, 0.0, true); + assert!(!fetches_tiles(&map)); + set(&mut map, 0.8, true); + assert!(fetches_tiles(&map)); + set(&mut map, 0.8, false); + assert!(!fetches_tiles(&map)); + } + /// Natural Earth is credited only where its world outline is drawn: not on a blank basemap or /// another body, whose sources are still credited. #[test] diff --git a/crates/ui-egui/src/panes.rs b/crates/ui-egui/src/panes.rs index c72c86035d..4c485d2c32 100644 --- a/crates/ui-egui/src/panes.rs +++ b/crates/ui-egui/src/panes.rs @@ -6675,21 +6675,24 @@ fn raster_symbology(app: &mut RustGisApp, ui: &mut Ui, l: &Layer, t: &Tokens) { RasterRenderer::Colormap => { ui.label(egui::RichText::new(tl!("Colors from the raster's own color table.")).size(11.5).color(t.text_dim)); } - RasterRenderer::ShadedRelief { band, ramp, azimuth, altitude, z_factor } => { - let (az, alt, zf, rp) = (*azimuth, *altitude, *z_factor, ramp.as_ref().map(|r| r.name().to_string())); - let relief = move |band: usize, az: f64, alt: f64, zf: f64| { - let mut p = json!({"type": "shadedRelief", "band": band + 1, "azimuth": az, "altitude": alt, "zFactor": zf}); + RasterRenderer::ShadedRelief { band, ramp, azimuth, altitude, z_factor, shadow } => { + let (az, alt, zf, sh, rp) = (*azimuth, *altitude, *z_factor, *shadow, ramp.as_ref().map(|r| r.name().to_string())); + let relief = move |band: usize, az: f64, alt: f64, zf: f64, sh: f64| { + let mut p = json!({"type": "shadedRelief", "band": band + 1, "azimuth": az, "altitude": alt, "zFactor": zf, "shadow": sh}); match &rp { Some(r) => p["ramp"] = json!(r), None => p["grey"] = json!(true), } p }; - band_combo(app, ui, "Band", *band, &|i| ("raster.symbology".into(), relief(i, az, alt, zf))); + band_combo(app, ui, "Band", *band, &|i| ("raster.symbology".into(), relief(i, az, alt, zf, sh))); egui::Grid::new("relief").num_columns(2).spacing(vec2(10.0, 4.0)).show(ui, |ui| { - for (label, v, range, speed, which) in - [("Azimuth", az, 0.0..=360.0, 1.0, 0), ("Altitude", alt, 0.0..=90.0, 0.5, 1), ("Z factor", zf, 0.001..=1000.0, 0.01, 2)] - { + for (label, v, range, speed, which) in [ + ("Azimuth", az, 0.0..=360.0, 1.0, 0), + ("Altitude", alt, 0.0..=90.0, 0.5, 1), + ("Z factor", zf, 0.001..=1000.0, 0.01, 2), + ("Cast shadows", sh, 0.0..=1.0, 0.01, 3), + ] { let input_label = ui.label(tl!(label)); let mut x = v; // Kept across a drag until it is let go (#607). @@ -6697,20 +6700,26 @@ fn raster_symbology(app: &mut RustGisApp, ui: &mut Ui, l: &Layer, t: &Tokens) { let r = ui .add(egui::DragValue::new(&mut x).update_while_editing(false).range(range).speed(speed).max_decimals(3)) .labelled_by(input_label.id); + let r = if which == 3 { + r.on_hover_text(tl!("How dark the shadows the terrain casts are, from 0 (none) to 1, for the sun set above")) + } else { + r + }; if drag.settled(ui, &r, &mut x) && x != v { - let (a, b, c) = match which { - 0 => (x, alt, zf), - 1 => (az, x, zf), - _ => (az, alt, x), + let (a, b, c, d) = match which { + 0 => (x, alt, zf, sh), + 1 => (az, x, zf, sh), + 2 => (az, alt, x, sh), + _ => (az, alt, zf, x), }; - let _ = app.run("raster.symbology", relief(*band, a, b, c)); + let _ = app.run("raster.symbology", relief(*band, a, b, c, d)); } ui.end_row(); } }); let mut tint = ramp.is_some(); if ui.checkbox(&mut tint, tl!("Tint by elevation")).changed() { - let mut p = relief(*band, az, alt, zf); + let mut p = relief(*band, az, alt, zf, sh); if tint { p["ramp"] = json!("Terrain"); p["grey"] = json!(false); diff --git a/crates/ui-egui/src/reportpane.rs b/crates/ui-egui/src/reportpane.rs index c45a092c8f..140a1d7c29 100644 --- a/crates/ui-egui/src/reportpane.rs +++ b/crates/ui-egui/src/reportpane.rs @@ -309,7 +309,7 @@ fn preview(app: &mut RustGisApp, ui: &mut Ui, i: usize, t: &Tokens) { // Any change to the report, its data or the selection runs a command, which moves the // revision on. let key = format!("{i}#{}#{}", app.reports.page, app.session.revision); - if app.reports.preview.as_ref().is_none_or(|p| p.0 != key) { + if app.reports.preview.as_ref().is_none_or(|p| !crate::layoutview::preview_current(&p.0, &key)) { app.reports.preview = None; let built_for = (i, app.session.revision); if app.reports.built.as_ref().is_none_or(|b| b.0 != built_for) { @@ -328,19 +328,23 @@ fn preview(app: &mut RustGisApp, ui: &mut Ui, i: usize, t: &Tokens) { None => return, }; let (s, page) = (&mut app.session, app.reports.page); - let drawn = std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| -> Result<_, String> { - let page = page.min(pages.len().saturating_sub(1)); - let (pm, _, _) = rustgis_engine::render::report::draw_page(doc, pages, page, 60.0, &s.project.layouts, &mut s.project.maps)?; - Ok((pm, page, pages.len())) - })) - .unwrap_or_else(|_| Err("the preview failed unexpectedly".into())); + let (drawn, said) = rustgis_engine::render::shadows_said(|| { + std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| -> Result<_, String> { + let page = page.min(pages.len().saturating_sub(1)); + let (pm, _, _) = + rustgis_engine::render::report::draw_page(doc, pages, page, 60.0, &s.project.layouts, &mut s.project.maps)?; + Ok((pm, page, pages.len())) + })) + .unwrap_or_else(|_| Err("the preview failed unexpectedly".into())) + }); + crate::layoutview::say_frame_shadows(app, &said); match drawn { Ok((pm, page, total)) => { app.reports.page = page; let img = egui::ColorImage::from_rgba_premultiplied([pm.width() as usize, pm.height() as usize], pm.data()); let tex = ui.ctx().load_texture("report_preview", img, egui::TextureOptions::LINEAR); let key = format!("{i}#{page}#{}", app.session.revision); - app.reports.preview = Some((key, tex, total)); + app.reports.preview = Some((crate::layoutview::preview_key(&key, &said), tex, total)); } Err(e) => { ui.label(egui::RichText::new(e).small().color(Color32::from_rgb(0xC0, 0x30, 0x30))); @@ -348,6 +352,9 @@ fn preview(app: &mut RustGisApp, ui: &mut Ui, i: usize, t: &Tokens) { } } } + if app.reports.preview.as_ref().is_some_and(|p| crate::layoutview::preview_waits(&p.0)) { + ui.ctx().request_repaint_after(std::time::Duration::from_millis(250)); + } let Some((_, tex, total)) = &app.reports.preview else { return }; let (tex, total) = (tex.clone(), *total); let size = tex.size_vec2(); diff --git a/docs/user-guide/data.md b/docs/user-guide/data.md index 34b856ccef..03817bb71f 100644 --- a/docs/user-guide/data.md +++ b/docs/user-guide/data.md @@ -1173,6 +1173,23 @@ With a raster layer selected in Layers, the **Style** and **Data** tabs show its | Style › Enhancement | Brightness, contrast, gamma | | Data | Raster information (size, bands, statistics, coordinate system) and Export Raster (GeoTIFF) | +**Cast shadows**, on a Shaded Relief layer (`raster.symbology` `"shadow"`, 0 to 1), darkens the +slopes the terrain hides from the sun as well as those facing away from it: a valley behind a ridge +is in shadow, with a soft edge. Only the direct light is darkened: a slope in full shadow keeps the +relief's ambient light. 0, the default, draws the relief as before. The shadows are worked out once +for the layer's sun, band and Z factor, off the map's frame on the desktop: the map and the Layout +view draw without them for the moment that takes (under a second for a few million cells on a +multi-core computer, several seconds on one thread; a sun under about 5° traces much farther, some +seconds on a multi-core computer and twenty or so on one thread), then with them. An export +waits for them; what the window draws at once (Copy Map or Copy Layout to the clipboard, printing, +the presentation and report previews, an agent's snapshot) doesn't, and says the layers it drew +without them. +The strength is drawn, not worked out, so changing it is immediate. The browser works them out for +rasters of at most 500,000 cells, and a cloud-optimised GeoTIFF read in place has none unless its +whole image is held: either way the layer is drawn without them, and a notice says so. Terrain +outside the raster casts nothing on it, and a grid spanning 0 to 360° casts nothing across its +seam. + **Masking**, at the foot of the Symbology pane (`raster.mask`), hides pixel values from view without changing the data: values to draw as no data (a background of 0 or −9999 the file doesn't flag, QA flags, land cover classes such as `0, 254, 255`), and values outside, or inside, a range. The