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}