Skip to main content

ifc_alignment/cant/
frame.rs

1//! Cant as data at a station: rail heights, bank angle and the section frame.
2//!
3//! The cant layout states, per station, how far each rail head sits above
4//! the vertical profile (`IfcAlignmentCantSegment` "measured relatively to
5//! vertical alignment"). With the parent's `RailHeadDistance` `b` that fixes
6//! the cross-section exactly:
7//!
8//! - cant `D = left - right`, positive when the left rail is higher;
9//! - bank angle `psi = arcsin(D / b)`, the relation IFC4.3 ADD2
10//!   (`IfcAlignmentCantSegmentTypeEnum`) states, so the two rail heads sit
11//!   `b/2 sin(psi) = D/2` above and below the section's rotation point;
12//! - that point -- the deviating elevation `IfcSegmentedReferenceCurve`
13//!   describes -- lies `(left + right) / 2` above the profile: zero for a
14//!   rotation about the track centreline, `D/2` for one about the low rail.
15//!
16//! Inside a `VIENNESEBEND` the standard states `psi` itself, so `D` and the
17//! frame come from that angle law and the rails sit `D/2` either side of a
18//! rotation point that stays put (#312), or a held rail stays and the other
19//! sits `D` from it (#364). A rotation point that moves with neither rail
20//! held is refused, as the banked centreline refuses it.
21//!
22//! The frame is the section rotated by `psi` about the centreline tangent,
23//! right-handed: in the basis `(t, n, u)` -- `t` the unit 3D tangent of the
24//! gradient curve, `n` the horizontal unit normal to its left, `u = t x n`
25//! -- the rail-to-rail axis is `cos(psi) n + sin(psi) u` and the section's
26//! up axis `-sin(psi) n + cos(psi) u`.
27//!
28//! This is the same rotation the lowered banked centreline carries
29//! (`lower_segmented_reference_curve`, `BankConvention::TangentRotation`),
30//! stated as data at one station: the tangent comes from whichever
31//! evaluator the caller uses. Where the rotation point moves (a low-rail
32//! pivot, a held rail through a Viennese bend), the banked curve turns the
33//! section about its own point path's tangent, which climbs by the
34//! point's rate over the profile; given that tangent, [`CantFrame::orient`]
35//! gives the banked section's frame. The rail heights here are the
36//! vertical ones the cant layout states; the banked section's rail heads,
37//! `b / 2` from the rotation point square to that tangent, stand
38//! `(D / 2)(1 - cos(theta))` closer to the rotation point's height, `theta`
39//! the climb of the point path (see `lower_segmented_reference_curve`). [`CantFrame::orient`] turns a caller-supplied
40//! point and tangent into a world frame; it is algebra on those vectors,
41//! not evaluation of any curve.
42
43use axiolid_core::{Frame3, Point3, Vec2, Vec3};
44
45use crate::cant::layout::CantLayout;
46use crate::error::{AlignmentError, AlignmentResult};
47
48/// The cant cross-section at one station.
49#[derive(Debug, Clone, Copy, PartialEq)]
50#[non_exhaustive]
51pub struct CantFrame {
52    /// Absolute distance along the horizontal alignment, in metres.
53    pub distance_along: f64,
54    /// Left rail head above the vertical profile, in metres.
55    pub left: f64,
56    /// Right rail head above the vertical profile, in metres.
57    pub right: f64,
58    /// Cant `D = left - right`, positive when the left rail is higher.
59    pub cant: f64,
60    /// Elevation of the section's rotation point above the vertical
61    /// profile: `(left + right) / 2`.
62    pub axis_elevation: f64,
63    /// Bank angle `psi = arcsin(D / b)` in radians, positive raising the
64    /// left rail (counter-clockwise looking along the tangent).
65    pub bank_angle: f64,
66    /// Rail-to-rail axis (towards the left rail) as `(n, u)` components.
67    pub lateral: Vec2,
68    /// Section up axis as `(n, u)` components.
69    pub up: Vec2,
70}
71
72impl CantFrame {
73    /// The section frame in world coordinates.
74    ///
75    /// `point` and `tangent` are the gradient curve's point and 3D tangent
76    /// at this frame's station, from the caller's evaluator. The origin is
77    /// `point` raised by [`Self::axis_elevation`] along world up (the cant
78    /// is measured vertically from the profile); `x` is the unit tangent,
79    /// `y` the rail-to-rail axis and `z` the section up axis.
80    ///
81    /// # Errors
82    ///
83    /// Refuses a non-finite point or tangent, and a vertical or zero
84    /// tangent, which has no horizontal left normal.
85    pub fn orient(&self, point: Point3, tangent: Vec3) -> AlignmentResult<Frame3> {
86        let invalid = |detail| Err(AlignmentError::InvalidUnits { detail });
87        if !(point.is_finite() && tangent.is_finite()) {
88            return invalid("cant frame point and tangent must be finite");
89        }
90        let horizontal = (tangent.x * tangent.x + tangent.y * tangent.y).sqrt();
91        if horizontal == 0.0 {
92            return invalid("a vertical or zero tangent has no horizontal left normal");
93        }
94        let t = tangent.normalize();
95        let n = Vec3::new(-tangent.y / horizontal, tangent.x / horizontal, 0.0);
96        let u = t.cross(n);
97        Ok(Frame3 {
98            origin: point + Vec3::Z * self.axis_elevation,
99            x: t,
100            y: n * self.lateral.x + u * self.lateral.y,
101            z: n * self.up.x + u * self.up.y,
102        })
103    }
104}
105
106impl CantLayout {
107    /// The cant cross-section at an absolute distance along.
108    ///
109    /// # Errors
110    ///
111    /// Refuses a distance outside the profile's span, a segment whose cant
112    /// cannot be evaluated exactly (including the inside of a Viennese bend
113    /// whose rotation point moves with neither rail held,
114    /// [`AlignmentError::Unsupported`]), and a
115    /// cant exceeding the `RailHeadDistance` (`|D| > b`, no real bank
116    /// angle).
117    pub fn frame_at_distance(&self, distance_along: f64) -> AlignmentResult<CantFrame> {
118        let at = self.cant_at_distance(distance_along)?;
119        let cant = at.left - at.right;
120        let ratio = cant / self.rail_head_distance;
121        if !(-1.0..=1.0).contains(&ratio) {
122            return Err(AlignmentError::SemanticViolation {
123                entity: Some(self.entity),
124                rule: "cant must not exceed the rail head distance (|D| <= b)",
125            });
126        }
127        let bank_angle = ratio.asin();
128        let (sin, cos) = bank_angle.sin_cos();
129        Ok(CantFrame {
130            distance_along,
131            left: at.left,
132            right: at.right,
133            cant,
134            axis_elevation: 0.5 * (at.left + at.right),
135            bank_angle,
136            lateral: Vec2::new(cos, sin),
137            up: Vec2::new(-sin, cos),
138        })
139    }
140}