Skip to main content

ifc_geometry/constraint/grid/
mod.rs

1//! `IfcGrid` placement: positioning against construction grid axes.
2//!
3//! Structural and architectural drawings lay out elements against a grid
4//! ("column at C-4") rather than by coordinate. `IfcGridPlacement` encodes
5//! that directly, so the placement is *derived* from two axis curves rather
6//! than stated as a transform.
7//!
8//! # Why this is not just another placement
9//!
10//! [`super::local::LocalPlacement`] composes stored transforms. A grid
11//! placement has no stored transform at all: the position is the intersection
12//! of two curves, which must be computed. The views here read the inputs;
13//! the placement chain walk ([`super::local::PlacementResolver`]) computes
14//! the frame (#362): straight axes in closed form, curved ones through a
15//! caller-supplied curve evaluator or a typed refusal.
16//!
17//! # Attribute layout differs by release
18//!
19//! IFC4.3 moved `PlacementRelTo` from `IfcLocalPlacement` up to
20//! `IfcObjectPlacement` ("IFC4.3.0.0-CHANGE In IFC 4.3 the PlacementRelTo
21//! attribute has been moved from IfcLocalPlacement to its supertype
22//! IfcObjectPlacement"), so an `IfcGridPlacement` has three attributes in
23//! IFC4X3 ADD2 (`PlacementRelTo`, `PlacementLocation`,
24//! `PlacementRefDirection`) and two in IFC2X3 TC1 and IFC4 ADD2 TC1
25//! (`PlacementLocation`, `PlacementRefDirection`). Both layouts are fixed
26//! length, so [`GridPlacement`] reads the layout from the instance's
27//! attribute count rather than guessing from `FILE_SCHEMA`.
28
29use crate::error::GeometryResult;
30use crate::slots::Slots;
31use ifc_model::{Entity, EntityId};
32
33#[cfg(feature = "compile")]
34mod curved;
35pub(crate) mod resolve;
36
37/// `IfcGridAxis` attribute slots.
38pub(crate) mod axis_slot {
39    /// `AxisTag`: the label, e.g. `C` or `4`.
40    pub const AXIS_TAG: usize = 0;
41    /// `AxisCurve`: the curve the axis follows.
42    pub const AXIS_CURVE: usize = 1;
43    /// `SameSense`: whether the curve direction agrees with the axis.
44    pub const SAME_SENSE: usize = 2;
45}
46
47/// `IfcVirtualGridIntersection` attribute slots.
48pub(crate) mod intersection_slot {
49    /// `IntersectingAxes`: exactly two `IfcGridAxis`.
50    pub const INTERSECTING_AXES: usize = 0;
51    /// `OffsetDistances`: two or three offsets from the intersection.
52    pub const OFFSET_DISTANCES: usize = 1;
53}
54
55/// `IfcGridPlacement` attribute slots, IFC2X3 TC1 and IFC4 ADD2 TC1 layout.
56///
57/// IFC4X3 ADD2 prepends the inherited `PlacementRelTo`, shifting both by
58/// one; see [`GridPlacement`].
59pub(crate) mod placement_slot {
60    /// `PlacementLocation`: the grid intersection.
61    pub const PLACEMENT_LOCATION: usize = 0;
62    /// `PlacementRefDirection`: optional direction reference.
63    pub const PLACEMENT_REF_DIRECTION: usize = 1;
64    /// Attribute count of the IFC4X3 ADD2 layout, whose slot 0 is the
65    /// inherited `PlacementRelTo`.
66    pub const IFC4X3_ARITY: usize = 3;
67}
68
69/// `IfcGrid` attribute slots: after the seven `IfcProduct` attributes in
70/// IFC2X3 TC1, IFC4 ADD2 TC1 and IFC4X3 ADD2 alike.
71pub(crate) mod grid_slot {
72    /// `UAxes`.
73    pub const U_AXES: usize = 7;
74    /// `VAxes`.
75    pub const V_AXES: usize = 8;
76    /// `WAxes`, optional.
77    pub const W_AXES: usize = 9;
78}
79
80/// A borrowed view of an `IfcGridAxis`.
81#[derive(Debug, Clone, Copy)]
82pub struct GridAxis<'m> {
83    slots: Slots<'m>,
84}
85
86impl<'m> GridAxis<'m> {
87    /// Wrap an entity assumed to be an `IfcGridAxis`.
88    pub fn new(id: EntityId, entity: &'m Entity) -> Self {
89        Self {
90            slots: Slots::new(id, entity),
91        }
92    }
93
94    /// The entity id.
95    pub fn id(&self) -> EntityId {
96        self.slots.id()
97    }
98
99    /// The axis label, e.g. `C` or `4`.
100    pub fn tag(&self) -> Option<&'m str> {
101        self.slots.opt(axis_slot::AXIS_TAG)?.as_text()
102    }
103
104    /// The curve this axis follows.
105    pub fn curve(&self) -> GeometryResult<EntityId> {
106        self.slots.req_ref(axis_slot::AXIS_CURVE, "AxisCurve")
107    }
108
109    /// Whether the axis direction agrees with its curve's direction.
110    ///
111    /// Required by the schema, but defaulted to `true` when a file omits it:
112    /// a missing sense flag should not make a grid unusable.
113    pub fn same_sense(&self) -> bool {
114        self.slots.opt_bool(axis_slot::SAME_SENSE).unwrap_or(true)
115    }
116}
117
118/// A borrowed view of an `IfcVirtualGridIntersection`.
119///
120/// "Virtual" because the axes need not physically cross: the intersection is a
121/// computed point, optionally offset.
122#[derive(Debug, Clone, Copy)]
123pub struct VirtualGridIntersection<'m> {
124    slots: Slots<'m>,
125}
126
127impl<'m> VirtualGridIntersection<'m> {
128    /// Wrap an entity assumed to be an `IfcVirtualGridIntersection`.
129    pub fn new(id: EntityId, entity: &'m Entity) -> Self {
130        Self {
131            slots: Slots::new(id, entity),
132        }
133    }
134
135    /// The entity id.
136    pub fn id(&self) -> EntityId {
137        self.slots.id()
138    }
139
140    /// The two intersecting axes.
141    ///
142    /// The schema constrains this to exactly two; a file with a different
143    /// count is returned as-is so the caller can report it rather than having
144    /// the truth hidden here.
145    pub fn axes(&self) -> GeometryResult<Vec<EntityId>> {
146        self.slots
147            .req_ref_list(intersection_slot::INTERSECTING_AXES, "IntersectingAxes")
148    }
149
150    /// Offsets from the computed intersection.
151    ///
152    /// Two or three values: along the first axis, along the second, and
153    /// optionally along Z. In the file's length unit, so unconverted.
154    pub fn offsets(&self) -> GeometryResult<Vec<f64>> {
155        self.slots
156            .req_f64_list(intersection_slot::OFFSET_DISTANCES, "OffsetDistances")
157    }
158}
159
160/// A borrowed view of an `IfcGridPlacement`, in either release layout.
161#[derive(Debug, Clone, Copy)]
162pub struct GridPlacement<'m> {
163    slots: Slots<'m>,
164    /// 1 for the IFC4X3 layout, whose slot 0 is `PlacementRelTo`; else 0.
165    shift: usize,
166}
167
168impl<'m> GridPlacement<'m> {
169    /// Wrap an entity assumed to be an `IfcGridPlacement`.
170    ///
171    /// Three attributes is the IFC4X3 ADD2 layout; anything else is read as
172    /// the IFC2X3/IFC4 one (module documentation).
173    pub fn new(id: EntityId, entity: &'m Entity) -> Self {
174        let shift = usize::from(entity.attributes.len() == placement_slot::IFC4X3_ARITY);
175        Self {
176            slots: Slots::new(id, entity),
177            shift,
178        }
179    }
180
181    /// The entity id.
182    pub fn id(&self) -> EntityId {
183        self.slots.id()
184    }
185
186    /// The stated `PlacementRelTo`: only IFC4X3 declares it on a grid
187    /// placement, where it "will reference ... the ObjectPlacement of the
188    /// IfcGrid".
189    pub fn placement_rel_to(&self) -> Option<EntityId> {
190        if self.shift == 0 {
191            return None;
192        }
193        self.slots.opt_ref(0)
194    }
195
196    /// The grid intersection this placement sits at.
197    pub fn location(&self) -> GeometryResult<EntityId> {
198        self.slots.req_ref(
199            placement_slot::PLACEMENT_LOCATION + self.shift,
200            "PlacementLocation",
201        )
202    }
203
204    /// Optional reference direction.
205    ///
206    /// `IfcGridPlacementDirectionSelect`: either an `IfcDirection` or a second
207    /// `IfcVirtualGridIntersection` pointing at it. Returned as a raw id
208    /// because the caller must dispatch on the target's type.
209    pub fn ref_direction(&self) -> Option<EntityId> {
210        self.slots
211            .opt_ref(placement_slot::PLACEMENT_REF_DIRECTION + self.shift)
212    }
213}
214
215#[cfg(test)]
216mod tests {
217    use super::*;
218    use ifc_model::Value;
219
220    #[test]
221    fn reads_axis_tag_and_curve() {
222        let e = Entity::new(
223            "IFCGRIDAXIS",
224            vec![
225                Value::Text("C".into()),
226                Value::Ref(EntityId(5)),
227                Value::Bool(true),
228            ],
229        );
230        let axis = GridAxis::new(EntityId(1), &e);
231        assert_eq!(axis.tag(), Some("C"));
232        assert_eq!(axis.curve().unwrap(), EntityId(5));
233        assert!(axis.same_sense());
234    }
235
236    /// A missing sense flag must not make the grid unusable.
237    #[test]
238    fn absent_same_sense_defaults_to_true() {
239        let e = Entity::new(
240            "IFCGRIDAXIS",
241            vec![
242                Value::Text("4".into()),
243                Value::Ref(EntityId(5)),
244                Value::Null,
245            ],
246        );
247        assert!(GridAxis::new(EntityId(1), &e).same_sense());
248    }
249
250    #[test]
251    fn reads_intersection_axes_and_offsets() {
252        let e = Entity::new(
253            "IFCVIRTUALGRIDINTERSECTION",
254            vec![
255                Value::List(vec![Value::Ref(EntityId(1)), Value::Ref(EntityId(2))]),
256                Value::List(vec![Value::Real(0.5), Value::Real(-0.25)]),
257            ],
258        );
259        let x = VirtualGridIntersection::new(EntityId(3), &e);
260        assert_eq!(x.axes().unwrap().len(), 2);
261        assert_eq!(x.offsets().unwrap(), vec![0.5, -0.25]);
262    }
263
264    #[test]
265    fn ref_direction_is_optional() {
266        let e = Entity::new(
267            "IFCGRIDPLACEMENT",
268            vec![Value::Ref(EntityId(9)), Value::Null],
269        );
270        let p = GridPlacement::new(EntityId(1), &e);
271        assert_eq!(p.location().unwrap(), EntityId(9));
272        assert_eq!(p.ref_direction(), None);
273        assert_eq!(p.placement_rel_to(), None);
274    }
275
276    /// IFC4X3 ADD2 prepends the inherited `PlacementRelTo`.
277    #[test]
278    fn the_ifc4x3_layout_reads_placement_rel_to_first() {
279        let e = Entity::new(
280            "IFCGRIDPLACEMENT",
281            vec![
282                Value::Ref(EntityId(7)),
283                Value::Ref(EntityId(9)),
284                Value::Ref(EntityId(11)),
285            ],
286        );
287        let p = GridPlacement::new(EntityId(1), &e);
288        assert_eq!(p.placement_rel_to(), Some(EntityId(7)));
289        assert_eq!(p.location().unwrap(), EntityId(9));
290        assert_eq!(p.ref_direction(), Some(EntityId(11)));
291    }
292}