See #5919. API now has support for features, not just openings. Void module is renamed to feature.

src/ifcopenshell-python/ifcopenshell/api/feature/__init__.py

@@ -16,25 +16,26 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Create void relationships between openings and physical elements
+"""Create relationships between features (e.g. openings) and physical elements
 
-An opening is a special element (created using
+A feature is a special element (created using
 :func:`ifcopenshell.api.root.create_entity`) that may then be used to create
-voids in other elements (such as walls and slabs). These voids may then be
-filled with doors, trapdoors, skylights, and so on.
+geometric changes in other elements (such as walls and slabs). Most commonly, a
+feature would be an opening void. These voids may then be filled with doors,
+trapdoors, skylights, and so on.
 """
 
 from .. import wrap_usecases
+from .add_feature import add_feature
 from .add_filling import add_filling
-from .add_opening import add_opening
+from .remove_feature import remove_feature
 from .remove_filling import remove_filling
-from .remove_opening import remove_opening
 
 wrap_usecases(__path__, __name__)
 
 __all__ = [
+    "add_feature",
     "add_filling",
-    "add_opening",
+    "remove_feature",
     "remove_filling",
-    "remove_opening",
 ]

src/ifcopenshell-python/ifcopenshell/api/feature/add_feature.py

@@ -0,0 +1,152 @@
+# IfcOpenShell - IFC toolkit and geometry engine
+# Copyright (C) 2021 Dion Moult <dion@thinkmoult.com>
+#
+# This file is part of IfcOpenShell.
+#
+# IfcOpenShell is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Lesser General Public License as published by
+# the Free Software Foundation, either version 3 of the License, or
+# (at your option) any later version.
+#
+# IfcOpenShell is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public License
+# along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
+
+import ifcopenshell
+import ifcopenshell.api.owner
+import ifcopenshell.api.geometry
+import ifcopenshell.api.aggregate
+import ifcopenshell.guid
+import ifcopenshell.util.element
+import ifcopenshell.util.placement
+
+
+def add_feature(
+    file: ifcopenshell.file, feature: ifcopenshell.entity_instance, element: ifcopenshell.entity_instance
+) -> ifcopenshell.entity_instance:
+    """Create a projecting, voiding, or surface feature in an element
+
+    There are three main types of features: those that add, remove, or
+    influence geometry of a parent object.
+
+    The most common of these is an opening. For example, it is often necessary
+    to cut out openings in elements like walls and slabs to make space to
+    insert doors, windows, and other services that go through these
+    penetrations.
+
+    Whereas it is possible to simply draw the wall as a rectangle with a
+    hole in it for the opening, often these openings have specific meanings.
+    For example, an opening might be filled with a window, and so when the
+    window moves, the opening should move with it. Alternatively, the
+    opening itself might have fire or acoustic requirements, such that any
+    service or equipment passing through that space must also comply with
+    those requirements. For these types of semantic openings, you should
+    have a distinct opening element which voids your regular element. For
+    example, your wall will still be a rectangular prism with no hole in it,
+    and a separate opening element will have a box representing the extents
+    of the opening for a window. The opening element will automatically
+    perform a geometric boolean operation to cut out the wall's geometry.
+
+    Whenever you have an opening in you project, you should determine
+    whether or not the opening is semantic (i.e. should be represented by a
+    distinct opening object) or non-semantic (i.e. should simply be
+    booleaned or be part of the shape of the object).
+
+    :param feature: The IfcFeatureElement to affect the element.
+    :type feature: ifcopenshell.entity_instance
+    :param element: The IfcElement to add the feature to.
+    :type element: ifcopenshell.entity_instance
+    :return: The new IfcRelVoidsElement relationship
+    :rtype: ifcopenshell.entity_instance
+
+    Example:
+
+    .. code:: python
+
+        # A bit of preparation, let's create some geometric contexts since
+        # we want to create some geometry for our wall and opening.
+        model3d = ifcopenshell.api.context.add_context(model, context_type="Model")
+        body = ifcopenshell.api.context.add_context(model,
+            context_type="Model", context_identifier="Body", target_view="MODEL_VIEW", parent=model3d)
+
+        # Create a wall
+        wall = ifcopenshell.api.root.create_entity(model, ifc_class="IfcWall")
+
+        # Let's use the "3D Body" representation we created earlier to add a
+        # new wall-like body geometry, 5 meters long, 3 meters high, and
+        # 200mm thick
+        representation = ifcopenshell.api.geometry.add_wall_representation(model,
+            context=body, length=5, height=3, thickness=0.2)
+        ifcopenshell.api.geometry.assign_representation(model,
+            product=wall, representation=representation)
+
+        # Place our wall at the origin
+        ifcopenshell.api.geometry.edit_object_placement(model, product=wall)
+
+        # Create an opening, such as for a service penetration with fire and
+        # acoustic requirements.
+        opening = ifcopenshell.api.root.create_entity(model, ifc_class="IfcOpeningElement")
+
+        # Let's create an opening representation of a 950mm x 2100mm door.
+        # Notice how the thickness is greater than the wall thickness, this
+        # helps resolve floating point resolution errors in 3D.
+        representation = ifcopenshell.api.geometry.add_wall_representation(model,
+            context=body, length=.95, height=2.1, thickness=0.4)
+        ifcopenshell.api.geometry.assign_representation(model,
+            product=opening, representation=representation)
+
+        # Let's shift our door 1 meter along the wall and 100mm along the
+        # wall, to create a nice overlap for the opening boolean.
+        matrix = np.identity(4)
+        matrix[:,3] = [1, -.1, 0, 0]
+        ifcopenshell.api.geometry.edit_object_placement(model, product=opening, matrix=matrix)
+
+        # The opening will now void the wall.
+        ifcopenshell.api.feature.add_feature(model, feature=opening, element=wall)
+    """
+    if feature.is_a("IfcFeatureElementSubtraction"):
+        rels = feature.VoidsElements
+        ifc_class = "IfcRelVoidsElement"
+    elif feature.is_a("IfcFeatureElementAddition"):
+        rels = feature.ProjectsElements
+        ifc_class = "IfcRelProjectsElement"
+    elif feature.is_a("IfcSurfaceFeature"):
+        if file.schema == "IFC4":
+            return ifcopenshell.api.aggregate.assign_object(file, [feature], element)
+        rels = feature.AdheresToElement
+        ifc_class = "IfcRelAdheresToElement"
+
+    if rels:
+        if rels[0][4] == element:
+            return rels[0]
+        elif ifc_class == "IfcRelAdheresToElement" and len(rels[0].RelatedSurfaceFeatures) != 1:
+            rels[0].RelatedSurfaceFeatures = list(set(rels[0].RelatedSurfaceFeatures) - {feature})
+        else:
+            history = rels[0].OwnerHistory
+            file.remove(rels[0])
+            if history:
+                ifcopenshell.util.element.remove_deep2(file, history)
+
+    rel = file.create_entity(
+        ifc_class,
+        ifcopenshell.guid.new(),
+        ifcopenshell.api.owner.create_owner_history(file),
+        None,
+        None,
+        element,
+        [feature] if ifc_class == "IfcRelAdheresToElement" else feature,
+    )
+
+    if (placement := feature.ObjectPlacement) and placement.is_a("IfcLocalPlacement"):
+        ifcopenshell.api.geometry.edit_object_placement(
+            file,
+            product=feature,
+            matrix=ifcopenshell.util.placement.get_local_placement(placement),
+            is_si=False,
+        )
+
+    return rel

