Skip to main content

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}