ifc_georef/site/elevation.rs
1//! Comparing `IfcSite.RefElevation` with the map height of the site origin.
2//!
3//! The rule and its spec basis are documented on the parent module.
4
5use ifc_model::EntityId;
6use ifc_schema::SchemaVersion;
7
8use super::reference::SiteReference;
9use crate::conversion::ProjectToMap;
10use crate::error::{GeorefError, GeorefResult};
11
12/// Suggested tolerance, in metres, for [`relate_site_elevation`]: 1 cm.
13///
14/// Above the rounding a millimetre, foot or inch unit round trip
15/// introduces, yet fine enough that a wrong or mismatched height datum is
16/// not absorbed as noise. A caller with its own survey requirements passes
17/// its own tolerance.
18pub const SITE_ELEVATION_TOLERANCE_M: f64 = 0.01;
19
20/// Both heights of the site origin, in metres, and how far apart they are.
21#[non_exhaustive]
22#[derive(Debug, Clone, PartialEq)]
23pub struct SiteElevationComparison {
24 /// The `IfcSite` compared.
25 pub site: EntityId,
26 /// `IfcSite.RefElevation`, metres.
27 pub ref_elevation: f64,
28 /// `IfcMapConversion.OrthogonalHeight`, metres: the map height of the
29 /// world coordinate system's origin.
30 pub orthogonal_height: f64,
31 /// Map height of the site origin, metres: the site origin carried
32 /// through the map conversion. Equals `orthogonal_height` for a site
33 /// origin at world height `0`.
34 pub site_origin_map_height: f64,
35 /// `ref_elevation - site_origin_map_height`, metres.
36 pub difference: f64,
37 /// The tolerance the difference was judged against, metres.
38 pub tolerance: f64,
39 /// The target `IfcProjectedCRS`.
40 pub target_crs: EntityId,
41 /// The target CRS's `VerticalDatum`, verbatim; `None` when unstated.
42 /// `RefElevation` names no datum, so the comparison assumes it is this
43 /// one; judging that is left to the caller.
44 pub vertical_datum: Option<String>,
45}
46
47/// How `IfcSite.RefElevation` relates to the map conversion's height.
48#[non_exhaustive]
49#[derive(Debug, Clone, PartialEq)]
50pub enum SiteElevationCheck {
51 /// The site states no `RefElevation`; nothing to compare.
52 RefElevationAbsent,
53 /// No map conversion was supplied (always the case under IFC2X3, which
54 /// declares none); only `RefElevation` locates the site vertically.
55 NoMapConversion,
56 /// The two heights agree within the tolerance.
57 Consistent(SiteElevationComparison),
58 /// The two heights differ by more than the tolerance. A finding, not an
59 /// error: both values are kept and neither is preferred.
60 Disagreement(SiteElevationComparison),
61}
62
63/// Relate `site.ref_elevation` to `map`'s `OrthogonalHeight` and the target
64/// CRS's `VerticalDatum`.
65///
66/// `site_origin_z` is the height of the `IfcSite` placement origin in the
67/// project's world coordinate system, in metres: `0.0` for a site placed at
68/// the world origin. `tolerance` is in metres, finite and non-negative;
69/// [`SITE_ELEVATION_TOLERANCE_M`] is the suggested value.
70///
71/// Refuses a non-finite `site_origin_z` or an invalid `tolerance` with
72/// [`GeorefError::InvalidParameter`], and a map conversion paired with an
73/// IFC2X3 site with [`GeorefError::UnsupportedSchema`].
74pub fn relate_site_elevation(
75 site: &SiteReference,
76 map: Option<&ProjectToMap>,
77 site_origin_z: f64,
78 tolerance: f64,
79) -> GeorefResult<SiteElevationCheck> {
80 if !tolerance.is_finite() || tolerance < 0.0 {
81 return Err(GeorefError::InvalidParameter {
82 name: "tolerance",
83 value: tolerance,
84 });
85 }
86 if !site_origin_z.is_finite() {
87 return Err(GeorefError::InvalidParameter {
88 name: "site_origin_z",
89 value: site_origin_z,
90 });
91 }
92 if site.version == SchemaVersion::Ifc2x3 && map.is_some() {
93 return Err(GeorefError::UnsupportedSchema {
94 token: "IFC2X3".to_owned(),
95 });
96 }
97 let Some(ref_elevation) = site.ref_elevation else {
98 return Ok(SiteElevationCheck::RefElevationAbsent);
99 };
100 let Some(map) = map else {
101 return Ok(SiteElevationCheck::NoMapConversion);
102 };
103 let orthogonal_height = map.map_point([0.0, 0.0, 0.0])[2];
104 let site_origin_map_height = map.map_point([0.0, 0.0, site_origin_z])[2];
105 let difference = ref_elevation - site_origin_map_height;
106 let comparison = SiteElevationComparison {
107 site: site.entity,
108 ref_elevation,
109 orthogonal_height,
110 site_origin_map_height,
111 difference,
112 tolerance,
113 target_crs: map.target_crs.entity,
114 vertical_datum: map.target_crs.vertical_datum.clone(),
115 };
116 Ok(if difference.abs() <= tolerance {
117 SiteElevationCheck::Consistent(comparison)
118 } else {
119 SiteElevationCheck::Disagreement(comparison)
120 })
121}