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}