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}