[Feature]: Intersect, Identity, Union and Near tools #959

Before you start

• I searched the existing issues and the roadmap and did not find a duplicate request.

What problem does this solve?

RustGIS has Clip and Erase but no overlay that keeps the attributes of both layers. Everyday questions need one:

• Which parcels are in the floodplain, and by how much? Clip keeps the parcel pieces inside the floodplain but drops the floodplain's attributes (zone, flood depth). Spatial Join keeps attributes but not the pieces, so the area inside can't be measured.
• Split a road network by jurisdiction, so each stretch carries the road's attributes and the jurisdiction's.
• Land use by zoning district: every area covered by either layer, with both sets of attributes where they overlap.
• How far is each address from the nearest hydrant, and which hydrant is it? Spatial Join's Closest (feat(analysis): Spatial Join by centre, largest overlap, closest and distance, with merge rules #864) can now answer this as a join, but there is no simple tool that adds the distance and the nearest feature's id to a layer.

Tabulate intersection, also on the roadmap, waits on intersect ("once intersect exists").

Proposed solution

Four tools in rustgis-analysis, listed in the roadmap's Solid ground theme as "Overlay tools beside Clip and Erase: intersect, union, identity and near (open)". Each writes a new layer, as Clip and Erase do.

Intersect (intersect; input, overlay, output): for each input feature and each overlay polygon it overlaps, one feature for the overlapping part, with the input's attributes followed by the overlay's. The input can be points, lines or polygons; the overlay is polygons; the output keeps the input's geometry type. Parts that only touch along a boundary (or at a point, for polygons) are left out.

Identity (identity; same parameters): Intersect's features, plus each input feature's remainder outside every overlay polygon, with empty overlay attributes. Every part of the input is kept (once for each overlay polygon it lies in, where overlay polygons overlap each other).

Union (union; same parameters, both polygon layers): Identity, plus each overlay polygon's remainder outside every input polygon, with empty input attributes.

Shared behaviour for the three:

• Selections are honoured in both layers, as Clip does.
• An overlay field whose name the input already has gets a suffix (name_2), as Spatial Join does.
• Overlaps between features of the same layer are not split. The docs will say so; that would need a "planarize" step and can come later.
• The overlay runs in the same space as Clip and Erase (geo's boolean operations on Web Mercator coordinates), so the results line up with theirs.

Near (near; input, near, optional distance and units as Spatial Join takes them, output): a copy of the input with near_fid (the nearest feature's OID, as the attribute table shows it) and near_dist (in units), plus near_x/near_y, the nearest point on that feature in longitude/latitude. Distances are on the WGS 84 ellipsoid between the features' nearest points, using the same measure as Spatial Join's Closest. With a distance, features with nothing within range get empty values. Ties keep the near layer's order.

Ribbon and panes: all four show in the Tools pane (under Analysis › Overlay, and Analysis › Proximity for Near) and in Feature Analysis. Intersect joins Clip and Erase in the Analyze gallery, with an icon drawn in code.

Crates: rustgis-analysis (the tools), rustgis-engine (the Feature Analysis list), rustgis-ui-egui (gallery entry and icon), plus the user guide, ROADMAP.md and GEOLIBRE_PARITY.md. No new dependency, data-model or command changes.

Delivery, as three pull requests:

1. Intersect.
2. Identity and Union, which reuse Intersect's pieces plus Erase's remainders.
3. Near.

Tests: GEOS reference cases for each overlay added to the #916 corpus (parcels and zones, a line crossing polygons, holes and multipart polygons, boundary-only contact); attribute order and name collisions; selections; Near with and without a search distance, against points, lines and polygons, with ties and across the antimeridian; and the existing hostile_params_never_panic coverage for the new tools.

I'd like to take this.

Estimated scope

Medium: a broader feature that is feasible in a reasonable timeframe

Alternatives considered

• Spatial Join, then Clip. Spatial Join with Intersects followed by Clip comes close to Intersect for one overlay polygon per feature. A feature crossing two zones is clipped against both and gets one zone's attributes, so the pieces and attributes don't match.
• A single overlay tool with an operation choice (intersect, identity, union). That is fewer tool ids, but each operation has different geometry rules (Union needs polygons on both sides), and separate tools match how Clip and Erase are listed and searched.
• Near as a Spatial Join option only. Closest with a distance field already covers the join form. Near is the simpler, more familiar tool for adding a distance, and it can report the nearest point, which a join doesn't.