src/ifcopenshell-python/ifcopenshell/api/feature/add_filling.py

@@ -82,7 +82,7 @@ def add_filling(
         ifcopenshell.api.geometry.edit_object_placement(model, product=opening, matrix=matrix)
 
         # The opening will now void the wall.
-        ifcopenshell.api.void.add_opening(model, opening=opening, element=wall)
+        ifcopenshell.api.feature.add_feature(model, feature=opening, element=wall)
 
         # Create a door
         door = ifcopenshell.api.root.create_entity(model, ifc_class="IfcDoor")
@@ -100,7 +100,7 @@ def add_filling(
         ifcopenshell.api.geometry.edit_object_placement(model, product=door, matrix=matrix)
 
         # The door will now fill the opening.
-        ifcopenshell.api.void.add_filling(model, opening=opening, element=door)
+        ifcopenshell.api.feature.add_filling(model, opening=opening, element=door)
     """
     settings = {"opening": opening, "element": element}
 

src/ifcopenshell-python/ifcopenshell/api/feature/remove_feature.py

@@ -17,44 +17,50 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api.root
+import ifcopenshell.api.aggregate
 import ifcopenshell.util.element
 
 
-def remove_opening(file: ifcopenshell.file, opening: ifcopenshell.entity_instance) -> None:
-    """Remove an opening
+def remove_feature(file: ifcopenshell.file, feature: ifcopenshell.entity_instance) -> None:
+    """Remove a feature
 
-    Fillings are retained as orphans. Voided elements remain. Openings
-    cannot exist by themselves, so not only is the opening relationship
-    removed, the opening is also removed.
+    Fillings are retained as orphans. Featured elements remain. Features
+    cannot exist by themselves, so not only is the relationship removed, the
+    feature is also removed.
 
-    :param opening: The IfcOpeningElement to remove.
-    :type opening: ifcopenshell.entity_instance
-    :return: None
-    :rtype: None
+    :param feature: The IfcFeatureElement to remove.
 
     Example:
 
     .. code:: python
 
-        # Create an oprhaned opening. Note that an orphaned opening is
+        # Create an orphaned opening. Note that an orphaned opening is
         # invalid, as an opening can only exist when voiding another
         # element.
-        opening = ifcopenshell.api.root.create_entity(model, ifc_class="IfcOpeningElement")
+        feature = ifcopenshell.api.root.create_entity(model, ifc_class="IfcOpeningElement")
 
         # Remove it. This brings us back to a valid model.
-        ifcopenshell.api.void.remove_opening(model, opening=opening)
+        ifcopenshell.api.feature.remove_feature(model, feature=feature)
     """
-    settings = {"opening": opening}
-
-    for rel in settings["opening"].VoidsElements:
+    if feature.is_a("IfcFeatureElementSubtraction"):
+        rels = feature.VoidsElements
+    elif feature.is_a("IfcFeatureElementAddition"):
+        rels = feature.ProjectsElements
+    elif feature.is_a("IfcSurfaceFeature"):
+        if file.schema == "IFC4":
+            ifcopenshell.api.aggregate.unassign_object(file, products=[feature])
+            rels = []
+        else:
+            rels = feature.ProjectsElements
+    for rel in rels:
         history = rel.OwnerHistory
         file.remove(rel)
         if history:
             ifcopenshell.util.element.remove_deep2(file, history)
-    if settings["opening"].is_a("IfcOpeningElement"):
-        for rel in settings["opening"].HasFillings:
+    if feature.is_a("IfcOpeningElement"):
+        for rel in feature.HasFillings:
             history = rel.OwnerHistory
             file.remove(rel)
             if history:
                 ifcopenshell.util.element.remove_deep2(file, history)
-    ifcopenshell.api.root.remove_product(file, product=settings["opening"])
+    ifcopenshell.api.root.remove_product(file, product=feature)

src/ifcopenshell-python/ifcopenshell/api/feature/remove_filling.py

@@ -47,10 +47,10 @@ def remove_filling(file: ifcopenshell.file, element: ifcopenshell.entity_instanc
         door = ifcopenshell.api.root.create_entity(model, ifc_class="IfcDoor")
 
         # The door will now fill the opening.
-        ifcopenshell.api.void.add_filling(model, opening=opening, element=door)
+        ifcopenshell.api.feature.add_filling(model, opening=opening, element=door)
 
         # Not anymore!
-        ifcopenshell.api.void.remove_filling(model, element=door)
+        ifcopenshell.api.feature.remove_filling(model, element=door)
     """
     settings = {"element": element}
 

src/ifcopenshell-python/ifcopenshell/api/root/remove_product.py

@@ -18,7 +18,7 @@
 
 import ifcopenshell.api.type
 import ifcopenshell.api.grid
-import ifcopenshell.api.void
+import ifcopenshell.api.feature
 import ifcopenshell.api.root
 import ifcopenshell.api.pset
 import ifcopenshell.api.boundary
@@ -94,7 +94,7 @@ def remove_product(file: ifcopenshell.file, product: ifcopenshell.entity_instanc
         )
         ifcopenshell.api.geometry.remove_representation(file, **{"representation": representation})
     for opening in getattr(settings["product"], "HasOpenings", []) or []:
-        ifcopenshell.api.void.remove_opening(file, opening=opening.RelatedOpeningElement)
+        ifcopenshell.api.feature.remove_feature(file, feature=opening.RelatedOpeningElement)
 
     if settings["product"].is_a("IfcGrid"):
         for axis in settings["product"].UAxes + settings["product"].VAxes + (settings["product"].WAxes or ()):

src/ifcopenshell-python/ifcopenshell/api/void/add_feature.py

@@ -19,19 +19,24 @@
 import ifcopenshell
 import ifcopenshell.api.owner
 import ifcopenshell.api.geometry
+import ifcopenshell.api.aggregate
 import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.placement
 
 
-def add_opening(
-    file: ifcopenshell.file, opening: ifcopenshell.entity_instance, element: ifcopenshell.entity_instance
+def add_feature(
+    file: ifcopenshell.file, feature: ifcopenshell.entity_instance, element: ifcopenshell.entity_instance
 ) -> ifcopenshell.entity_instance:
-    """Create an opening in an element
+    """Create a projecting, voiding, or surface feature in an element
 
-    It is often necessary to cut out openings in elements like walls and
-    slabs to make space to insert doors, windows, and other services that go
-    through these penetrations.
+    There are three main types of features: those that add, remove, or
+    influence geometry of a parent object.
+
+    The most common of these is an opening. For example, it is often necessary
+    to cut out openings in elements like walls and slabs to make space to
+    insert doors, windows, and other services that go through these
+    penetrations.
 
     Whereas it is possible to simply draw the wall as a rectangle with a
     hole in it for the opening, often these openings have specific meanings.
@@ -51,9 +56,9 @@ def add_opening(
     distinct opening object) or non-semantic (i.e. should simply be
     booleaned or be part of the shape of the object).
 
-    :param opening: The IfcOpeningElement to cut out the element.
-    :type opening: ifcopenshell.entity_instance
-    :param element: The IfcElement to insert the opening into.
+    :param feature: The IfcFeatureElement to affect the element.
+    :type feature: ifcopenshell.entity_instance
+    :param element: The IfcElement to add the feature to.
     :type element: ifcopenshell.entity_instance
     :return: The new IfcRelVoidsElement relationship
     :rtype: ifcopenshell.entity_instance
@@ -101,36 +106,46 @@ def add_opening(
         ifcopenshell.api.geometry.edit_object_placement(model, product=opening, matrix=matrix)
 
         # The opening will now void the wall.
-        ifcopenshell.api.void.add_opening(model, opening=opening, element=wall)
+        ifcopenshell.api.void.add_feature(model, feature=opening, element=wall)
     """
-    settings = {"opening": opening, "element": element}
+    if feature.is_a("IfcFeatureElementSubtraction"):
+        rels = feature.VoidsElements
+        ifc_class = "IfcRelVoidsElement"
+    elif feature.is_a("IfcFeatureElementAddition"):
+        rels = feature.ProjectsElements
+        ifc_class = "IfcRelProjectsElement"
+    elif feature.is_a("IfcSurfaceFeature"):
+        if file.schema == "IFC4":
+            return ifcopenshell.api.aggregate.assign_object(file, [feature], element)
+        rels = feature.AdheresToElement
+        ifc_class = "IfcRelAdheresToElement"
 
-    voids_elements = settings["opening"].VoidsElements
-
-    if voids_elements:
-        if voids_elements[0].RelatingBuildingElement == settings["element"]:
-            return voids_elements[0]
-        history = voids_elements[0].OwnerHistory
-        file.remove(voids_elements[0])
-        if history:
-            ifcopenshell.util.element.remove_deep2(file, history)
+    if rels:
+        if rels[0][4] == element:
+            return rels[0]
+        elif ifc_class == "IfcRelAdheresToElement" and len(rels[0].RelatedSurfaceFeatures) != 1:
+            rels[0].RelatedSurfaceFeatures = list(set(rels[0].RelatedSurfaceFeatures) - {feature})
+        else:
+            history = rels[0].OwnerHistory
+            file.remove(rels[0])
+            if history:
+                ifcopenshell.util.element.remove_deep2(file, history)
 
     rel = file.create_entity(
-        "IfcRelVoidsElement",
-        **{
-            "GlobalId": ifcopenshell.guid.new(),
-            "OwnerHistory": ifcopenshell.api.owner.create_owner_history(file),
-            "RelatingBuildingElement": settings["element"],
-            "RelatedOpeningElement": settings["opening"],
-        }
+        ifc_class,
+        ifcopenshell.guid.new(),
+        ifcopenshell.api.owner.create_owner_history(file),
+        None,
+        None,
+        element,
+        [feature] if ifc_class == "IfcRelAdheresToElement" else feature,
     )
 
-    placement = getattr(settings["opening"], "ObjectPlacement", None)
-    if placement and placement.is_a("IfcLocalPlacement"):
+    if (placement := feature.ObjectPlacement) and placement.is_a("IfcLocalPlacement"):
         ifcopenshell.api.geometry.edit_object_placement(
             file,
-            product=settings["opening"],
-            matrix=ifcopenshell.util.placement.get_local_placement(settings["opening"].ObjectPlacement),
+            product=feature,
+            matrix=ifcopenshell.util.placement.get_local_placement(placement),
             is_si=False,
         )