Skip to main content

ifc_geometry/rules/
mod.rs

1//! EXPRESS `WHERE` rules: the schema's own correctness conditions.
2//!
3//! # Why these are worth implementing
4//!
5//! A file can parse and still describe impossible geometry: a 2D direction
6//! on a 3D placement, a boolean between operands of different dimensionality,
7//! an extrusion parallel to the plane it extrudes. The schema states these
8//! conditions as `WHERE` rules, and they are the difference between "the
9//! parser accepted it" and "a kernel can build it".
10//!
11//! Checking them **here** rather than in the kernel matters: the kernel would
12//! discover the problem as a numerical failure deep in an algorithm, where the
13//! diagnostic is a degenerate matrix rather than "RefDirection is parallel to
14//! Axis in #4711".
15//!
16//! # Scope
17//!
18//! IFC4 declares 95 where-rules across 56 geometry entities, and all 95 are
19//! implemented, each in every bundled release that declares it, under that
20//! release's own name and text (#400; see `rules/release.rs`) (`data/ifc4-where-rules.tsv`, asserted by
21//! `tests/where_rule_inventory.rs`). The geometry entities IFC4 does not
22//! declare carry their own rules, checked in the releases that declare
23//! them (#402): IFC2X3 TC1's `Ifc2DCompositeCurve` and
24//! `IfcRationalBezierCurve`, and the linear-referencing geometry of IFC4X1
25//! on (`rules/linear.rs`). A rule whose check cannot fail on a
26//! parsed model would be kept as `inventoried`, with the reason beside the
27//! code, rather than implemented as a check that always passes.
28//!
29//! Rules do not re-check what the parser and typed views already enforce
30//! (declared types, attribute arity, SELECT membership); a rule states only
31//! the schema's own `WHERE` condition. Numerical validation of a built shape
32//! belongs to the kernel, not here.
33//!
34//! # Design
35//!
36//! A rule is a pure function from a resolved view to `Result<(), RuleViolation>`.
37//! Rules never mutate, never allocate on the success path, and are grouped by
38//! the entity they constrain. [`validate`] runs every rule that applies to an
39//! entity, so a caller checks a whole model without knowing the rule list.
40
41mod bspline;
42mod cardinality;
43mod curve;
44mod dimension;
45mod express;
46mod grid;
47mod linear;
48pub mod placement;
49mod release;
50mod scalar;
51pub mod solid;
52mod surface;
53mod typing;
54pub mod violation;
55
56pub use violation::{RuleViolation, ViolationKind};
57
58use std::collections::HashMap;
59
60use ifc_model::{Entity, EntityId, Model};
61use release::{Declared, Release, Subject};
62
63/// Run every implemented where-rule that applies to this entity.
64///
65/// The rules are the ones the model's declared release states, named as
66/// that release names them (see `rules/release.rs`).
67///
68/// Returns all violations rather than the first, because a consumer fixing a
69/// file wants the whole list, and because one bad placement often implies
70/// several related failures.
71pub fn validate(model: &Model, id: EntityId) -> Vec<RuleViolation> {
72    let Some(entity) = model.get(id) else {
73        return Vec::new();
74    };
75    let release = Release::of(model);
76    let name = entity.type_name.to_ascii_uppercase();
77    let governing = release.governing(&name);
78    let mut found = Vec::new();
79    run(
80        &Subject::new(model, &release, id, entity, &name, &governing),
81        &mut found,
82    );
83    found
84}
85
86/// Validate every entity in a model.
87///
88/// Linear in model size and allocation-free unless a rule actually fails,
89/// so it is cheap enough to run as an import-time check. The rules that
90/// govern a type are resolved once per type, not once per instance.
91pub fn validate_model(model: &Model) -> Vec<RuleViolation> {
92    let release = Release::of(model);
93    let mut governing: HashMap<String, Vec<&'static Declared>> = HashMap::new();
94    let mut found = Vec::new();
95    for (id, entity) in model.iter() {
96        let name = entity.type_name.to_ascii_uppercase();
97        if !governing.contains_key(&name) {
98            governing.insert(name.clone(), release.governing(&name));
99        }
100        let rules = &governing[&name];
101        if rules.is_empty() {
102            continue;
103        }
104        run(
105            &Subject::new(model, &release, id, entity, &name, rules),
106            &mut found,
107        );
108    }
109    found
110}
111
112/// Every rule module, for one entity in its release.
113fn run(subject: &Subject<'_>, found: &mut Vec<RuleViolation>) {
114    if !subject.is_governed() {
115        return;
116    }
117    placement::run(subject, found);
118    solid::run(subject, found);
119    grid::check(subject, found);
120    curve::check(subject, found);
121    scalar::check(subject, found);
122    cardinality::check(subject, found);
123    typing::check(subject, found);
124    surface::check(subject, found);
125    bspline::check(subject, found);
126    linear::check(subject, found);
127}
128
129/// Run one module's rules for an entity of `model`, resolving the release
130/// as [`validate`] does. Backs the public per-module `check` functions.
131fn run_one(
132    model: &Model,
133    id: EntityId,
134    entity: &Entity,
135    out: &mut Vec<RuleViolation>,
136    module: fn(&Subject<'_>, &mut Vec<RuleViolation>),
137) {
138    let release = Release::of(model);
139    let name = entity.type_name.to_ascii_uppercase();
140    let governing = release.governing(&name);
141    let subject = Subject::new(model, &release, id, entity, &name, &governing);
142    if subject.is_governed() {
143        module(&subject, out);
144    }
145}