Skip to main content

openbim_ifc_binding_core/
lib.rs

1//! Host-independent core of the IFC language bindings (ADR 0013, #34).
2//!
3//! The WebAssembly, C and Python bindings each wrap [`IfcModel`] and move
4//! [`value::Tagged`] values into and out of their host. The operations, the
5//! lossless value encoding and the error codes live here once, so the three
6//! hosts cannot drift apart: a fix or a new operation lands in one place and
7//! every binding exposes it.
8//!
9//! This crate adds no IFC behaviour of its own. It is a thin, host-shaped
10//! view of `openbim-ifc`; if a binding needs more, the facade grows first.
11//!
12//! # Features
13//!
14//! Beyond the release features (`ifc2x3` ... `ifc4x3`, #112), three
15//! default features select facade capabilities that add to a browser
16//! build's size: `ifcxml` (the ifcXML codec), `validate` (schema
17//! validation) and `unreachable` (the viewer reachability lint). An
18//! operation whose feature is off still exists, so every host keeps one
19//! surface, and refuses with `feature-disabled`.
20//!
21//! Every read recognizes an ifcZIP archive by its ZIP signature and reads
22//! the STEP or ifcXML model it holds within a decompression budget
23//! ([`ifczip`], feature `zip`); [`IfcModel::write_ifczip`] writes one.
24//!
25//! Attributes are read and written by position or by name
26//! ([`IfcModel::attribute_by_name`]); a name resolves against the release
27//! the header declares, inherited attributes included, and is refused with
28//! `unknown-attribute` (or `derived-attribute` for a write to a `*` slot)
29//! rather than guessed. A by-name write also takes a plain host value
30//! ([`Plain`], #342), coerced against the attribute's declared type
31//! ([`coerce`]): a string to a label or an enumeration item, an integer to
32//! an `INTEGER` or a `REAL`, refused with `type-mismatch` when it does not
33//! fit and `ambiguous-value` when several SELECT members would take it.
34//!
35//! Property sets resolve per object ([`IfcModel::property_sets`]) or for
36//! many objects in one pass ([`IfcModel::property_sets_many`], #358), which
37//! validates the file's property relationships once rather than per object.
38//!
39//! Entities are created by type and named attributes (#330, feature
40//! `author`), alone or with the spatial, product, type and placement
41//! builders in one checked batch ([`IfcModel::author`]); a refused batch
42//! leaves the model unchanged.
43//!
44//! Geometry crosses at two levels (#328, ADR 0021): each product's world
45//! placement and selected Body representation ([`IfcModel::product_placements`],
46//! feature `placements`, default), and triangle meshes from the reference
47//! backend ([`IfcModel::product_meshes`], feature `mesh`, opt-in because it
48//! links an execution provider). A product that cannot be placed or
49//! meshed is a record with a typed refusal, never a failed call.
50//!
51//! Property edits check `Pset_`/`Qto_` sets against the PSD/QTO catalog
52//! ([`catalog`]): embedded with `property-catalog` (default), or loaded at
53//! runtime from pinned snapshot files with `property-catalog-runtime`, the
54//! npm package's choice, where a write before loading refuses with
55//! `catalog-not-loaded`.
56
57//! Entities are found by `GlobalId` ([`IfcModel::by_guid`], #463) through
58//! an index built on the first lookup and rebuilt only after an edit; a
59//! `GlobalId` several entities carry is refused with `invalid-model`, never
60//! answered with one. [`new_guid`] draws a random `GlobalId` and
61//! [`name_based_guid`] derives a reproducible one. An object's type, a
62//! type's occurrences, an element's openings and an opening's fillings
63//! and host ([`IfcModel::type_object`] and its siblings) read the
64//! relationships the declared release states.
65//!
66//! Selectors (#464, [`selector`]) filter the model by class, attribute,
67//! property, type, material, classification, location and group
68//! ([`IfcModel::select`]); values are read and written by path
69//! ([`IfcModel::get_value`], [`IfcModel::set_value`]). A query that does
70//! not parse is refused with `invalid-selector` and the byte span of the
71//! offending text ([`BindingError::span`]).
72//!
73//! Units convert between each other ([`convert_unit`],
74//! [`IfcModel::convert_unit_value`], [`format_length`], #469), and
75//! [`IfcModel::convert_length_unit`] rescales a whole model to a new
76//! project length unit as one checked transaction ([`units`]).
77//! Tables of values by path (#474, [`table`]): the entities a selector
78//! selects exported as CSV, TSV or XLSX ([`IfcModel::export_table`]), and
79//! a table applied back by `GlobalId` or id as one checked transaction
80//! ([`IfcModel::import_table`]), with every refusal by row and column and
81//! a dry run. XLSX needs feature `sheet-xlsx` (default; the browser
82//! package leaves it out and refuses with `feature-disabled`).
83//!
84//! `INVERSE` attributes read by name too ([`inverse`], #462):
85//! `attribute_by_name(wall, "IsDefinedBy")` follows the declared release's
86//! `FOR` clause through a reverse index built on first use and rebuilt
87//! only after an edit; [`IfcModel::inverse_references`] and
88//! [`IfcModel::total_inverses`] list and count every referrer.
89
90mod attribute;
91pub mod authoring;
92pub mod catalog;
93pub mod classification;
94pub mod coerce;
95pub mod cost;
96mod error;
97pub mod geometry;
98pub mod georef;
99pub mod header;
100pub mod history;
101pub mod ifczip;
102pub mod inverse;
103pub mod material;
104mod model;
105mod options;
106pub mod properties;
107pub mod property_edit;
108pub mod record;
109pub mod relations;
110pub mod selector;
111pub mod spatial;
112pub mod systems;
113pub mod table;
114pub mod units;
115pub mod unreachable;
116pub mod validation;
117pub mod value;
118mod xml;
119
120pub use attribute::AttributeInfo;
121pub use authoring::{
122    AppendOptions, AuthorOp, AuthoringResult, CopiedEntity, CopyProductOptions, CopyReport,
123    KeptEntity, PurgeOptions, RemovalReport, RemoveProductOptions, RemovedEntity,
124};
125pub use coerce::Plain;
126pub use error::BindingError;
127pub use geometry::curves::{ProductCurves, ProductPolyline};
128pub use geometry::graph::{
129    GeometryEncoding, ProductGeometry, GEOMETRY_FORMAT, GEOMETRY_FORMAT_VERSION,
130};
131pub use geometry::{
132    GeometryRefusal, ProductMesh, ProductPlacement, SelectedRepresentation, SurfaceColour,
133};
134pub use history::{HistoryChange, HistoryState};
135pub use inverse::{InverseAttributeInfo, InverseReference};
136pub use model::IfcModel;
137pub use options::{OnMalformed, ParseOptions};
138pub use record::{Field, Record, ToRecord};
139pub use relations::{name_based_guid, new_guid, DuplicateGlobalId};
140pub use selector::{canonical_selector, Selected, SELECTOR_GRAMMAR_VERSION};
141pub use table::{TableChange, TableImport, TableRefusal};
142pub use units::{
143    convert_unit, format_length, ConvertedValues, KeptValues, LengthUnitOptions, LengthUnitReport,
144};
145pub use unreachable::UnreachableProduct;
146pub use validation::{ValidationFinding, ValidationReport, ValidationSummary};