gh-50 Add spatial predicates API with fixed-scale support

Add FloatPredicateOverlay and FloatRelate trait for efficient spatial
relationship testing (intersects, touches, within, covers, disjoint).

Features:
- PredicateOverlay for integer-space predicate evaluation with early-exit
- FloatPredicateOverlay wrapper handling float-to-int conversion
- FloatRelate trait for ergonomic predicate methods on ShapeResource types
- FixedScaleFloatRelate trait for fixed-scale precision predicates
- with_adapter() and with_adapter_custom() constructors for custom adapters
- with_subj_and_clip_fixed_scale() for fixed-scale precision

Author: bretttully

iOverlay/README.md

@@ -23,6 +23,7 @@ iOverlay powers polygon boolean operations in [geo](https://github.com/georust/g
 - [Boolean Operations](#boolean-operations)
   - [Simple Example](#simple-example)
   - [Overlay Rules](#overlay-rules)
+- [Spatial Predicates](#spatial-predicates)
 - [Custom Point Type Support](#custom-point-type-support)
 - [Slicing & Clipping](#slicing--clipping)
   - [Slicing a Polygon with a Polyline](#slicing-a-polygon-with-a-polyline)
@@ -49,6 +50,7 @@ iOverlay powers polygon boolean operations in [geo](https://github.com/georust/g
 ## Features
 
 - **Boolean Operations**: union, intersection, difference, and exclusion.
+- **Spatial Predicates**: `intersects`, `disjoint`, `interiors_intersect`, `touches`, `within`, `covers` with early-exit optimization.
 - **Polyline Operations**: clip and slice.
 - **Polygons**: with holes, self-intersections, and multiple contours.
 - **Simplification**: removes degenerate vertices and merges collinear edges.
@@ -183,6 +185,78 @@ The `overlay` function returns a `Vec<Shapes>`:
 |---------|---------------|----------------------|----------------|--------------------|----------------|
 | <img src="readme/ab.svg" alt="AB" style="width:100px;"> | <img src="readme/union.svg" alt="Union" style="width:100px;"> | <img src="readme/intersection.svg" alt="Intersection" style="width:100px;"> | <img src="readme/difference_ab.svg" alt="Difference" style="width:100px;"> | <img src="readme/difference_ba.svg" alt="Inverse Difference" style="width:100px;"> | <img src="readme/exclusion.svg" alt="Exclusion" style="width:100px;"> |
 
+&nbsp;
+## Spatial Predicates
+
+When you only need to know *whether* two shapes have a spatial relationship—not compute their intersection geometry—use spatial predicates for better performance:
+
+```rust
+use i_overlay::float::relate::FloatRelate;
+
+let outer = vec![[0.0, 0.0], [0.0, 20.0], [20.0, 20.0], [20.0, 0.0]];
+let inner = vec![[5.0, 5.0], [5.0, 15.0], [15.0, 15.0], [15.0, 5.0]];
+let adjacent = vec![[20.0, 0.0], [20.0, 10.0], [30.0, 10.0], [30.0, 0.0]];
+let distant = vec![[100.0, 100.0], [100.0, 110.0], [110.0, 110.0], [110.0, 100.0]];
+
+// intersects: shapes share any point (interior or boundary)
+assert!(outer.intersects(&inner));
+assert!(outer.intersects(&adjacent));  // edge contact counts
+
+// disjoint: shapes share no points (negation of intersects)
+assert!(outer.disjoint(&distant));
+
+// interiors_intersect: interiors overlap (stricter than intersects)
+assert!(outer.interiors_intersect(&inner));
+assert!(!outer.interiors_intersect(&adjacent));  // edge-only contact
+
+// touches: boundaries intersect but interiors don't
+assert!(outer.touches(&adjacent));
+assert!(!outer.touches(&inner));  // interiors overlap
+
+// within: first shape completely inside second
+assert!(inner.within(&outer));
+assert!(!outer.within(&inner));
+
+// covers: first shape completely contains second
+assert!(outer.covers(&inner));
+assert!(!inner.covers(&outer));
+```
+
+These methods use early-exit optimization, returning as soon as the predicate can be determined without processing remaining segments.
+
+### Fixed-Scale Predicates
+
+For consistent precision across operations, use `FixedScaleFloatRelate`:
+
+```rust
+use i_overlay::float::scale::FixedScaleFloatRelate;
+
+let square = vec![[0.0, 0.0], [0.0, 10.0], [10.0, 10.0], [10.0, 0.0]];
+let other = vec![[5.0, 5.0], [5.0, 15.0], [15.0, 15.0], [15.0, 5.0]];
+
+let scale = 1000.0;  // or 1.0 / grid_size
+
+let result = square.intersects_with_fixed_scale(&other, scale);
+assert!(result.unwrap());
+```
+
+For more control, use `FloatPredicateOverlay` directly with a custom adapter:
+
+```rust
+use i_overlay::float::relate::FloatPredicateOverlay;
+use i_float::adapter::FloatPointAdapter;
+
+let square = vec![[0.0, 0.0], [0.0, 10.0], [10.0, 10.0], [10.0, 0.0]];
+let clip = vec![[5.0, 5.0], [5.0, 15.0], [15.0, 15.0], [15.0, 5.0]];
+
+// Use fixed-scale constructor
+let mut overlay = FloatPredicateOverlay::with_subj_and_clip_fixed_scale(
+    &square, &clip, 1000.0
+).unwrap();
+
+assert!(overlay.intersects());
+```
+
 &nbsp;
 ## Custom Point Type Support
 `iOverlay` allows users to define custom point types, as long as they implement the `FloatPointCompatible` trait.

iOverlay/src/build/boolean.rs

@@ -1,4 +1,6 @@
-use crate::build::builder::{FillStrategy, GraphBuilder, InclusionFilterStrategy};
+use crate::build::builder::{
+    FillHandler, FillStrategy, GraphBuilder, InclusionFilterStrategy, sweep_with_handler,
+};
 use crate::core::extract::VisitState;
 use crate::core::fill_rule::FillRule;
 use crate::core::graph::OverlayGraph;
@@ -8,14 +10,18 @@ use crate::core::link::OverlayLinkFilter;
 use crate::core::overlay::IntOverlayOptions;
 use crate::core::overlay_rule::OverlayRule;
 use crate::core::solver::Solver;
+use crate::geom::v_segment::VSegment;
 use crate::segm::boolean::ShapeCountBoolean;
 use crate::segm::segment::{
     ALL, BOTH_BOTTOM, BOTH_TOP, CLIP_BOTH, CLIP_BOTTOM, CLIP_TOP, SUBJ_BOTH, SUBJ_BOTTOM, SUBJ_TOP, Segment,
     SegmentFill,
 };
 use crate::segm::winding::WindingCount;
+use crate::util::log::Int;
 use alloc::vec::Vec;
 use i_shape::util::reserve::Reserve;
+use i_tree::key::list::KeyExpList;
+use i_tree::key::tree::KeyExpTree;
 
 impl GraphBuilder<ShapeCountBoolean, OverlayNode> {
     #[inline]
@@ -79,6 +85,54 @@ impl GraphBuilder<ShapeCountBoolean, OverlayNode> {
     }
 }
 
+/// Sweeps segments with a fill handler, dispatching on fill rule.
+/// This is used by PredicateOverlay for early-exit predicate evaluation.
+#[inline]
+pub(crate) fn sweep_boolean<H: FillHandler>(
+    fill_rule: FillRule,
+    solver: &Solver,
+    segments: &[Segment<ShapeCountBoolean>],
+    handler: H,
+) -> H::Output {
+    let count = segments.len();
+    if solver.is_list_fill(segments) {
+        let capacity = count.log2_sqrt().max(4) * 2;
+        let mut list: KeyExpList<VSegment, i32, ShapeCountBoolean> = KeyExpList::new(capacity);
+        sweep_boolean_with_scan(fill_rule, &mut list, segments, handler)
+    } else {
+        let capacity = count.log2_sqrt().max(8);
+        let mut tree: KeyExpTree<VSegment, i32, ShapeCountBoolean> = KeyExpTree::new(capacity);
+        sweep_boolean_with_scan(fill_rule, &mut tree, segments, handler)
+    }
+}
+
+#[inline]
+fn sweep_boolean_with_scan<S, H>(
+    fill_rule: FillRule,
+    scan: &mut S,
+    segments: &[Segment<ShapeCountBoolean>],
+    handler: H,
+) -> H::Output
+where
+    S: i_tree::key::exp::KeyExpCollection<VSegment, i32, ShapeCountBoolean>,
+    H: FillHandler,
+{
+    match fill_rule {
+        FillRule::EvenOdd => {
+            sweep_with_handler::<ShapeCountBoolean, EvenOddStrategy, S, H>(scan, segments, handler)
+        }
+        FillRule::NonZero => {
+            sweep_with_handler::<ShapeCountBoolean, NonZeroStrategy, S, H>(scan, segments, handler)
+        }
+        FillRule::Positive => {
+            sweep_with_handler::<ShapeCountBoolean, PositiveStrategy, S, H>(scan, segments, handler)
+        }
+        FillRule::Negative => {
+            sweep_with_handler::<ShapeCountBoolean, NegativeStrategy, S, H>(scan, segments, handler)
+        }
+    }
+}
+
 struct EvenOddStrategy;
 struct NonZeroStrategy;
 struct PositiveStrategy;

iOverlay/src/build/builder.rs

@@ -7,20 +7,115 @@ use crate::segm::segment::{NONE, Segment, SegmentFill};
 use crate::segm::winding::WindingCount;
 use crate::util::log::Int;
 use alloc::vec::Vec;
+use core::ops::ControlFlow;
 use i_float::triangle::Triangle;
 use i_shape::util::reserve::Reserve;
 use i_tree::key::exp::KeyExpCollection;
 use i_tree::key::list::KeyExpList;
 use i_tree::key::tree::KeyExpTree;
 
-pub(super) trait FillStrategy<C> {
+pub(crate) trait FillStrategy<C> {
     fn add_and_fill(this: C, bot: C) -> (C, SegmentFill);
 }
 
 pub(super) trait InclusionFilterStrategy {
     fn is_included(fill: SegmentFill) -> bool;
 }
 
+/// Handler for processing segment fills during sweep.
+/// Enables early-exit for predicates like `intersects()`.
+pub(crate) trait FillHandler {
+    type Output;
+    fn handle(&mut self, index: usize, fill: SegmentFill) -> ControlFlow<Self::Output>;
+    fn finalize(self) -> Self::Output;
+}
+
+/// Handler that stores fills in a Vec (used by GraphBuilder).
+pub(crate) struct StoreFillsHandler<'a> {
+    fills: &'a mut Vec<SegmentFill>,
+}
+
+impl<'a> StoreFillsHandler<'a> {
+    #[inline]
+    pub(crate) fn new(fills: &'a mut Vec<SegmentFill>) -> Self {
+        Self { fills }
+    }
+}
+
+impl FillHandler for StoreFillsHandler<'_> {
+    type Output = ();
+
+    #[inline(always)]
+    fn handle(&mut self, index: usize, fill: SegmentFill) -> ControlFlow<()> {
+        self.fills[index] = fill;
+        ControlFlow::Continue(())
+    }
+
+    #[inline(always)]
+    fn finalize(self) {}
+}
+
+/// Core sweep-line algorithm that computes segment fills and passes them to a handler.
+/// This is the shared implementation used by both graph building and predicate evaluation.
+#[inline]
+pub(crate) fn sweep_with_handler<C, F, S, H>(
+    scan: &mut S,
+    segments: &[Segment<C>],
+    mut handler: H,
+) -> H::Output
+where
+    C: WindingCount,
+    F: FillStrategy<C>,
+    S: KeyExpCollection<VSegment, i32, C>,
+    H: FillHandler,
+{
+    let mut node = Vec::with_capacity(4);
+    let n = segments.len();
+    let mut i = 0;
+
+    while i < n {
+        let p = segments[i].x_segment.a;
+
+        node.push(End {
+            index: i,
+            point: segments[i].x_segment.b,
+        });
+        i += 1;
+
+        while i < n && segments[i].x_segment.a == p {
+            node.push(End {
+                index: i,
+                point: segments[i].x_segment.b,
+            });
+            i += 1;
+        }
+
+        if node.len() > 1 {
+            node.sort_by(|s0, s1| Triangle::clock_order_point(p, s1.point, s0.point));
+        }
+
+        let mut sum_count = scan.first_less_or_equal_by(p.x, C::new(0, 0), |s| s.is_under_point_order(p));
+
+        for se in node.iter() {
+            let sid = unsafe { segments.get_unchecked(se.index) };
+            let (new_sum, fill) = F::add_and_fill(sid.count, sum_count);
+            sum_count = new_sum;
+
+            if let ControlFlow::Break(result) = handler.handle(se.index, fill) {
+                return result;
+            }
+
+            if sid.x_segment.is_not_vertical() {
+                scan.insert(sid.x_segment.into(), sum_count, p.x);
+            }
+        }
+
+        node.clear();
+    }
+
+    handler.finalize()
+}
+
 pub(crate) trait GraphNode {
     fn with_indices(indices: &[usize]) -> Self;
 }
@@ -73,56 +168,8 @@ impl<C: WindingCount, N: GraphNode> GraphBuilder<C, N> {
         scan_list: &mut S,
         segments: &[Segment<C>],
     ) {
-        let mut node = Vec::with_capacity(4);
-
-        let n = segments.len();
-
-        self.fills.resize(n, NONE);
-
-        let mut i = 0;
-
-        while i < n {
-            let p = segments[i].x_segment.a;
-
-            node.push(End {
-                index: i,
-                point: segments[i].x_segment.b,
-            });
-            i += 1;
-
-            while i < n && segments[i].x_segment.a == p {
-                node.push(End {
-                    index: i,
-                    point: segments[i].x_segment.b,
-                });
-                i += 1;
-            }
-
-            if node.len() > 1 {
-                node.sort_by(|s0, s1| Triangle::clock_order_point(p, s1.point, s0.point));
-            }
-
-            let mut sum_count =
-                scan_list.first_less_or_equal_by(p.x, C::new(0, 0), |s| s.is_under_point_order(p));
-            let mut fill: SegmentFill;
-
-            for se in node.iter() {
-                let sid = unsafe {
-                    // SAFETY: `se.index` was produced from `i` while iterating i ∈ [0, n) over `segments`
-                    segments.get_unchecked(se.index)
-                };
-                (sum_count, fill) = F::add_and_fill(sid.count, sum_count);
-                unsafe {
-                    // SAFETY: `se.index` was produced from `i` while iterating i ∈ [0, n) over `segments` and segments.len == self.fills.len
-                    *self.fills.get_unchecked_mut(se.index) = fill
-                }
-                if sid.x_segment.is_not_vertical() {
-                    scan_list.insert(sid.x_segment.into(), sum_count, p.x);
-                }
-            }
-
-            node.clear();
-        }
+        self.fills.resize(segments.len(), NONE);
+        sweep_with_handler::<C, F, S, _>(scan_list, segments, StoreFillsHandler::new(&mut self.fills));
     }
 
     #[inline]

iOverlay/src/core/mod.rs

@@ -7,5 +7,7 @@ pub(crate) mod link;
 pub(crate) mod nearest_vector;
 pub mod overlay;
 pub mod overlay_rule;
+pub mod predicate;
+pub mod relate;
 pub mod simplify;
 pub mod solver;