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}