diff --git a/crates/analysis/src/tools.rs b/crates/analysis/src/tools.rs index 59773e0339..0e32bb9a6f 100644 --- a/crates/analysis/src/tools.rs +++ b/crates/analysis/src/tools.rs @@ -1281,6 +1281,50 @@ fn result(ds: Dataset, msg: String) -> Result { Ok(ToolResult { output: Output::Layer(ds), messages: vec![msg] }) } +/// A geometry's polygons, or none when it has no polygon to give: an empty polygon, or a point +/// or line, which a polygon layer can hold (Minimum Bounding Geometry writes its flat hulls so). +fn polygon_of(g: &Geometry) -> Option> { + to_multipolygon(g).filter(|mp| mp.0.iter().any(|p| !p.exterior().0.is_empty())) +} + +/// The error when `tool`, whose output would be empty, left out every feature of `layer` it was +/// given, `left` saying how many of each kind. +fn nothing_covered(tool: &str, layer: &str, left: LeftOut) -> String { + let what = match (left.no_polygon, left.no_area) { + (_, 0) => NO_POLYGON.to_string(), + (0, _) => NO_AREA.to_string(), + (a, b) => format!("{a} with no polygon ({NO_POLYGON}), {b} with no area"), + }; + format!("{tool}: none of the {} feature(s) of '{layer}' covers anything: {what}", left.no_polygon + left.no_area) +} + +/// What a feature [`overlay_zones`] leaves out holds: no geometry, or a geometry [`polygon_of`] +/// gives nothing for. +const NO_POLYGON: &str = "no geometry, a point or line, or an empty polygon"; + +/// What a feature whose polygons, unioned, come to nothing holds: Clip leaves out such a mask, and +/// the overlay tools such a feature of several parts (see [`ZoneUse`]). +const NO_AREA: &str = "a polygon with no area"; + +/// How many features of a mask or overlay layer Clip or an overlay tool left out: those with no +/// polygon ([`NO_POLYGON`]), and those whose polygons have no area ([`NO_AREA`]). +#[derive(Clone, Copy, Default)] +struct LeftOut { + no_polygon: usize, + no_area: usize, +} + +impl LeftOut { + /// `tool`'s notices for them, one for each kind there are any of, `layer` being their layer. + fn notes(self, tool: &str, layer: &str) -> Vec { + [(self.no_polygon, NO_POLYGON), (self.no_area, NO_AREA)] + .into_iter() + .filter(|&(n, _)| n > 0) + .map(|(n, what)| format!("{tool}: {n} feature(s) of '{layer}' left out, covering nothing: {what}")) + .collect() + } +} + /// A copy of a feature's attributes for an output with the same schema. fn copy_schema(ds: &Dataset, name: String, g: GeometryType) -> Dataset { Dataset::new(name, g, ds.fields.clone()) @@ -1577,7 +1621,9 @@ fn part(g: &Geometry, mask: &MultiPolygon, inside: bool) -> Option Result { let ds = input(inp, p, "input")?; let clip_ds = input(inp, p, "clip")?; @@ -1585,22 +1631,32 @@ fn clip(inp: &dyn Inputs, p: &Json) -> Result { return Err(format!("'{}' is not a polygon layer", clip_ds.name)); } let mut masks = Vec::new(); - let mask_rows = rows(inp, p, "clip", clip_ds); + // Mask features that clip nothing, left out and counted: no polygon, or one with no area. + let mut left = LeftOut::default(); + let mask_rows = each_once(rows(inp, p, "clip", clip_ds)); crate::control::begin(mask_rows.len()); for (done, r) in mask_rows.into_iter().enumerate() { // Each mask is a union: Cancel is looked at, and progress counted, before each. crate::control::check()?; crate::control::reached(done); - let Some(m) = clip_ds.features.get(r).and_then(|f| f.geometry.as_ref()).and_then(to_multipolygon) else { continue }; + let Some(m) = clip_ds.features.get(r).and_then(|f| f.geometry.as_ref()).and_then(polygon_of) else { + left.no_polygon += 1; + continue; + }; let ext = merc_extent(&m); // Union even one polygon: collapsed rings have no filled area. Keep the original // bounds too: rounding an edge must not hide a line the boolean overlay clips to it. let mask = union_all(m.0.iter()); let ext = ext.union(&merc_extent(&mask)); - if !mask.0.is_empty() { + if mask.0.is_empty() { + left.no_area += 1; + } else { masks.push((mask, ext)); } } + if masks.is_empty() && left.no_polygon + left.no_area > 0 { + return Err(nothing_covered("Clip", &clip_ds.name, left)); + } let index = ExtentIndex::new(masks.iter().map(|(_, ext)| *ext)); // The masks reaching each pole: a point at one is in them at any longitude (#1033). let at_poles = AtPoles::new(masks.iter().map(|(m, _)| plane_poles(m))); @@ -1654,7 +1710,9 @@ fn clip(inp: &dyn Inputs, p: &Json) -> Result { } } let n = out.features.len(); - result(out, format!("Clip: {n} features kept")) + let mut r = result(out, format!("Clip: {n} features kept"))?; + r.messages.extend(left.notes("Clip", &clip_ds.name)); + Ok(r) } /// Erase: each input feature's part outside every erase polygon, as [`outside`] gives it (a point @@ -1672,7 +1730,7 @@ fn erase_on(inp: &dyn Inputs, p: &Json, threads: Option) -> Result) -> Result) -> MultiPolygon { if poly.0.len() > 1 { union_all(poly.0.iter()) } else { poly.orient(Direction::Default) } } -/// The polygon layer of an overlay tool's parameter `k` (`overlay`, `erase`, `update`, `split`), -/// which must be polygons, and its (selected) features with geometry as [`Zone`]s, in order. -fn overlay_zones<'a>(inp: &'a dyn Inputs, p: &Json, k: &str) -> Result<(&'a Dataset, Vec), String> { - overlay_zones_on(inp, p, k, None) +/// How an overlay tool uses its overlay polygons, for [`overlay_zones`]. +#[derive(Clone, Copy, PartialEq, Eq)] +enum ZoneUse { + /// Its output comes only from inside them (Intersect, Split): with none left, it would be + /// empty, an error. + Inside, + /// It cuts by them (Erase, Identity, Union, Symmetrical Difference); with none left, the input + /// comes out as it is. + Cuts, + /// It writes each as it is (Update): one whose parts union to nothing is kept, as it is. + AsIs, +} + +/// What one overlay polygon's feature makes of its layer in [`overlay_zones_on`]: a zone, or the +/// reason it is left out. +enum ZoneMade { + Zone(Zone), + NoPolygon, + NoArea, +} + +/// The polygon layer of `tool`'s parameter `k` (`overlay`, `erase`, `update`, `split`), which +/// must be polygons, its (selected) features with a polygon as [`Zone`]s, in order, each once, and +/// how many it left out, for the tool's notices: those with no polygon ([`NO_POLYGON`]), and, +/// unless `use_` is [`ZoneUse::AsIs`], those of several parts whose union is empty ([`NO_AREA`]), +/// as they cover nothing. A polygon of one part is only oriented, its edges kept exactly, so one +/// with no area stays a zone, as it always has. +fn overlay_zones<'a>( + inp: &'a dyn Inputs, + p: &Json, + k: &str, + tool: &str, + use_: ZoneUse, +) -> Result<(&'a Dataset, Vec, LeftOut), String> { + overlay_zones_on(inp, p, k, tool, use_, None) } /// [`overlay_zones`] on `threads` threads (by the number of zones when `None`). A zone of several /// parts is a union: each zone is made on its own, on several threads when there are many /// (#1252), and they come back in order, as on one thread; Cancel is looked at, and progress /// counted, between zones. -fn overlay_zones_on<'a>(inp: &'a dyn Inputs, p: &Json, k: &str, threads: Option) -> Result<(&'a Dataset, Vec), String> { +fn overlay_zones_on<'a>( + inp: &'a dyn Inputs, + p: &Json, + k: &str, + tool: &str, + use_: ZoneUse, + threads: Option, +) -> Result<(&'a Dataset, Vec, LeftOut), String> { let ov = input(inp, p, k)?; if ov.geometry_type != GeometryType::Polygon { return Err(format!("'{}' is not a polygon layer", ov.name)); } - let zone_rows = rows(inp, p, k, ov); + let zone_rows = each_once(rows(inp, p, k, ov)); crate::control::begin(zone_rows.len()); let threads = threads.unwrap_or_else(|| crate::parallel::threads_for(zone_rows.len(), PARALLEL_FEATURES)); let made = crate::parallel::try_map_on( @@ -1748,14 +1846,29 @@ fn overlay_zones_on<'a>(inp: &'a dyn Inputs, p: &Json, k: &str, threads: Option< threads, || (), |_, _, &row| { - let zone = ov.features.get(row).and_then(|f| f.geometry.as_ref()).and_then(|g| { - let poly = to_multipolygon(g).map(mask_of)?; - Some(Zone { row, ext: g.extent(), poly }) - }); - Ok::<_, String>(zone) + let Some((g, poly)) = ov.features.get(row).and_then(|f| f.geometry.as_ref()).and_then(|g| Some((g, polygon_of(g)?))) else { + return Ok::<_, String>(ZoneMade::NoPolygon); + }; + let poly = mask_of(poly); + if poly.0.is_empty() && use_ != ZoneUse::AsIs { + return Ok(ZoneMade::NoArea); + } + Ok(ZoneMade::Zone(Zone { row, ext: g.extent(), poly })) }, )?; - Ok((ov, made.into_iter().flatten().collect())) + let mut zones = Vec::with_capacity(made.len()); + let mut left = LeftOut::default(); + for m in made { + match m { + ZoneMade::Zone(z) => zones.push(z), + ZoneMade::NoPolygon => left.no_polygon += 1, + ZoneMade::NoArea => left.no_area += 1, + } + } + if use_ == ZoneUse::Inside && zones.is_empty() && left.no_polygon + left.no_area > 0 { + return Err(nothing_covered(tool, &ov.name, left)); + } + Ok((ov, zones, left)) } /// An overlay tool's output layer: the input's fields, then the overlay's, an overlay field whose @@ -1932,7 +2045,8 @@ fn overlay_on(inp: &dyn Inputs, p: &Json, op: Overlay, threads: Option) - if op.keeps_overlay_rest() && ds.geometry_type != GeometryType::Polygon { return Err(format!("'{}' is not a polygon layer", ds.name)); } - let (ov, zones) = overlay_zones_on(inp, p, "overlay", threads)?; + let use_ = if matches!(op, Overlay::Intersect) { ZoneUse::Inside } else { ZoneUse::Cuts }; + let (ov, zones, left_out) = overlay_zones_on(inp, p, "overlay", op.name(), use_, threads)?; let index = ExtentIndex::new(zones.iter().map(|z| z.ext)); let at_poles = AtPoles::new(zones.iter().map(|z| poles(&z.ext))); let mut out = overlay_schema(ds, ov, out_name(p, format!("{}_{}", ds.name, op.suffix())), ds.geometry_type); @@ -2006,7 +2120,9 @@ fn overlay_on(inp: &dyn Inputs, p: &Json, op: Overlay, threads: Option) - } } let n = out.features.len(); - result(out, format!("{}: {n} features", op.name())) + let mut r = result(out, format!("{}: {n} features", op.name()))?; + r.messages.extend(left_out.notes(op.name(), &ov.name)); + Ok(r) } /// Intersect: see [`overlay`]. @@ -2067,9 +2183,10 @@ fn converted(v: &Value, ty: FieldType) -> Value { /// update polygon as it is, its values copied into the input's fields of the same name (matched /// exactly, else ignoring case; converted by [`converted`]), the input's other fields empty. The /// output has the input's fields only. Input features without geometry, and those no update -/// polygon overlaps, are kept as they are; update features without geometry are left out, and -/// update polygons that overlap each other each come out whole. An input field that no update -/// field matches exactly, but two match ignoring case, is an error rather than a guess. +/// polygon overlaps, are kept as they are; update features without a polygon ([`NO_POLYGON`]) are +/// left out, saying how many, and update polygons that overlap each other each come out whole. An +/// input field that no update field matches exactly, but two match ignoring case, is an error +/// rather than a guess. fn update(inp: &dyn Inputs, p: &Json) -> Result { update_on(inp, p, None) } @@ -2081,7 +2198,7 @@ fn update_on(inp: &dyn Inputs, p: &Json, threads: Option) -> Result) -> Result String { /// [`MAX_SPLIT_NAME`] characters, control characters dropped); one with no value is named by its /// id, as is one whose value is blank once its control characters are dropped. A name the map /// already has gets a number when the layer is added. Layers left with no features are left out; -/// selections in both layers count. +/// selections in both layers count. Split features left out by [`overlay_zones`] are counted; with +/// none left, it's an error. fn split(inp: &dyn Inputs, p: &Json) -> Result { let ds = input(inp, p, "input")?; if ds.geometry_type == GeometryType::None { return Err(format!("'{}' has no geometry", ds.name)); } - let (sp, zones) = overlay_zones(inp, p, "split")?; - // A field name, or none; anything else is an error, not one layer per polygon. + // A field name, or none; anything else is an error, not one layer per polygon. Checked before + // the split polygons are read, so a wrong field isn't hidden behind them. let field = match p.get("field") { None | Some(Json::Null) => None, Some(Json::String(name)) if name.trim().is_empty() => None, - Some(Json::String(name)) => Some(find_field_case_insensitive(sp, name.trim())?), + Some(Json::String(name)) => Some(find_field_case_insensitive(input(inp, p, "split")?, name.trim())?), Some(other) => return Err(format!("Split Field must be a field name, not {other}")), }; + let (sp, zones, left_out) = overlay_zones(inp, p, "split", "Split", ZoneUse::Inside)?; // The split polygons of each layer, in the order their first polygon comes, keyed by the exact // value, so values that would be named alike stay apart. A layer named by a value and one named // by an id are kept apart even when the two read the same. @@ -2243,7 +2364,7 @@ fn split(inp: &dyn Inputs, p: &Json) -> Result { let areas = if empty == 1 { "split area" } else { "split areas" }; msg = format!("{msg} ({empty} {areas} held no features)"); } - Ok(ToolResult { output: Output::Layers(layers), messages: vec![msg] }) + Ok(ToolResult { output: Output::Layers(layers), messages: std::iter::once(msg).chain(left_out.notes("Split", &sp.name)).collect() }) } /// Dissolve: one feature for each value of the dissolve field (one for all without it), the union @@ -2273,8 +2394,7 @@ fn dissolve(inp: &dyn Inputs, p: &Json) -> Result { for (done, r) in input_rows.into_iter().enumerate() { crate::control::check()?; crate::control::reached(done); - let polygon = ds.features.get(r).and_then(|f| f.geometry.as_ref()).and_then(to_multipolygon); - let Some(mp) = polygon.filter(|mp| mp.0.iter().any(|p| !p.exterior().0.is_empty())) else { + let Some(mp) = ds.features.get(r).and_then(|f| f.geometry.as_ref()).and_then(polygon_of) else { not_polygons += 1; continue; }; @@ -2480,9 +2600,9 @@ fn convex_hull(inp: &dyn Inputs, p: &Json) -> Result { GeometryType::Point => "the output is a point layer".to_string(), GeometryType::Polyline => "the output is a line layer".to_string(), // Points and lines, every hull flat: a polygon layer, there being no one kind. - _ if flat >= n => "they are kept in the output's polygon layer, points and lines together, where Dissolve leaves them out and as Clip masks they cover nothing".to_string(), + _ if flat >= n => "they are kept in the output's polygon layer, points and lines together, where Dissolve leaves them out, as do Clip and the overlay tools from a mask or overlay layer, saying how many".to_string(), _ => format!( - "they are kept in the output's polygon layer, among its {} polygon(s), where Dissolve leaves them out and as Clip masks they cover nothing", + "they are kept in the output's polygon layer, among its {} polygon(s), where Dissolve leaves them out, as do Clip and the overlay tools from a mask or overlay layer, saying how many", n.saturating_sub(flat) ), }; @@ -6934,6 +7054,164 @@ mod tests { assert!(e.contains("none of the 2 feature(s) has a polygon"), "{e}"); } + /// Clip and the overlay tools say how many mask or overlay features they left out as covering + /// nothing: a point and a line in a polygon layer (as Minimum Bounding Geometry's flat hulls + /// are), empty polygons and a feature without geometry, and a feature of two parts with no + /// area (all but Update, which writes it as it is); Clip also a single polygon with no area. + /// Those change nothing in the output; a layer of polygons, a bowtie among them, says nothing + /// of the kind; only the selected features are counted, each once; and leaving out every one + /// is an error where the output would be empty. + #[test] + fn overlay_tools_count_mask_features_that_cover_nothing() { + struct Sel(Map, Option>); + impl Inputs for Sel { + fn dataset(&self, layer: &str) -> Option<&Dataset> { + self.0.dataset(layer) + } + fn selection(&self, layer: &str) -> &[usize] { + match &self.1 { + Some(rows) if layer == "masks" => rows, + _ => &[], + } + } + } + // On one parallel: a straight line on the analysis plane too. + let flat = |y: f64| vec![Coord::new(5.0, y), Coord::new(6.0, y), Coord::new(7.0, y), Coord::new(5.0, y)]; + // Two triangles meeting at a point, wound opposite ways: its signed area sums to zero. + let bowtie = || { + let c = Coord::new; + Geometry::Polygon(vec![vec![vec![c(5.0, 0.0), c(7.0, 2.0), c(7.0, 0.0), c(5.0, 2.0), c(5.0, 0.0)]]]) + }; + let polys = || { + let mut polys = Dataset::new("polys", GeometryType::Polygon, vec![Field::new("a", FieldType::Integer)]); + polys.push(Some(sq(0.0, 0.0, 2.0)), vec![Value::Int(1)]); + polys.push(Some(sq(5.0, 0.0, 2.0)), vec![Value::Int(2)]); + polys + }; + let run = |tool: &str, key: &str, masks: Dataset, selected: Option>| { + let m = Sel(Map(HashMap::from([("polys".to_string(), polys()), ("masks".to_string(), masks)])), selected); + let res = crate::run(tool, &m, &serde_json::json!({"input": "polys", key: "masks"}))?; + let notes: Vec = res.messages.iter().filter(|m| m.contains("covering nothing")).cloned().collect(); + let shapes: Vec> = match res.output { + Output::Layer(ds) => ds.features.into_iter().map(|f| f.geometry).collect(), + Output::Layers(layers) => layers + .into_iter() + .flat_map(|l| match l { + OutputLayer::Vector(ds) => ds.features.into_iter().map(|f| f.geometry).collect(), + _ => Vec::new(), + }) + .collect(), + _ => panic!("{tool}: a layer"), + }; + Ok::<_, String>((shapes, notes)) + }; + let masks = |extra: bool, tool: &str| { + let mut masks = Dataset::new("masks", GeometryType::Polygon, vec![Field::new("b", FieldType::Integer)]); + masks.push(Some(sq(1.0, 1.0, 2.0)), vec![Value::Int(10)]); + if extra { + // Over the second input polygon, where a mask would change the output. + masks.push(Some(Geometry::Point(Coord::new(6.0, 1.0))), vec![Value::Int(11)]); + masks.push(Some(Geometry::Line(vec![vec![Coord::new(5.0, 1.0), Coord::new(7.0, 1.0)]])), vec![Value::Int(12)]); + masks.push(Some(Geometry::Polygon(vec![])), vec![Value::Int(13)]); + masks.push(Some(Geometry::Polygon(vec![vec![]])), vec![Value::Int(14)]); + masks.push(None, vec![Value::Int(15)]); + // Update writes an update polygon as it is, so this one would change its output; + // the others leave it out, counted. + if tool != "update" { + // Two polygons, each a ring on a line. + masks.push(Some(Geometry::Polygon(vec![vec![flat(1.0)], vec![flat(1.5)]])), vec![Value::Int(16)]); + } + if tool == "clip" { + masks.push(Some(Geometry::Polygon(vec![vec![flat(1.0)]])), vec![Value::Int(17)]); + } + } + masks + }; + let tools = [ + ("clip", "clip", "Clip"), + ("erase", "erase", "Erase"), + ("intersect", "overlay", "Intersect"), + ("identity", "overlay", "Identity"), + ("union", "overlay", "Union"), + ("symmetricalDifference", "overlay", "Symmetrical Difference"), + ("update", "update", "Update"), + ("split", "split", "Split"), + ]; + let note = |name: &str, n: usize, what: &str| format!("{name}: {n} feature(s) of 'masks' left out, covering nothing: {what}"); + for (tool, key, name) in tools { + let (clean, none) = run(tool, key, masks(false, tool), None).unwrap_or_else(|e| panic!("{tool}: {e}")); + assert!(none.is_empty(), "{tool}: {none:?}"); + let (shapes, notes) = run(tool, key, masks(true, tool), None).unwrap_or_else(|e| panic!("{tool}: {e}")); + assert_eq!(shapes, clean, "{tool}: the features covering nothing change nothing"); + let expected = match tool { + "clip" => vec![note(name, 5, NO_POLYGON), note(name, 2, NO_AREA)], + "update" => vec![note(name, 5, NO_POLYGON)], + _ => vec![note(name, 5, NO_POLYGON), note(name, 1, NO_AREA)], + }; + assert_eq!(notes, expected, "{tool}"); + // The square, and the point and line twice over, selected: those two are counted once. + let (shapes, notes) = run(tool, key, masks(true, tool), Some(vec![0, 1, 2, 2, 1])).unwrap_or_else(|e| panic!("{tool}: {e}")); + assert_eq!(shapes, clean, "{tool}: selected"); + assert_eq!(notes, [note(name, 2, NO_POLYGON)], "{tool}: selected"); + // A bowtie covers ground: kept, without a word. + let mut bowties = Dataset::new("masks", GeometryType::Polygon, vec![Field::new("b", FieldType::Integer)]); + bowties.push(Some(bowtie()), vec![Value::Int(20)]); + let (_, notes) = run(tool, key, bowties, None).unwrap_or_else(|e| panic!("{tool}: {e}")); + assert!(notes.is_empty(), "{tool}: {notes:?}"); + // The point alone, and a feature without geometry: an error where nothing would come + // out (Clip, Intersect, Split); the input, as it comes out with no mask, elsewhere. + let mut points = Dataset::new("masks", GeometryType::Polygon, vec![Field::new("b", FieldType::Integer)]); + points.push(Some(Geometry::Point(Coord::new(6.0, 1.0))), vec![Value::Int(11)]); + points.push(None, vec![Value::Int(15)]); + match (tool, run(tool, key, points, None)) { + ("clip" | "intersect" | "split", res) => assert_eq!( + res.err().unwrap_or_default(), + format!("{name}: none of the 2 feature(s) of 'masks' covers anything: {NO_POLYGON}"), + "{tool}" + ), + (_, res) => assert_eq!(res.map(|(_, notes)| notes), Ok(vec![note(name, 2, NO_POLYGON)]), "{tool}"), + } + // One ring on a line alone: Clip's mask, unioned, is nothing; the overlay tools keep + // it as the polygon it is, as before. + let mut flats = Dataset::new("masks", GeometryType::Polygon, vec![Field::new("b", FieldType::Integer)]); + flats.push(Some(Geometry::Polygon(vec![vec![flat(1.0)]])), vec![Value::Int(17)]); + match (tool, run(tool, key, flats, None)) { + ("clip", res) => assert_eq!( + res.err().unwrap_or_default(), + format!("Clip: none of the 1 feature(s) of 'masks' covers anything: {NO_AREA}") + ), + (_, res) => assert_eq!(res.map(|(_, notes)| notes), Ok(vec![]), "{tool}"), + } + // A feature of two rings on a line alone: left out, an error where nothing would come + // out; Update writes it as it is. + let mut twos = Dataset::new("masks", GeometryType::Polygon, vec![Field::new("b", FieldType::Integer)]); + twos.push(Some(Geometry::Polygon(vec![vec![flat(1.0)], vec![flat(1.5)]])), vec![Value::Int(16)]); + match (tool, run(tool, key, twos, None)) { + ("clip" | "intersect" | "split", res) => assert_eq!( + res.err().unwrap_or_default(), + format!("{name}: none of the 1 feature(s) of 'masks' covers anything: {NO_AREA}"), + "{tool}" + ), + ("update", res) => assert_eq!(res.map(|(_, notes)| notes), Ok(vec![]), "{tool}"), + (_, res) => assert_eq!(res.map(|(_, notes)| notes), Ok(vec![note(name, 1, NO_AREA)]), "{tool}"), + } + } + // A wrong Split field is said before the split polygons are looked at. + let mut points = Dataset::new("masks", GeometryType::Polygon, vec![]); + points.push(Some(Geometry::Point(Coord::new(6.0, 1.0))), vec![]); + let m = Map(HashMap::from([("polys".to_string(), polys()), ("masks".to_string(), points)])); + let e = crate::run("split", &m, &serde_json::json!({"input": "polys", "split": "masks", "field": 42})).err().unwrap_or_default(); + assert_eq!(e, "Split Field must be a field name, not 42"); + // Clip's error says how many of each kind. + let mut both = Dataset::new("masks", GeometryType::Polygon, vec![]); + both.push(None, vec![]); + both.push(Some(Geometry::Polygon(vec![vec![flat(1.0)]])), vec![]); + assert_eq!( + run("clip", "clip", both, None).err().unwrap_or_default(), + format!("Clip: none of the 2 feature(s) of 'masks' covers anything: 1 with no polygon ({NO_POLYGON}), 1 with no area") + ); + } + /// Dissolve's groups, found by their keys' hash: in the order first met, −0 with 0, each NaN /// on its own (it equals no value), and a number apart from the same text and a whole number /// apart from the same fraction. @@ -10245,6 +10523,8 @@ mod tests { .is_some() ); for selection in [None, Some((0..80).filter(|i| i % 3 != 0).collect()), Some(vec![82]), Some(vec![83])] { + // Mask 83 has no geometry. + let without_geometry = selection == Some(vec![83]); let mut selected = HashMap::new(); if let Some(s) = selection { selected.insert("masks".into(), s); @@ -10252,6 +10532,12 @@ mod tests { } let inp = Selected(indexed_overlay_inputs(), selected); let p = serde_json::json!({"input":"features", "clip":"masks"}); + if without_geometry { + // Nothing to clip by: an error saying why, not an empty layer. + let e = crate::run("clip", &inp, &p).err().unwrap_or_default(); + assert!(e.contains("none of the 1 feature(s) of 'masks' covers anything"), "{e}"); + continue; + } let masks = &inp.0.0["masks"]; let polys: Vec<_> = rows(&inp, &p, "clip", masks) .iter() diff --git a/docs/user-guide/analysis.md b/docs/user-guide/analysis.md index eae4f74460..3c1288fab4 100644 --- a/docs/user-guide/analysis.md +++ b/docs/user-guide/analysis.md @@ -560,8 +560,8 @@ overlay must be polygons. An overlay field whose name the input already has gets Overlapping features within one layer are not split against each other. Like Clip and Erase, the overlay works on the map's Web Mercator coordinates, so the parts' edges are straight on the map within ±85.05° (beyond it, see **Near the poles** above). -Selections in both layers are honoured. To measure each part, run Calculate Geometry Attributes on -the result: +Selections in both layers are honoured, and a row selected twice is used once, so its parts come out +once. To measure each part, run Calculate Geometry Attributes on the result: ```text gp.run={"tool":"intersect","params":{"input":"parcels","overlay":"floodplain","output":"parcels_in_floodplain"}} @@ -611,6 +611,15 @@ field), empty ones included. Selections in both layers are honoured. gp.run={"tool":"split","params":{"input":"roads","split":"districts","field":"name"}} ``` +Clip, Erase, Intersect, Identity, Union, Symmetrical Difference, Update and Split leave out a +feature of the clip, erase, overlay, update or split layer with no polygon, and say how many: one +without geometry, a point or line in the polygon layer (as Minimum Bounding Geometry's flat hulls +are), or an empty polygon. Clip also leaves out a mask whose polygons, unioned, have no area, and +the others a feature of several parts that, unioned, come to nothing (Update writes it as it is), +saying how many. When none of the features of that layer is left, Clip, Intersect and Split, whose +result would be empty, stop with an error. In all of them, a feature selected twice in that layer is +used once. + **Near** (`near`) copies `input` and adds, for each feature, the nearest feature of `near`: its OID as the attribute table shows it (`near_fid`), the distance to it (`near_dist`, in `units`, Kilometers by default) and the point on it nearest the input feature (`near_x` and `near_y`, in @@ -782,10 +791,10 @@ writing no hull for it; if every feature is skipped, it is an error. A latitude taken as that pole. A hull with no area is written as what it is: a point for points in one place, or the line between the two farthest apart for points on one straight line on the map. The layer is a point or line layer when every hull is one, and the tool says so; otherwise it's a polygon layer -holding any points and lines among its polygons. Dissolve leaves those out, saying how many; as -Clip masks they cover nothing; a Shapefile export leaves them out, saying how many; and a -GeoPackage export keeps them in a column that holds any kind of geometry. It says how many of -each. +holding any points and lines among its polygons. Dissolve leaves those out, saying how many; so +do Clip and the overlay tools when the layer is their mask or overlay; a Shapefile export leaves +them out, saying how many; and a GeoPackage export keeps them in a column that holds any kind of +geometry. The tool says how many hulls have no area. **Dissolve** (`dissolve`) merges the polygons sharing a value of `field` into one feature for each value, or all of them into one without a field. Each feature has the value and `count`, the