ifc_spatial/lib.rs
1//! `ifc-spatial` — containment and objectified relationship traversal.
2//!
3//! # The problem
4//!
5//! IFC stores no parent pointers. A wall does not name its storey; a separate
6//! `IfcRelContainedInSpatialStructure` entity names both ends. Asking "which
7//! elements are on this storey" therefore means finding relationship entities
8//! and reading the right attribute slot — and the two relationships that build
9//! the tree **disagree about which slot is which**:
10//!
11//! ```text
12//! IfcRelAggregates 4 = RelatingObject 5 = RelatedObjects
13//! IfcRelContainedInSpatialStructure 4 = RelatedElements 5 = RelatingStructure
14//! ```
15//!
16//! Assuming a uniform layout inverts containment silently: elements become the
17//! parents of their storey, and every downstream answer is wrong in a way no
18//! type error catches.
19//!
20//! # Example
21//!
22//! ```no_run
23//! use ifc_spatial::{SpatialKind, SpatialTree};
24//! # let model = ifc_model::Model::new();
25//!
26//! let tree = SpatialTree::build(&model);
27//!
28//! for storey in tree.of_kind(SpatialKind::Storey) {
29//! let elements = tree.elements_of(storey.id);
30//! println!("storey {:?} holds {} elements", storey.id, elements.len());
31//! }
32//! ```
33//!
34//! # Tolerating real files
35//!
36//! The canonical hierarchy is project → site → building → storey → element, and
37//! real exports deviate: omitted sites, elements hung directly off a building,
38//! duplicate storeys, relationships naming entities that are not in the file.
39//! The tree records what the file says and reports anomalies through
40//! [`SpatialTree::orphans`] and [`SpatialTree::dangling`] rather than asserting
41//! the ideal shape or panicking.
42//!
43//! # Boundaries
44//!
45//! This crate reads containment. It does not validate it — `ifc-validate` owns
46//! WHERE rules and cardinality — and it does not interpret geometry or
47//! properties of the elements it groups.
48//!
49//! # Releases
50//!
51//! The release features (`ifc2x3`, `ifc4`, `ifc4x1`, `ifc4x2`, `ifc4x3`, all
52//! on by default) choose which schema tables are linked. Classification needs
53//! one of the three it is verified against -- IFC2X3, IFC4 or IFC4X3 --
54//! because without a table nothing would classify as a container and every
55//! tree would be silently empty; a build naming none of them is refused at
56//! compile time.
57
58#[cfg(not(any(feature = "ifc2x3", feature = "ifc4", feature = "ifc4x3")))]
59compile_error!(
60 "ifc-spatial classifies containers from a release's schema table: enable \
61 at least one of the features `ifc2x3`, `ifc4` or `ifc4x3` (through \
62 `openbim-ifc`: `schema` or one of those release features)"
63);
64
65pub mod authoring;
66pub mod relation;
67mod tree;
68
69pub use relation::{
70 BoundaryExposure, BoundaryPhysicality, ConnectionGeometryAnomaly, Relationship,
71 RelationshipIndex, RelationshipKind, SpaceBoundary,
72};
73pub use tree::{SpatialAnomaly, SpatialKind, SpatialNode, SpatialTree};
74
75/// The IFC release a tree classifies against (re-exported from `ifc-schema`).
76pub use ifc_schema::SchemaVersion;
77
78pub mod facility;
79
80pub use facility::{
81 create_facility, create_facility_with_owner_history, Facility, FacilityDraft, FacilityError,
82 FacilityResult,
83};
84
85pub use authoring::{
86 aggregate, aggregate_with_owner_history, connect_path_elements,
87 connect_path_elements_with_owner_history, contain, contain_with_owner_history,
88 create_external_spatial_element, create_external_spatial_element_with_owner_history,
89 create_project, create_project_library, create_project_library_with_owner_history,
90 create_project_with_owner_history, create_space_boundary,
91 create_space_boundary_with_owner_history, create_spatial_element,
92 create_spatial_element_with_owner_history, BoundaryDraft, BoundaryLevel, ExternalSpatialDraft,
93 ProjectLibraryDraft, SpatialAuthoringError, SpatialAuthoringResult, SpatialDraft,
94};