Skip to main content

ifc_geometry/curve/
mod.rs

1//! Typed read-only views of the `IfcCurve` family.
2//!
3//! # What is here and what is deliberately not
4//!
5//! These are *views*: newtypes over `(EntityId, &Entity)` that name the
6//! attributes and check the invariants a file can violate. Nothing here
7//! evaluates a curve, tessellates one, or implements NURBS basis functions.
8//! A geometry kernel does that; this module's job is to hand it parameters it
9//! can trust, and to fail loudly where the file cannot be trusted.
10//!
11//! # The taxonomy
12//!
13//! `IfcCurve` is abstract with three branches:
14//!
15//! ```text
16//!   IfcCurve
17//!   |- IfcLine                     unbounded, point + vector
18//!   |- IfcConic                    unbounded, placement + radii
19//!   |  |- IfcCircle
20//!   |  '- IfcEllipse
21//!   |- IfcOffsetCurve2D / 3D       relative to another curve
22//!   |- IfcPcurve                   in a surface's parameter space
23//!   |- IfcSurfaceCurve             on one or two surfaces
24//!   |  |- IfcIntersectionCurve
25//!   |  '- IfcSeamCurve
26//!   '- IfcBoundedCurve             has a start and an end
27//!      |- IfcPolyline
28//!      |- IfcIndexedPolyCurve
29//!      |- IfcTrimmedCurve
30//!      |- IfcCompositeCurve
31//!      |  '- IfcCompositeCurveOnSurface
32//!      |     '- IfcBoundaryCurve
33//!      |        '- IfcOuterBoundaryCurve
34//!      '- IfcBSplineCurve
35//!         '- IfcBSplineCurveWithKnots
36//!            '- IfcRationalBSplineCurveWithKnots
37//! ```
38//!
39//! **Bounded versus unbounded is the distinction that bites.** An `IfcCircle`
40//! is the whole circle; an `IfcLine` is infinite in both directions. Neither
41//! can be drawn on its own. They appear in files almost exclusively as the
42//! `BasisCurve` of an [`trimmed::TrimmedCurve`] or as the `ParentCurve` of a
43//! [`composite::CompositeCurveSegment`], which is where the bounds come from.
44//! Code that meets an `IfcCircle` at the top of a representation and draws a
45//! full circle has usually skipped a trim.
46//!
47//! # `IfcCurveSegment`
48//!
49//! Not in IFC4 ADD2 TC1. It was introduced in IFC4x3 for alignment geometry
50//! and has no view here; [`CurveKind::classify`] returns `None` for it, so a
51//! consumer meeting one in an IFC4x3 file gets an honest miss rather than a
52//! wrong shape. Lowering reads it directly (`lower::curve::segment`).
53//!
54//! # Coordinate and parameter units
55//!
56//! Curve coordinates are in the model's length unit, but `IfcParameterValue`
57//! is not a length. On a conic it is an angle in the model's *plane-angle*
58//! unit, which is degrees in a large minority of files. No accessor in this
59//! module converts anything; see [`crate::units`].
60
61pub mod bspline;
62pub mod composite;
63pub mod conic;
64pub mod line;
65pub mod offset;
66pub mod polyline;
67pub mod trimmed;
68
69pub use bspline::{BSplineCurve, BSplineCurveForm, KnotType, KnotVector};
70pub use composite::{CompositeCurve, CompositeCurveSegment, TransitionCode};
71pub use conic::{Circle, Ellipse};
72pub use line::Line;
73pub use offset::{
74    OffsetCurve2D, OffsetCurve3D, PCurve, PreferredSurfaceCurveRepresentation, SurfaceCurve,
75    SurfaceCurveKind,
76};
77pub use polyline::{IndexedPolyCurve, PolySegment, Polyline};
78pub use trimmed::{Trim, TrimPoint, TrimSpec, TrimmedCurve, TrimmingPreference};
79
80/// Which concrete `IfcCurve` subtype an entity is.
81///
82/// # Why classify at all
83///
84/// A representation item's attribute is typed `IfcCurve`, so the file gives a
85/// reference and nothing else. Dispatch has to happen on the type name, and
86/// doing it in one place keeps the spelling of 15 IFC type names out of every
87/// call site.
88#[derive(Debug, Clone, Copy, PartialEq, Eq)]
89pub enum CurveKind {
90    /// `IfcLine`: unbounded, needs trimming to be drawable.
91    Line,
92    /// `IfcCircle`: the *whole* circle unless trimmed.
93    Circle,
94    /// `IfcEllipse`: the whole ellipse unless trimmed.
95    Ellipse,
96    /// `IfcPolyline`: a chain of `IfcCartesianPoint` entities.
97    Polyline,
98    /// `IfcIndexedPolyCurve`: a point list plus 1-based index segments.
99    IndexedPolyCurve,
100    /// `IfcTrimmedCurve`: a bounded piece of some other curve.
101    TrimmedCurve,
102    /// `IfcCompositeCurve` or a subtype; see [`CompositeCurve::is_on_surface`].
103    CompositeCurve,
104    /// Any `IfcBSplineCurve` subtype.
105    BSplineCurve,
106    /// `IfcOffsetCurve2D`: offset in the plane.
107    OffsetCurve2D,
108    /// `IfcOffsetCurve3D`: offset in space, needs a reference direction.
109    OffsetCurve3D,
110    /// `IfcPcurve`: a curve in a surface's parameter space.
111    PCurve,
112    /// `IfcSurfaceCurve` or a subtype.
113    SurfaceCurve,
114}
115
116impl CurveKind {
117    /// Classify an IFC type name, or `None` if it is not an `IfcCurve`.
118    ///
119    /// Case-insensitive because STEP keywords are, and real files disagree
120    /// about casing even within one export.
121    pub fn classify(type_name: &str) -> Option<Self> {
122        match type_name.to_ascii_uppercase().as_str() {
123            "IFCLINE" => Some(Self::Line),
124            "IFCCIRCLE" => Some(Self::Circle),
125            "IFCELLIPSE" => Some(Self::Ellipse),
126            "IFCPOLYLINE" => Some(Self::Polyline),
127            "IFCINDEXEDPOLYCURVE" => Some(Self::IndexedPolyCurve),
128            "IFCTRIMMEDCURVE" => Some(Self::TrimmedCurve),
129            "IFCCOMPOSITECURVE"
130            | "IFCCOMPOSITECURVEONSURFACE"
131            | "IFCBOUNDARYCURVE"
132            | "IFCOUTERBOUNDARYCURVE" => Some(Self::CompositeCurve),
133            "IFCBSPLINECURVE" | "IFCBSPLINECURVEWITHKNOTS" | "IFCRATIONALBSPLINECURVEWITHKNOTS" => {
134                Some(Self::BSplineCurve)
135            }
136            "IFCOFFSETCURVE2D" => Some(Self::OffsetCurve2D),
137            "IFCOFFSETCURVE3D" => Some(Self::OffsetCurve3D),
138            "IFCPCURVE" => Some(Self::PCurve),
139            "IFCSURFACECURVE" | "IFCINTERSECTIONCURVE" | "IFCSEAMCURVE" => Some(Self::SurfaceCurve),
140            _ => None,
141        }
142    }
143
144    /// Is this curve bounded on its own, without an enclosing trim?
145    ///
146    /// The question to ask before drawing anything. `false` means the entity
147    /// describes an infinite or closed-and-unbounded locus that only becomes a
148    /// drawable edge inside an `IfcTrimmedCurve` or an
149    /// `IfcCompositeCurveSegment`.
150    ///
151    /// `IfcPcurve` and `IfcSurfaceCurve` are `false` because their bounds come
152    /// from the curve they wrap, which may itself be unbounded.
153    pub fn is_bounded(&self) -> bool {
154        matches!(
155            self,
156            Self::Polyline
157                | Self::IndexedPolyCurve
158                | Self::TrimmedCurve
159                | Self::CompositeCurve
160                | Self::BSplineCurve
161        )
162    }
163
164    /// Is this a closed conic whose trimming is sense-dependent?
165    ///
166    /// True for `IfcCircle` and `IfcEllipse`. When one of these is the basis
167    /// curve of an `IfcTrimmedCurve`, the trim pair plus `SenseAgreement`
168    /// select one of four arcs; see [`trimmed`].
169    pub fn is_closed_conic(&self) -> bool {
170        matches!(self, Self::Circle | Self::Ellipse)
171    }
172}
173
174#[cfg(test)]
175mod tests {
176    use super::*;
177
178    #[test]
179    fn every_ifc4_curve_type_name_classifies() {
180        let names = [
181            "IFCLINE",
182            "IFCCIRCLE",
183            "IFCELLIPSE",
184            "IFCPOLYLINE",
185            "IFCINDEXEDPOLYCURVE",
186            "IFCTRIMMEDCURVE",
187            "IFCCOMPOSITECURVE",
188            "IFCCOMPOSITECURVEONSURFACE",
189            "IFCBOUNDARYCURVE",
190            "IFCOUTERBOUNDARYCURVE",
191            "IFCBSPLINECURVE",
192            "IFCBSPLINECURVEWITHKNOTS",
193            "IFCRATIONALBSPLINECURVEWITHKNOTS",
194            "IFCOFFSETCURVE2D",
195            "IFCOFFSETCURVE3D",
196            "IFCPCURVE",
197            "IFCSURFACECURVE",
198            "IFCINTERSECTIONCURVE",
199            "IFCSEAMCURVE",
200        ];
201        for name in names {
202            assert!(
203                CurveKind::classify(name).is_some(),
204                "{name} is an IfcCurve subtype but does not classify"
205            );
206        }
207    }
208
209    #[test]
210    fn a_non_curve_entity_does_not_classify_as_a_curve() {
211        assert_eq!(CurveKind::classify("IFCWALL"), None);
212        assert_eq!(CurveKind::classify("IFCPLANE"), None);
213        assert_eq!(CurveKind::classify("IFCCARTESIANPOINT"), None);
214    }
215
216    /// IfcCurveSegment is IFC4x3 only; claiming to handle it would substitute
217    /// wrong geometry for alignment models.
218    #[test]
219    fn ifc4x3_curve_segment_is_an_honest_miss_rather_than_a_wrong_match() {
220        assert_eq!(CurveKind::classify("IFCCURVESEGMENT"), None);
221    }
222
223    /// STEP keywords are case-insensitive and exports are inconsistent.
224    #[test]
225    fn classification_ignores_case() {
226        assert_eq!(CurveKind::classify("IfcCircle"), Some(CurveKind::Circle));
227        assert_eq!(
228            CurveKind::classify("ifcpolyline"),
229            Some(CurveKind::Polyline)
230        );
231    }
232
233    /// Drawing an untrimmed IfcCircle as a full circle is a real and common
234    /// bug; the boundedness flag is what prevents it.
235    #[test]
236    fn unbounded_curves_are_distinguished_from_drawable_ones() {
237        for kind in [
238            CurveKind::Line,
239            CurveKind::Circle,
240            CurveKind::Ellipse,
241            CurveKind::OffsetCurve2D,
242            CurveKind::OffsetCurve3D,
243            CurveKind::PCurve,
244            CurveKind::SurfaceCurve,
245        ] {
246            assert!(!kind.is_bounded(), "{kind:?} must not claim to be bounded");
247        }
248        for kind in [
249            CurveKind::Polyline,
250            CurveKind::IndexedPolyCurve,
251            CurveKind::TrimmedCurve,
252            CurveKind::CompositeCurve,
253            CurveKind::BSplineCurve,
254        ] {
255            assert!(kind.is_bounded(), "{kind:?} is bounded");
256        }
257    }
258
259    #[test]
260    fn only_conics_are_flagged_as_sense_dependent_when_trimmed() {
261        assert!(CurveKind::Circle.is_closed_conic());
262        assert!(CurveKind::Ellipse.is_closed_conic());
263        assert!(!CurveKind::Line.is_closed_conic());
264        assert!(!CurveKind::BSplineCurve.is_closed_conic());
265    }
266}