Skip to main content

ifc_geometry/lower/
connection.rs

1//! Connection-surface lowering: the surface where two elements meet.
2//!
3//! # Why a helper and not a representation item
4//!
5//! `IfcConnectionSurfaceGeometry` is not a representation item. It is what
6//! `IfcRelSpaceBoundary.ConnectionGeometry` and the element-connection
7//! relationships point at, and its payload is an `IfcSurfaceOrFaceSurface`:
8//! a bare `IfcSurface`, an `IfcFaceSurface` (or its `IfcAdvancedFace`
9//! subtype), or an `IfcFaceBasedSurfaceModel`. The select is resolved here so
10//! a consumer measuring space-boundary coverage does not re-derive it, and
11//! each member goes through the lowerer that already owns its family.
12//!
13//! # Two ends, two coordinate systems
14//!
15//! `SurfaceOnRelatingElement` is given in the relating element's local
16//! coordinate system, the optional `SurfaceOnRelatedElement` in the related
17//! element's (IFC4 ADD2 TC1, `IfcConnectionSurfaceGeometry` attribute
18//! definitions). One frame cannot place both, so each end has its own entry
19//! point and the caller passes the placement of the element that end belongs
20//! to. For a space boundary that is the space's placement.
21//!
22//! # Only surfaces
23//!
24//! The point, curve, volume and (IFC2X3) port connection kinds are legal
25//! connection geometry but carry no surface. They are refused with a typed
26//! [`crate::GeometryError::Unsupported`] naming the connection, never
27//! substituted by a degenerate or bounding surface. Anything that is not a
28//! connection geometry at all is a wrong-type error.
29//!
30//! Slots are identical in IFC2X3 TC1, IFC4 ADD2 TC1 and IFC4X3 ADD2:
31//! `IfcConnectionGeometry` declares no attributes, so
32//! `SurfaceOnRelatingElement` is 0 and `SurfaceOnRelatedElement` is 1
33//! (`data/absolute-slots.txt`).
34
35use axiolid_model::NodeId;
36use ifc_model::EntityId;
37
38use crate::constraint::connection::slot;
39use crate::error::{GeometryError, GeometryResult};
40use crate::lower::brep::lower_face_surface_node;
41use crate::lower::collection::lower_collection_node;
42use crate::lower::session::LoweringSession;
43use crate::lower::surface::lower_surface_node;
44use crate::select::SurfaceOrFaceSurface;
45use crate::transform::Transform;
46
47/// The accepted connection type; every other one is classified below.
48const SURFACE_CONNECTION: &str = "IFCCONNECTIONSURFACEGEOMETRY";
49
50/// Connection kinds that are valid IFC but carry no surface, with the reason.
51///
52/// `IFCCONNECTIONPORTGEOMETRY` exists only in IFC2X3 TC1, and
53/// `IFCCONNECTIONVOLUMEGEOMETRY` only from IFC4 on; both are listed so a file
54/// of either release gets a typed refusal rather than a wrong-type error.
55const REFUSED: &[(&str, &str)] = &[
56    (
57        "IFCCONNECTIONPOINTGEOMETRY",
58        "a point connection carries a point or vertex point, not a surface",
59    ),
60    (
61        "IFCCONNECTIONPOINTECCENTRICITY",
62        "an eccentric point connection carries a point or vertex point, not a surface",
63    ),
64    (
65        "IFCCONNECTIONCURVEGEOMETRY",
66        "a curve connection carries a curve or edge curve, not a surface",
67    ),
68    (
69        "IFCCONNECTIONVOLUMEGEOMETRY",
70        "a volume connection carries a solid or shell, not a surface",
71    ),
72    (
73        "IFCCONNECTIONPORTGEOMETRY",
74        "an IFC2X3 port connection carries a placement and a profile, not a surface",
75    ),
76];
77
78/// Lower `SurfaceOnRelatingElement` of an `IfcConnectionSurfaceGeometry`.
79///
80/// `frame` is the RELATING element's placement: the surface is authored in
81/// that element's local coordinate system. Returns the node of the lowered
82/// surface, face surface (a single-face open `BRep`), or face-based surface
83/// model (a `Collection` of open shells).
84///
85/// # Errors
86///
87/// - [`GeometryError::Unsupported`] naming `id` for a point, curve, volume
88///   or port connection.
89/// - [`GeometryError::WrongEntityType`] when `id` is not a connection
90///   geometry, or the surface is not an `IfcSurfaceOrFaceSurface` member.
91/// - [`GeometryError::MissingEntity`] for a dangling `id` or surface
92///   reference, and [`GeometryError::MissingAttribute`] when the required
93///   surface is `$`.
94/// - Any error of the member's own lowerer.
95pub fn lower_connection_surface(
96    session: &mut LoweringSession<'_>,
97    id: EntityId,
98    frame: Transform,
99) -> GeometryResult<NodeId> {
100    check_connection(session, id)?;
101    let target = session
102        .slots(id)?
103        .req_ref(slot::AT_RELATING, "SurfaceOnRelatingElement")?;
104    lower_surface_or_face_surface(session, id, target, frame)
105}
106
107/// Lower the optional `SurfaceOnRelatedElement` of an
108/// `IfcConnectionSurfaceGeometry`.
109///
110/// `frame` is the RELATED element's placement. Returns `Ok(None)` when the
111/// file omits the attribute: the schema then means "the relating surface is
112/// the whole statement", and inventing a copy in another frame would place it
113/// wrongly.
114///
115/// # Errors
116///
117/// As [`lower_connection_surface`]; a present value that is not an entity
118/// reference is [`GeometryError::WrongValueKind`].
119pub fn lower_related_connection_surface(
120    session: &mut LoweringSession<'_>,
121    id: EntityId,
122    frame: Transform,
123) -> GeometryResult<Option<NodeId>> {
124    check_connection(session, id)?;
125    let slots = session.slots(id)?;
126    if slots.opt(slot::AT_RELATED).is_none() {
127        return Ok(None);
128    }
129    let target = slots.req_ref(slot::AT_RELATED, "SurfaceOnRelatedElement")?;
130    lower_surface_or_face_surface(session, id, target, frame).map(Some)
131}
132
133/// Accept a surface connection; refuse every other kind with its reason.
134fn check_connection(session: &LoweringSession<'_>, id: EntityId) -> GeometryResult<()> {
135    let type_name = session.type_name(id)?;
136    if type_name == SURFACE_CONNECTION {
137        return Ok(());
138    }
139    if let Some((_, reason)) = REFUSED.iter().find(|(name, _)| *name == type_name) {
140        return Err(session.unsupported(id, &type_name, reason));
141    }
142    Err(GeometryError::WrongEntityType {
143        entity: id,
144        actual: type_name,
145        expected: "IfcConnectionSurfaceGeometry",
146    })
147}
148
149/// Route one `IfcSurfaceOrFaceSurface` member to the lowerer owning it.
150///
151/// Resolution checks the face surface before the plain surface: the select
152/// helper classifies most-derived first, so an `IfcAdvancedFace` reaches the
153/// face path with its bounds rather than only its carrier surface.
154fn lower_surface_or_face_surface(
155    session: &mut LoweringSession<'_>,
156    referrer: EntityId,
157    target: EntityId,
158    frame: Transform,
159) -> GeometryResult<NodeId> {
160    match SurfaceOrFaceSurface::resolve(session.model(), referrer, target)? {
161        SurfaceOrFaceSurface::Surface(surface) => lower_surface_node(session, surface, frame),
162        SurfaceOrFaceSurface::FaceSurface(face) => lower_face_surface_node(session, face, frame),
163        SurfaceOrFaceSurface::FaceBasedSurfaceModel(model) => {
164            lower_collection_node(session, model, frame)
165        }
166    }
167}