ifc-spatial 0.5.0

//! `ifc-spatial` — containment and objectified relationship traversal.
//!
//! # The problem
//!
//! IFC stores no parent pointers. A wall does not name its storey; a separate
//! `IfcRelContainedInSpatialStructure` entity names both ends. Asking "which
//! elements are on this storey" therefore means finding relationship entities
//! and reading the right attribute slot — and the two relationships that build
//! the tree **disagree about which slot is which**:
//!
//! ```text
//! IfcRelAggregates                    4 = RelatingObject   5 = RelatedObjects
//! IfcRelContainedInSpatialStructure   4 = RelatedElements  5 = RelatingStructure
//! ```
//!
//! Assuming a uniform layout inverts containment silently: elements become the
//! parents of their storey, and every downstream answer is wrong in a way no
//! type error catches.
//!
//! # Example
//!
//! ```no_run
//! use ifc_spatial::{SpatialKind, SpatialTree};
//! # let model = ifc_model::Model::new();
//!
//! let tree = SpatialTree::build(&model);
//!
//! for storey in tree.of_kind(SpatialKind::Storey) {
//!     let elements = tree.elements_of(storey.id);
//!     println!("storey {:?} holds {} elements", storey.id, elements.len());
//! }
//! ```
//!
//! # Tolerating real files
//!
//! The canonical hierarchy is project → site → building → storey → element, and
//! real exports deviate: omitted sites, elements hung directly off a building,
//! duplicate storeys, relationships naming entities that are not in the file.
//! The tree records what the file says and reports anomalies through
//! [`SpatialTree::orphans`] and [`SpatialTree::dangling`] rather than asserting
//! the ideal shape or panicking.
//!
//! # Boundaries
//!
//! This crate reads containment. It does not validate it — `ifc-validate` owns
//! WHERE rules and cardinality — and it does not interpret geometry or
//! properties of the elements it groups.
//!
//! # Releases
//!
//! The release features (`ifc2x3`, `ifc4`, `ifc4x1`, `ifc4x2`, `ifc4x3`, all
//! on by default) choose which schema tables are linked. Classification needs
//! one of the three it is verified against -- IFC2X3, IFC4 or IFC4X3 --
//! because without a table nothing would classify as a container and every
//! tree would be silently empty; a build naming none of them is refused at
//! compile time.

#[cfg(not(any(feature = "ifc2x3", feature = "ifc4", feature = "ifc4x3")))]
compile_error!(
    "ifc-spatial classifies containers from a release's schema table: enable \
     at least one of the features `ifc2x3`, `ifc4` or `ifc4x3` (through \
     `openbim-ifc`: `schema` or one of those release features)"
);

pub mod authoring;
pub mod relation;
mod tree;

pub use relation::{
    BoundaryExposure, BoundaryPhysicality, ConnectionGeometryAnomaly, Relationship,
    RelationshipIndex, RelationshipKind, SpaceBoundary,
};
pub use tree::{SpatialAnomaly, SpatialKind, SpatialNode, SpatialTree};

/// The IFC release a tree classifies against (re-exported from `ifc-schema`).
pub use ifc_schema::SchemaVersion;

pub mod facility;

pub use facility::{
    create_facility, create_facility_with_owner_history, Facility, FacilityDraft, FacilityError,
    FacilityResult,
};

pub use authoring::{
    aggregate, aggregate_with_owner_history, connect_path_elements,
    connect_path_elements_with_owner_history, contain, contain_with_owner_history,
    create_external_spatial_element, create_external_spatial_element_with_owner_history,
    create_project, create_project_library, create_project_library_with_owner_history,
    create_project_with_owner_history, create_space_boundary,
    create_space_boundary_with_owner_history, create_spatial_element,
    create_spatial_element_with_owner_history, BoundaryDraft, BoundaryLevel, ExternalSpatialDraft,
    ProjectLibraryDraft, SpatialAuthoringError, SpatialAuthoringResult, SpatialDraft,
};