ClippingInfo util class to pass and apply plane clippings #3774

Co-Authored-By: Carlos Villagrasa <carvillasil@gmail.com>

src/ifcopenshell-python/ifcopenshell/api/geometry/add_profile_representation.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell.geom
 import ifcopenshell.util.unit
+from ifcopenshell.util.representation import ClippingInfo
 
 
 class Usecase:
@@ -28,8 +29,8 @@ class Usecase:
             "profile": None,
             "depth": 1.0,
             "cardinal_point": 5,
-            # Planes are defined as a matrix. The XY plane is the clipping boundary and +Z is removed.
+            # Planes are defined either by ClippingInfo objects
-            # [{"type": "IfcBooleanClippingResult", "operand_type": "IfcHalfSpaceSolid", "matrix": [...]}, {...}]
+            # or by dictionaries of arguments for `ClippingInfo.parse`
             "clippings": [],  # A list of planes that define clipping half space solids
             "placement_zx_axes": (None, None),
         }
@@ -38,6 +39,7 @@ class Usecase:
 
     def execute(self):
         self.settings["unit_scale"] = ifcopenshell.util.unit.calculate_unit_scale(self.file)
+        self.settings["clippings"] = [ClippingInfo.parse(c) for c in self.settings["clippings"]]
         return self.file.createIfcShapeRepresentation(
             self.settings["context"],
             self.settings["context"].ContextIdentifier,
@@ -69,25 +71,8 @@ class Usecase:
                 new = ifcopenshell.util.element.copy(self.file, clipping)
                 new.FirstOperand = first_operand
                 first_operand = new
-            elif clipping["operand_type"] == "IfcHalfSpaceSolid":
+            else:  # ClippingInfo
-                matrix = clipping["matrix"]
+                first_operand = clipping.apply(self.file, first_operand, self.settings["unit_scale"])
-                second_operand = self.file.createIfcHalfSpaceSolid(
-                    self.file.createIfcPlane(
-                        self.file.createIfcAxis2Placement3D(
-                            self.file.createIfcCartesianPoint(
-                                (
-                                    self.convert_si_to_unit(matrix[0][3]),
-                                    self.convert_si_to_unit(matrix[1][3]),
-                                    self.convert_si_to_unit(matrix[2][3]),
-                                )
-                            ),
-                            self.file.createIfcDirection((matrix[0][2], matrix[1][2], matrix[2][2])),
-                            self.file.createIfcDirection((matrix[0][0], matrix[1][0], matrix[2][0])),
-                        )
-                    ),
-                    False,
-                )
-                first_operand = self.file.create_entity(clipping["type"], "DIFFERENCE", first_operand, second_operand)
         return first_operand
 
     def convert_si_to_unit(self, co):

src/ifcopenshell-python/ifcopenshell/api/geometry/add_slab_representation.py

@@ -27,7 +27,8 @@ class Usecase:
             "context": None,  # IfcGeometricRepresentationContext
             "depth": 0.2,
             "x_angle": 0,  # Radians
-            # Planes are defined as a matrix. The XY plane is the clipping boundary and +Z is removed.
+            # Planes are defined either by ClippingInfo objects
+            # or by dictionaries of arguments for `ClippingInfo.parse`
             "clippings": [],  # A list of planes that define clipping half space solids
         }
         for key, value in settings.items():
@@ -78,23 +79,12 @@ class Usecase:
     def apply_clippings(self, first_operand):
         while self.settings["clippings"]:
             clipping = self.settings["clippings"].pop()
-            second_operand = self.file.createIfcHalfSpaceSolid(
+            if isinstance(clipping, ifcopenshell.entity_instance):
-                self.file.createIfcPlane(
+                new = ifcopenshell.util.element.copy(self.file, clipping)
-                    self.file.createIfcAxis2Placement3D(
+                new.FirstOperand = first_operand
-                        self.file.createIfcCartesianPoint(
+                first_operand = new
-                            (
+            else:  # ClippingInfo
-                                self.convert_si_to_unit(clipping[0][3]),
+                first_operand = clipping.apply(self.file, first_operand, self.settings["unit_scale"])
-                                self.convert_si_to_unit(clipping[1][3]),
-                                self.convert_si_to_unit(clipping[2][3]),
-                            )
-                        ),
-                        self.file.createIfcDirection((clipping[0][2], clipping[1][2], clipping[2][2])),
-                        self.file.createIfcDirection((clipping[0][0], clipping[1][0], clipping[2][0])),
-                    )
-                ),
-                False,
-            )
-            first_operand = self.file.createIfcBooleanClippingResult("DIFFERENCE", first_operand, second_operand)
         return first_operand
 
     def convert_si_to_unit(self, co):

src/ifcopenshell-python/ifcopenshell/api/geometry/add_wall_representation.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell.util.unit
 from math import sin, cos
+from ifcopenshell.util.representation import ClippingInfo
 
 
 class Usecase:
@@ -31,8 +32,8 @@ class Usecase:
             "thickness": 0.2,
             # Sloped walls along the wall's X axis, provided in radians
             "x_angle": 0,
