Skip to main content

ifc_geometry/solid/tessellated/
irregular_network.rs

1//! `IfcTriangulatedIrregularNetwork`: an IFC4X3 terrain mesh.
2//!
3//! The entity is a subtype of `IfcTriangulatedFaceSet` that adds exactly one
4//! attribute, `Flags : LIST [1:?] OF IfcInteger`, and the `NotClosed` rule
5//! (`Closed = FALSE`). Every inherited slot reads as on the supertype, so
6//! [`TriangulatedIrregularNetwork::face_set`] hands out the supertype's view.
7//!
8//! # What the flags mean
9//!
10//! The EXPRESS source types `Flags` only as integers. Their meaning comes
11//! from the IFC 4.3 documentation (buildingSMART `IFC4.3.x-development`,
12//! `IfcTriangulatedIrregularNetwork.md` at `fb8f62fa`), one value per triangle:
13//! `-2` invisible void, `-1` invisible hole, `0` no breaklines, and `1` to `7`
14//! a bit set of breaklines on edges 1, 2 and 3. A void excludes the triangle;
15//! a hole excludes it but lets another surface fill the gap.
16//!
17//! A breakline marks an edge the triangulation already has, so the triangle
18//! surface is the same with or without it. An excluded triangle is not: the
19//! surface has a gap there. [`TriangulatedIrregularNetwork::admit`] therefore
20//! admits a network whose flags are all breakline codes and refuses one with
21//! a void, a hole, or an undocumented value.
22
23use crate::error::GeometryResult;
24use crate::slots::Slots;
25use ifc_model::{Entity, EntityId};
26
27use super::{int_list, TriangulatedFaceSet};
28
29/// The STEP type name.
30pub const TYPE: &str = "IFCTRIANGULATEDIRREGULARNETWORK";
31
32/// `IfcTriangulatedIrregularNetwork` attribute slots.
33///
34/// IFC4X3_ADD2: the five `IfcTriangulatedFaceSet` slots, then `Flags`.
35pub(crate) mod slot {
36    /// `Flags : LIST [1:?] OF IfcInteger`, absolute slot 5.
37    pub const FLAGS: usize = 5;
38}
39
40/// Refusal for a void or hole triangle.
41pub const EXCLUDED_TRIANGLE: &str = "a Flags value is -1 (hole) or -2 (void); the triangle is \
42     excluded from the surface, and the neutral mesh has no face-exclusion or fall-back channel";
43
44/// Refusal for a flag outside the documented codes.
45pub const UNDOCUMENTED_FLAG: &str =
46    "a Flags value is outside the documented codes -2 to 7, so its meaning is unknown";
47
48/// `IfcTriangulatedIrregularNetwork`: a triangulated face set with per-triangle flags.
49#[derive(Debug, Clone, Copy)]
50pub struct TriangulatedIrregularNetwork<'m> {
51    slots: Slots<'m>,
52}
53
54impl<'m> TriangulatedIrregularNetwork<'m> {
55    /// Wrap an entity assumed to be an `IfcTriangulatedIrregularNetwork`.
56    pub fn new(id: EntityId, entity: &'m Entity) -> Self {
57        Self {
58            slots: Slots::new(id, entity),
59        }
60    }
61
62    /// The entity id.
63    pub fn id(&self) -> EntityId {
64        self.slots.id()
65    }
66
67    /// The inherited `IfcTriangulatedFaceSet` attributes.
68    pub fn face_set(&self) -> TriangulatedFaceSet<'m> {
69        TriangulatedFaceSet::new(self.slots.id(), self.slots.entity())
70    }
71
72    /// `Flags` exactly as written, one value per triangle.
73    pub fn flags(&self) -> GeometryResult<Vec<i64>> {
74        let value = self.slots.req(slot::FLAGS, "Flags")?;
75        int_list(value.unwrap_typed())
76            .ok_or_else(|| self.slots.degenerate("Flags is not a list of integers"))
77    }
78
79    /// Admit the network for lowering as its triangle surface, or refuse it.
80    ///
81    /// Breakline codes (`0` to `7`) are admitted: they mark existing edges and
82    /// leave the surface unchanged. Voids and holes are refused because the
83    /// surface excludes those triangles. Undocumented codes are refused.
84    ///
85    /// # Errors
86    ///
87    /// `Degenerate` when `Flags` does not hold one value per triangle;
88    /// `Unsupported` for a void, a hole or an undocumented code.
89    pub fn admit(&self, triangles: usize) -> GeometryResult<()> {
90        let flags = self.flags()?;
91        if flags.len() != triangles {
92            return Err(self.slots.degenerate(format!(
93                "Flags has {} values but CoordIndex declares {triangles} triangles",
94                flags.len()
95            )));
96        }
97        if flags.iter().any(|flag| !(-2..=7).contains(flag)) {
98            return Err(self.slots.unsupported(UNDOCUMENTED_FLAG));
99        }
100        if flags.iter().any(|flag| *flag < 0) {
101            return Err(self.slots.unsupported(EXCLUDED_TRIANGLE));
102        }
103        Ok(())
104    }
105}
106
107#[cfg(test)]
108mod tests {
109    use super::*;
110    use crate::solid::testkit::{entity, int_grid as grid, ints, r};
111    use crate::GeometryError;
112    use ifc_model::Value;
113
114    fn network(flags: &[i64]) -> Entity {
115        entity(
116            TYPE,
117            vec![
118                r(50),
119                Value::Null,
120                Value::Bool(false),
121                grid(&[&[1, 2, 3], &[1, 3, 4]]),
122                Value::Null,
123                ints(flags),
124            ],
125        )
126    }
127
128    #[test]
129    fn inherited_slots_read_through_the_face_set_view() {
130        let e = network(&[0, 0]);
131        let view = TriangulatedIrregularNetwork::new(EntityId(1), &e);
132        assert_eq!(view.face_set().coordinates().unwrap(), EntityId(50));
133        assert_eq!(view.face_set().closed(), Some(false));
134        assert_eq!(view.flags().unwrap(), vec![0, 0]);
135    }
136
137    #[test]
138    fn breakline_codes_are_admitted() {
139        for flags in [[0, 0], [1, 7], [3, 4]] {
140            let e = network(&flags);
141            TriangulatedIrregularNetwork::new(EntityId(1), &e)
142                .admit(2)
143                .unwrap_or_else(|error| panic!("{flags:?} must be admitted: {error}"));
144        }
145    }
146
147    #[test]
148    fn voids_holes_and_unknown_codes_are_typed_refusals() {
149        for (flags, detail) in [
150            ([0, -1], EXCLUDED_TRIANGLE),
151            ([-2, 0], EXCLUDED_TRIANGLE),
152            ([8, 0], UNDOCUMENTED_FLAG),
153            ([0, -3], UNDOCUMENTED_FLAG),
154        ] {
155            let e = network(&flags);
156            let error = TriangulatedIrregularNetwork::new(EntityId(4), &e)
157                .admit(2)
158                .expect_err("must refuse");
159            assert!(
160                matches!(&error, GeometryError::Unsupported { detail: d, .. } if *d == detail),
161                "{flags:?}: {error}"
162            );
163        }
164    }
165
166    #[test]
167    fn a_flag_count_that_disagrees_with_the_triangles_is_degenerate() {
168        let e = network(&[0]);
169        let error = TriangulatedIrregularNetwork::new(EntityId(4), &e)
170            .admit(2)
171            .expect_err("one flag for two triangles");
172        assert!(matches!(error, GeometryError::Degenerate { .. }), "{error}");
173    }
174}