Skip to main content

ifc_geometry/authoring/
spiral.rs

1//! Authoring transition spirals.
2//!
3//! A spiral is an alignment transition curve: curvature varies along
4//! its length so a vehicle can move between a straight and an arc
5//! without an instantaneous change of steering angle.
6//!
7//! All six share one shape -- a `Position` placement, one required
8//! leading term, then optional lower-order terms in descending degree.
9//! The terms are trailing OPTIONALs, so an absent one is `Null` in its
10//! own slot rather than a shortened record: writing a shorter list
11//! would silently shift every following term up a degree.
12
13use ifc_model::{Entity, EntityId, Transaction, Value};
14
15use crate::error::GeometryError;
16
17use super::{invalid, require_finite};
18
19/// Which spiral to stage, with its defining terms.
20///
21/// Each variant names its terms as the schema does, highest degree
22/// first. The leading term is required because it is what makes the
23/// spiral that kind: a clothoid with no constant is not a clothoid.
24#[derive(Debug, Clone, Copy, PartialEq)]
25pub enum SpiralKind {
26    /// `IfcClothoid`: curvature proportional to arc length.
27    Clothoid {
28        /// `ClothoidConstant`.
29        constant: f64,
30    },
31    /// `IfcCosineSpiral`.
32    Cosine {
33        /// `CosineTerm`.
34        cosine: f64,
35        /// `ConstantTerm`.
36        constant: Option<f64>,
37    },
38    /// `IfcSineSpiral`.
39    Sine {
40        /// `SineTerm`.
41        sine: f64,
42        /// `LinearTerm`.
43        linear: Option<f64>,
44        /// `ConstantTerm`.
45        constant: Option<f64>,
46    },
47    /// `IfcSecondOrderPolynomialSpiral`.
48    SecondOrder {
49        /// `QuadraticTerm`.
50        quadratic: f64,
51        /// `LinearTerm`.
52        linear: Option<f64>,
53        /// `ConstantTerm`.
54        constant: Option<f64>,
55    },
56    /// `IfcThirdOrderPolynomialSpiral`.
57    ThirdOrder {
58        /// `CubicTerm`.
59        cubic: f64,
60        /// `QuadraticTerm`.
61        quadratic: Option<f64>,
62        /// `LinearTerm`.
63        linear: Option<f64>,
64        /// `ConstantTerm`.
65        constant: Option<f64>,
66    },
67    /// `IfcSeventhOrderPolynomialSpiral`.
68    SeventhOrder {
69        /// `SepticTerm`, then lower degrees in descending order.
70        septic: f64,
71        /// Optional terms, sextic down to constant.
72        lower: [Option<f64>; 7],
73    },
74}
75
76impl SpiralKind {
77    /// The IFC entity name for this spiral.
78    fn entity_name(self) -> &'static str {
79        match self {
80            Self::Clothoid { .. } => "IFCCLOTHOID",
81            Self::Cosine { .. } => "IFCCOSINESPIRAL",
82            Self::Sine { .. } => "IFCSINESPIRAL",
83            Self::SecondOrder { .. } => "IFCSECONDORDERPOLYNOMIALSPIRAL",
84            Self::ThirdOrder { .. } => "IFCTHIRDORDERPOLYNOMIALSPIRAL",
85            Self::SeventhOrder { .. } => "IFCSEVENTHORDERPOLYNOMIALSPIRAL",
86        }
87    }
88
89    /// The name of the required leading term, for error reporting.
90    fn leading_attribute(self) -> &'static str {
91        match self {
92            Self::Clothoid { .. } => "ClothoidConstant",
93            Self::Cosine { .. } => "CosineTerm",
94            Self::Sine { .. } => "SineTerm",
95            Self::SecondOrder { .. } => "QuadraticTerm",
96            Self::ThirdOrder { .. } => "CubicTerm",
97            Self::SeventhOrder { .. } => "SepticTerm",
98        }
99    }
100
101    /// The term slots after `Position`, in schema order.
102    fn terms(self) -> (f64, Vec<Option<f64>>) {
103        match self {
104            Self::Clothoid { constant } => (constant, Vec::new()),
105            Self::Cosine { cosine, constant } => (cosine, vec![constant]),
106            Self::Sine {
107                sine,
108                linear,
109                constant,
110            } => (sine, vec![linear, constant]),
111            Self::SecondOrder {
112                quadratic,
113                linear,
114                constant,
115            } => (quadratic, vec![linear, constant]),
116            Self::ThirdOrder {
117                cubic,
118                quadratic,
119                linear,
120                constant,
121            } => (cubic, vec![quadratic, linear, constant]),
122            Self::SeventhOrder { septic, lower } => (septic, lower.to_vec()),
123        }
124    }
125}
126
127/// Stage a transition spiral.
128///
129/// # Errors
130///
131/// Refuses a non-finite term, and a zero leading term: the leading
132/// coefficient is what gives the spiral its degree, so a zero one
133/// describes a lower-order curve wearing the wrong type name.
134pub fn spiral(
135    tx: &mut Transaction,
136    position: EntityId,
137    kind: SpiralKind,
138) -> Result<EntityId, GeometryError> {
139    let entity = kind.entity_name();
140    let (leading, lower) = kind.terms();
141
142    require_finite(entity, kind.leading_attribute(), &[leading])?;
143    if leading == 0.0 {
144        return Err(invalid(
145            entity,
146            kind.leading_attribute(),
147            "expected a non-zero leading term",
148        ));
149    }
150    let present: Vec<f64> = lower.iter().flatten().copied().collect();
151    require_finite(entity, "term", &present)?;
152
153    let mut attrs = vec![Value::Ref(position), Value::Real(leading)];
154    attrs.extend(
155        lower
156            .into_iter()
157            .map(|t| t.map_or(Value::Null, Value::Real)),
158    );
159    Ok(tx.create(Entity::new(entity, attrs)))
160}