-            # Planes are defined as a matrix. The XY plane is the clipping boundary and +Z is removed.
+            # Planes are defined either by ClippingInfo objects
-            # [{"type": "IfcBooleanClippingResult", "operand_type": "IfcHalfSpaceSolid", "matrix": [...]}, {...}]
+            # or by dictionaries of arguments for `ClippingInfo.parse`
             "clippings": [],  # A list of planes that define clipping half space solids
             "booleans": [],  # Any existing IfcBooleanResults
         }
@@ -41,6 +42,7 @@ class Usecase:
 
     def execute(self):
         self.settings["unit_scale"] = ifcopenshell.util.unit.calculate_unit_scale(self.file)
+        self.settings["clippings"] = [ClippingInfo.parse(c) for c in self.settings["clippings"]]
         return self.file.createIfcShapeRepresentation(
             self.settings["context"],
             self.settings["context"].ContextIdentifier,
@@ -99,25 +101,8 @@ class Usecase:
                 new = ifcopenshell.util.element.copy(self.file, clipping)
                 new.FirstOperand = first_operand
                 first_operand = new
-            elif clipping["operand_type"] == "IfcHalfSpaceSolid":
+            else:  # ClippingInfo
-                matrix = clipping["matrix"]
+                first_operand = clipping.apply(self.file, first_operand, self.settings["unit_scale"])
-                second_operand = self.file.createIfcHalfSpaceSolid(
-                    self.file.createIfcPlane(
-                        self.file.createIfcAxis2Placement3D(
-                            self.file.createIfcCartesianPoint(
-                                (
-                                    self.convert_si_to_unit(matrix[0][3]),
-                                    self.convert_si_to_unit(matrix[1][3]),
-                                    self.convert_si_to_unit(matrix[2][3]),
-                                )
-                            ),
-                            self.file.createIfcDirection((matrix[0][2], matrix[1][2], matrix[2][2])),
-                            self.file.createIfcDirection((matrix[0][0], matrix[1][0], matrix[2][0])),
-                        )
-                    ),
-                    False,
-                )
-                first_operand = self.file.create_entity(clipping["type"], "DIFFERENCE", first_operand, second_operand)
         return first_operand
 
     def convert_si_to_unit(self, co):

src/ifcopenshell-python/ifcopenshell/util/representation.py

@@ -16,8 +16,11 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+from __future__ import annotations
 import numpy as np
 import ifcopenshell
+from typing import Any
+from dataclasses import dataclass
 
 
 def get_context(ifc_file, context, subcontext=None, target_view=None):
@@ -86,3 +89,57 @@ def resolve_items(representation, matrix=None):
         else:
             results.append({"matrix": matrix.copy(), "item": item})
     return results
+
+
+@dataclass
+class ClippingInfo:
+    location: tuple[float, float, float]
+    normal: tuple[float, float, float]
+    type: str = "IfcBooleanClippingResult"
+    operand_type: str = "IfcHalfSpaceSolid"
+
+    @classmethod
+    def parse(cls, raw_data: Any) -> ifcopenshell.entity_instance | ClippingInfo | None:
+        """`raw_data` can be either:
+        - IfcBooleanResult IFC entity
+        - `ClippingInfo` instance
+        - dictionary to define `ClippingInfo` - either `location` and `normal`
+            or a `matrix` where XY plane is the clipping boundary and +Z is removed.
+            `matrix` method will be soon to be deprecated completely.
+        """
+        if isinstance(raw_data, ifcopenshell.entity_instance):
+            if not raw_data.is_a("IfcBooleanResult"):
+                raise Exception(f"Provided clipping of unexpected IFC class: {raw_data}")
+            return raw_data
+        elif isinstance(raw_data, ClippingInfo):
+            return raw_data
+        elif isinstance(raw_data, dict):
+            if "matrix" in raw_data:
+                raw_data = raw_data.copy()
+                matrix = np.array(raw_data["matrix"])[:3]
+                raw_data["normal"] = matrix[:, 2].tolist()
+                raw_data["location"] = matrix[:, 3].tolist()
+                del raw_data["matrix"]
+            clipping_data = cls(**raw_data)
+            if clipping_data.type != "IfcBooleanClippingResult":
+                raise Exception(f'Provided clipping with unexpected result type "{clipping_data.type}"')
+            if clipping_data.operand_type != "IfcHalfSpaceSolid":
+                raise Exception(f'Provided clipping with unexpected operand type "{clipping_data.operand_type}"')
+            return clipping_data
+        raise Exception(f"Unexpected clipping type provided: {raw_data}")
+
+    def apply(
+        self, file: ifcopenshell.file, first_operand: ifcopenshell.entity_instance, unit_scale: float
+    ) -> ifcopenshell.entity_instance:
+        # TODO: move to a separate method like `shape_builder.add_plane`
+        def create_ifc_half_space_solid():
+            location = file.createIfcCartesianPoint([i / unit_scale for i in self.location])
+            direction = file.createIfcDirection(self.normal)
+            axis_placement = file.createIfcAxis2Placement3D(location, direction, None)
+            plane = file.createIfcPlane(axis_placement)
+            halfspace_solid = file.createIfcHalfSpaceSolid(plane, False)
+            return halfspace_solid
+
+        second_operand = create_ifc_half_space_solid()
+        first_operand = file.createIfcBooleanClippingResult("DIFFERENCE", first_operand, second_operand)
+        return first_operand