Skip to main content

ifc_georef/context/
chain.rs

1//! Composing a project frame with a resolved project-to-map operation.
2//!
3//! [`crate::resolve_project_to_map`] produces the operation IFC declares:
4//! project engineering coordinates to map coordinates. It does not know, and
5//! must not know, where in the project a given product actually sits --
6//! that is `IfcLocalPlacement` chain resolution, which is `ifc-geometry`'s
7//! job. This crate never places individual products (see the crate-level
8//! docs).
9//!
10//! A caller that *has* resolved a product's placement down to a single
11//! neutral transform (its "project frame": the product's placement relative
12//! to the project's `IfcGeometricRepresentationContext.WorldCoordinateSystem`)
13//! can compose it with the project-to-map operation here to get that
14//! product's map-frame transform. This module owns exactly that
15//! composition -- it takes the project frame as an opaque, already-resolved
16//! `Transform3` rather than reaching into `ifc-geometry` for it, which is
17//! what keeps the crate boundary intact.
18
19use axiolid_core::Transform3;
20
21use crate::conversion::ProjectToMap;
22use crate::error::{GeorefError, GeorefResult};
23
24/// Compose an externally supplied project frame with a resolved
25/// project-to-map operation, producing the project frame's map-frame
26/// transform.
27///
28/// `project_frame` maps a point from some product-local space into the
29/// project's own engineering coordinate system (metres, matching
30/// `operation.project_unit`). The result maps that same point straight into
31/// map coordinates: `map_frame = operation.transform * project_frame`, i.e.
32/// `project_frame` is applied first.
33///
34/// Refuses (rather than silently propagating `NaN`/`Inf`) when
35/// `project_frame`'s linear part is not invertible: a singular frame means
36/// the supplied placement collapsed a dimension, and composing it here would
37/// produce map coordinates that look plausible but encode no real position.
38pub fn compose_project_frame(
39    operation: &ProjectToMap,
40    project_frame: Transform3,
41) -> GeorefResult<Transform3> {
42    let determinant = project_frame.matrix3.determinant();
43    if !determinant.is_finite() || determinant.abs() <= f64::EPSILON {
44        return Err(GeorefError::DegenerateProjectFrame);
45    }
46    Ok(operation.transform * project_frame)
47}
48
49#[cfg(test)]
50mod tests {
51    use std::sync::Arc;
52
53    use axiolid_core::{Mat3, Point3, Vec3};
54    use ifc_model::value::Value;
55    use ifc_model::{Entity, EntityId, Model};
56
57    use super::*;
58    use crate::conversion::resolve_project_to_map;
59
60    fn id(value: u64) -> EntityId {
61        EntityId(value)
62    }
63
64    fn r(value: u64) -> Value {
65        Value::Ref(id(value))
66    }
67
68    fn real(value: f64) -> Value {
69        Value::Real(value)
70    }
71
72    fn model_with_map_conversion() -> Model {
73        let mut model = Model::new();
74        model.insert(
75            id(1),
76            Entity::new("IFCGEOMETRICREPRESENTATIONCONTEXT", vec![]),
77        );
78        model.insert(
79            id(2),
80            Entity::new(
81                "IFCPROJECTEDCRS",
82                vec![Value::Text(Arc::from("EPSG:25832"))],
83            ),
84        );
85        model.insert(
86            id(4),
87            Entity::new(
88                "IFCMAPCONVERSION",
89                vec![
90                    r(1),
91                    r(2),
92                    real(1000.0),
93                    real(2000.0),
94                    real(50.0),
95                    Value::Null,
96                    Value::Null,
97                    real(1.0),
98                ],
99            ),
100        );
101        model
102    }
103
104    #[test]
105    fn composes_a_translated_project_frame_into_map_coordinates() {
106        let model = model_with_map_conversion();
107        let operation = resolve_project_to_map(&model, id(4), 1.0).expect("resolves");
108
109        // The project frame places a product's local origin at (10, 20, 0)
110        // in project engineering coordinates.
111        let project_frame =
112            Transform3::from_mat3_translation(Mat3::IDENTITY, Vec3::new(10.0, 20.0, 0.0));
113        let map_frame = compose_project_frame(&operation, project_frame).expect("composes");
114
115        let mapped = map_frame.transform_point3(Point3::ZERO);
116        assert_eq!(mapped, Vec3::new(1010.0, 2020.0, 50.0));
117    }
118
119    #[test]
120    fn refuses_a_singular_project_frame() {
121        let model = model_with_map_conversion();
122        let operation = resolve_project_to_map(&model, id(4), 1.0).expect("resolves");
123
124        // A degenerate frame that collapses the Y axis to zero.
125        let singular = Transform3::from_mat3_translation(
126            Mat3::from_cols(
127                Vec3::new(1.0, 0.0, 0.0),
128                Vec3::ZERO,
129                Vec3::new(0.0, 0.0, 1.0),
130            ),
131            Vec3::ZERO,
132        );
133
134        assert!(matches!(
135            compose_project_frame(&operation, singular),
136            Err(GeorefError::DegenerateProjectFrame)
137        ));
138    }
139
140    #[test]
141    fn composition_order_applies_the_project_frame_before_the_map_operation() {
142        let model = model_with_map_conversion();
143        let operation = resolve_project_to_map(&model, id(4), 1.0).expect("resolves");
144
145        // A project frame that rotates 90 degrees about Z before translating.
146        let rotated = Transform3::from_mat3_translation(
147            Mat3::from_cols(Vec3::new(0.0, 1.0, 0.0), Vec3::new(-1.0, 0.0, 0.0), Vec3::Z),
148            Vec3::new(5.0, 0.0, 0.0),
149        );
150        let map_frame = compose_project_frame(&operation, rotated).expect("composes");
151
152        // A point one unit along local X ends up rotated, then translated by
153        // the frame, then carried through the (unrotated) map conversion.
154        let mapped = map_frame.transform_point3(Point3::new(1.0, 0.0, 0.0));
155        assert_eq!(mapped, Vec3::new(1005.0, 2001.0, 50.0));
156    }
157}