geo 0.33.1

Geospatial primitives and algorithms
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120

pub(crate) use edge_end_builder::EdgeEndBuilder;
pub use geomgraph::intersection_matrix::IntersectionMatrix;
use relate_operation::RelateOperation;

use crate::geometry::*;
#[deprecated(
    since = "0.31.1",
    note = "PreparedGeometry has moved to geo::indexed::PreparedGeometry"
)]
pub use crate::indexed::PreparedGeometry;
pub use crate::relate::geomgraph::GeometryGraph;
use crate::{BoundingRect, GeoFloat, GeometryCow, HasDimensions};

mod edge_end_builder;
pub(crate) mod geomgraph;
mod relate_operation;

/// Topologically relate two geometries based on [DE-9IM](https://en.wikipedia.org/wiki/DE-9IM) semantics.
///
/// See [`IntersectionMatrix`] for details. All predicates are available on the calculated matrix.
///
/// # Examples
///
/// ```
/// use geo::{coord, Line, Rect, line_string};
/// use crate::geo::relate::Relate;
///
/// let line = Line::new(coord! { x: 2.0, y: 2.0}, coord! { x: 4.0, y: 4.0 });
/// let rect = Rect::new(coord! { x: 2.0, y: 2.0}, coord! { x: 4.0, y: 4.0 });
/// let intersection_matrix = rect.relate(&line);
///
/// assert!(intersection_matrix.is_intersects());
/// assert!(!intersection_matrix.is_disjoint());
/// assert!(intersection_matrix.is_contains());
/// assert!(!intersection_matrix.is_within());
///
/// let line = Line::new(coord! { x: 1.0, y: 1.0}, coord! { x: 5.0, y: 5.0 });
/// let rect = Rect::new(coord! { x: 2.0, y: 2.0}, coord! { x: 4.0, y: 4.0 });
/// let intersection_matrix = rect.relate(&line);
/// assert!(intersection_matrix.is_intersects());
/// assert!(!intersection_matrix.is_disjoint());
/// assert!(!intersection_matrix.is_contains());
/// assert!(!intersection_matrix.is_within());
///
/// let rect_boundary = line_string![
///     (x: 2.0, y: 2.0),
///     (x: 4.0, y: 2.0),
///     (x: 4.0, y: 4.0),
///     (x: 2.0, y: 4.0),
///     (x: 2.0, y: 2.0)
/// ];
/// let intersection_matrix = rect.relate(&rect_boundary);
/// assert!(intersection_matrix.is_intersects());
/// assert!(!intersection_matrix.is_disjoint());
/// // According to DE-9IM, polygons don't contain their own boundary
/// assert!(!intersection_matrix.is_contains());
/// assert!(!intersection_matrix.is_within());
/// ```
///
/// Note: `Relate` must not be called on geometries containing `NaN` coordinates.
pub trait Relate<F: GeoFloat>: BoundingRect<F> + HasDimensions {
    /// Returns a noded topology graph for the geometry.
    ///
    /// # Params
    ///
    /// `idx`: 0 or 1, designating A or B (respectively) in the role this geometry plays
    ///        in the relation. e.g. in `a.relate(b)`
    fn geometry_graph(&self, idx: usize) -> GeometryGraph<'_, F>;

    fn relate(&self, other: &impl Relate<F>) -> IntersectionMatrix
    where
        Self: Sized,
    {
        RelateOperation::new(self, other).compute_intersection_matrix()
    }
}

macro_rules! relate_impl {
    ($($t:ty ,)*) => {
        $(
            impl<F: GeoFloat> Relate<F> for $t {
                fn geometry_graph(&self, arg_index: usize) -> GeometryGraph<'_, F> {
                    $crate::relate::GeometryGraph::new(arg_index, GeometryCow::from(self))
                }
            }
            impl<F: GeoFloat> From<$t> for PreparedGeometry<'static, $t, F> {
                fn from(geometry: $t) -> Self {
                    $crate::indexed::prepared_geometry::prepare_geometry(geometry)
                }
            }
            impl<'a, F: GeoFloat> From<&'a $t> for PreparedGeometry<'a, &'a $t, F> {
                fn from(geometry: &'a $t) -> Self {
                    $crate::indexed::prepared_geometry::prepare_geometry(geometry)
                }
            }
        )*
    };
}

relate_impl![
    Point<F>,
    Line<F>,
    LineString<F>,
    Polygon<F>,
    MultiPoint<F>,
    MultiLineString<F>,
    MultiPolygon<F>,
    Rect<F>,
    Triangle<F>,
    GeometryCollection<F>,
    Geometry<F>,
];

#[cfg(test)]
mod tests {
    #[test]
    fn run_jts_relate_tests() {
        jts_test_runner::assert_jts_tests_succeed("*Relate*.xml");
    }
}