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}