removed unnecessary code

Co-authored-by: Bruno Perdigão <57102715+brunoperdigao@users.noreply.github.com>

src/blenderbim/Makefile

@@ -151,8 +151,10 @@ endif
 	cd dist/working && wget https://github.com/IfcOpenShell/IfcOpenShell/archive/v0.7.0.zip
 	cd dist/working && unzip v0.7.0.zip
 	# IfcOpenBot sometimes lags behind, so we hotfix the Python utilities
-	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/util/* dist/blenderbim/libs/site/packages/ifcopenshell/util/
-	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/api/* dist/blenderbim/libs/site/packages/ifcopenshell/api/
+	rm -rf dist/blenderbim/libs/site/packages/ifcopenshell/util/
+	rm -rf dist/blenderbim/libs/site/packages/ifcopenshell/api/
+	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/util dist/blenderbim/libs/site/packages/ifcopenshell/
+	cp -r dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/api dist/blenderbim/libs/site/packages/ifcopenshell/
 	cp dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/*.py dist/blenderbim/libs/site/packages/ifcopenshell/
 	cp dist/working/IfcOpenShell-0.7.0/src/ifcopenshell-python/ifcopenshell/express/rule_executor.py dist/blenderbim/libs/site/packages/ifcopenshell/express/
 	# Provides bcf functionality

src/blenderbim/blenderbim/__init__.py

@@ -18,7 +18,13 @@
 
 import os
 import sys
-import site
+import bpy
+import platform
+import traceback
+import subprocess
+import webbrowser
+import addon_utils
+from collections import deque
 
 bl_info = {
     "name": "BlenderBIM",
@@ -32,16 +38,150 @@ bl_info = {
     "category": "System",
 }
 
+last_error = None
+last_actions: deque = deque(maxlen=10)
+
+
+def get_debug_info():
+    version = ".".join(
+        [
+            str(x)
+            for x in [
+                addon.bl_info.get("version", (-1, -1, -1))
+                for addon in addon_utils.modules()
+                if addon.bl_info["name"] == "BlenderBIM"
+            ][0]
+        ]
+    )
+    return {
+        "os": platform.system(),
+        "os_version": platform.version(),
+        "python_version": platform.python_version(),
+        "architecture": platform.architecture(),
+        "machine": platform.machine(),
+        "processor": platform.processor(),
+        "blender_version": bpy.app.version_string,
+        "blenderbim_version": version,
+        "last_actions": last_actions,
+        "last_error": last_error,
+    }
+
+
+def format_debug_info(info: dict):
+    last_actions = ""
+    for action in info["last_actions"]:
+        last_actions += f"\n# {action['type']}: {action['name']}"
+        if settings := action.get("settings"):
+            last_actions += f"\n>>> {settings}"
+    info["last_actions"] = last_actions
+    text = "\n".join(f"{k}: {v}" for k, v in info.items())
+    return text.strip()
+
+
 if sys.modules.get("bpy", None):
     # Process *.pth in /libs/site/packages to setup globally importable modules
     # This is 3 levels deep as required by the static RPATH of ../../ from dependencies taken from Anaconda
     # site.addsitedir(os.path.join(os.path.dirname(os.path.realpath(__file__)), "libs", "site", "packages"))
     sys.path.insert(0, os.path.join(os.path.dirname(os.path.realpath(__file__)), "libs", "site", "packages"))
 
-    import blenderbim.bim
+    try:
+        import blenderbim.bim
+        import ifcopenshell.api
 
-    def register():
-        blenderbim.bim.register()
+        def log_api(usecase_path, ifc_file, settings):
+            last_actions.append(
+                {
+                    "type": "ifcopenshell.api",
+                    "name": usecase_path,
+                    "settings": ifcopenshell.api.serialise_settings(settings),
+                }
+            )
 
-    def unregister():
-        blenderbim.bim.unregister()
+        ifcopenshell.api.add_pre_listener("*", "action_logger", log_api)
+
+        def register():
+            blenderbim.bim.register()
+
+        def unregister():
+            blenderbim.bim.unregister()
+
+    except:
+        last_error = traceback.format_exc()
+
+        print(last_error)
+        print(format_debug_info(get_debug_info()))
+        print("\nFATAL ERROR: Unable to load the BlenderBIM Add-on")
+
+        class BIM_PT_fatal_error(bpy.types.Panel):
+            bl_label = "BlenderBIM Fatal Error"
+            bl_idname = "SCENE_PT_error_message"
+            bl_space_type = "PROPERTIES"
+            bl_region_type = "WINDOW"
+            bl_context = "scene"
+
+            def draw(self, context):
+                layout = self.layout
+                layout.label(text="BlenderBIM could not load.", icon="ERROR")
+                layout.label(text="View the console for full logs.", icon="CONSOLE")
+                box = layout.box()
+                info = get_debug_info()
+                py = ".".join(info["python_version"].split(".")[0:2])
+                b3d = ".".join(info["blender_version"].split(".")[0:2])
+                box.label(text=f"Blender {b3d} {info['os']} {info['machine']}", icon="BLENDER")
+                box.label(text=f"Python {py} BBIM {info['blenderbim_version']}", icon="SCRIPTPLUGINS")
+                layout.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard")
+                op = layout.operator("bim.open_uri", text="How Can I Fix This?")
+                op.uri = "https://docs.blenderbim.org/users/troubleshooting.html#installation-issues"
+
+        class OpenUri(bpy.types.Operator):
+            bl_idname = "bim.open_uri"
+            bl_label = "Open URI"
+            uri: bpy.props.StringProperty()
+
+            def execute(self, context):
+                webbrowser.open(self.uri)
+                return {"FINISHED"}
+
+        class CopyDebugInformation(bpy.types.Operator):
+            bl_idname = "bim.copy_debug_information"
+            bl_label = "Copy Debug Information"
+            bl_description = "Copies debugging information to your clipboard for use in bugreports"
+
+            def execute(self, context):
+                info = format_debug_info(get_debug_info())
+
+                if platform.system() == "Windows":
+                    command = "echo | set /p nul=" + info
+                elif platform.system() == "Darwin":  # for MacOS
+                    command = 'printf "' + info.replace("\n", "\\n").replace('"', "") + '" | pbcopy'
+                else:  # Linux
+                    command = 'printf "' + info.replace("\n", "\\n").replace('"', "") + '" | xclip -selection clipboard'
+                subprocess.run(command, shell=True, check=True)
+                return {"FINISHED"}
+
+        class HiddenPanel:
+            @classmethod
+            def false_poll(cls, context):
+                return False
+
+        def register():
+            # Only show our error panel and nothing else in the scene tab
+            for item_name in dir(bpy.types):
+                item = getattr(bpy.types, item_name)
+                if not hasattr(item, "bl_rna") or not isinstance(item.bl_rna, bpy.types.Panel):
+                    continue
+                if getattr(item, "bl_context", None) != "scene":
+                    continue
+
+                # Reregister scene panel with a new poll to hide it
+                item.poll = HiddenPanel.false_poll
+                bpy.utils.unregister_class(item)
+                bpy.utils.register_class(item)
+            bpy.utils.register_class(BIM_PT_fatal_error)
+            bpy.utils.register_class(CopyDebugInformation)
+            bpy.utils.register_class(OpenUri)
+
+        def unregister():
+            bpy.utils.unregister_class(OpenUri)
+            bpy.utils.unregister_class(CopyDebugInformation)
+            bpy.utils.unregister_class(BIM_PT_fatal_error)

src/blenderbim/blenderbim/bim/__init__.py

@@ -17,11 +17,11 @@
 # along with BlenderBIM Add-on.  If not, see <http://www.gnu.org/licenses/>.
 
 import os
-from pathlib import Path
 import bpy
 import bpy.utils.previews
 import blenderbim
 import importlib
+from pathlib import Path
 from . import handler, ui, prop, operator, helper
 from typing import Callable, Union
 
@@ -103,6 +103,7 @@ classes = [
     operator.BIM_OT_select_object,
     operator.BIM_OT_show_description,
     operator.ClippingPlaneCutWithCappings,
+    operator.CloseError,
     operator.EditBlenderCollection,
     operator.FileAssociate,
     operator.FileUnassociate,

src/blenderbim/blenderbim/bim/data/pset/EPset_Drawing.ifc

@@ -5,7 +5,7 @@ FILE_NAME('EPset_Drawing.ifc','2020-01-01T00:00:00',(),(),'EPset_Drawing','EPset
 FILE_SCHEMA(('IFC4'));
 ENDSEC;
 DATA;
-#1=IFCPROPERTYSETTEMPLATE('2JhNIvqZrFnAgxfhK0XVQX',$,'EPset_Drawing','',.PSET_OCCURRENCEDRIVEN.,'IfcAnnotation',(#2,#3,#4,#5,#6,#7,#8,#9,#10,#11,#12,#13,#14,#15,#16,#17,#18,#19,#20,#21,#22,#23));
+#1=IFCPROPERTYSETTEMPLATE('2JhNIvqZrFnAgxfhK0XVQX',$,'EPset_Drawing','',.PSET_OCCURRENCEDRIVEN.,'IfcAnnotation/DRAWING',(#2,#3,#4,#5,#6,#7,#8,#9,#10,#11,#12,#13,#14,#15,#16,#17,#18,#19,#20,#21,#22,#23));
 #2=IFCSIMPLEPROPERTYTEMPLATE('23JavTMk98ZxXhrUEnjAcf',$,'TargetView','',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #3=IFCSIMPLEPROPERTYTEMPLATE('1yVWUt5H9DAOuu0OaMMLpe',$,'Scale','The scale of this drawing represented as a numerator and denominator, such as 1/100',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #4=IFCSIMPLEPROPERTYTEMPLATE('3gsuPBtU93b8f0gg1pjkq6',$,'HumanScale','The scale of this drawing in human readable format, such as 1:100',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);

src/blenderbim/blenderbim/bim/data/pset/Psets_BBIM_Annotation.ifc

@@ -5,20 +5,20 @@ FILE_NAME('Psets_BBIM_Annotation.ifc','2020-01-01T00:00:00',(),(),'Psets_BBIM_An
 FILE_SCHEMA(('IFC4'));
 ENDSEC;
 DATA;
-#1=IFCPROPERTYSETTEMPLATE('3VuPUwdCD2Qx3XDDRs0R1N',$,'EPset_Annotation','',.PSET_OCCURRENCEDRIVEN.,'IfcAnnotation,IfcTypeProduct',(#2,#3,#4));
+#1=IFCPROPERTYSETTEMPLATE('3VuPUwdCD2Qx3XDDRs0R1N',$,'EPset_Annotation','',.PSET_TYPEDRIVENOVERRIDE.,'IfcAnnotation,IfcTypeProduct',(#2,#3,#4));
 #2=IFCSIMPLEPROPERTYTEMPLATE('2P7JN79n96Q9pElZ83LKe4',$,'ZIndex','',.P_SINGLEVALUE.,'IfcInteger',$,$,$,$,$,.READWRITE.);
 #3=IFCSIMPLEPROPERTYTEMPLATE('1Wpx_r2xj1_9w5JpI0QRJy',$,'Symbol','',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #4=IFCSIMPLEPROPERTYTEMPLATE('3q0oxMUKP47vZ4jnyG$dDb',$,'Classes','Classes separarated by spaces that end up in classes for this element in svg. Can be used to specify the text font size: small - 1.8mm; regular - 2.5mm; large - 3.5mm; header - 5mm; title - 7mm. By default regular size is used.',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
-#5=IFCPROPERTYSETTEMPLATE('0iKwujnQL9IevVQato8f7Z',$,'BBIM_Batting','',.PSET_OCCURRENCEDRIVEN.,'IfcAnnotation,IfcTypeProduct',(#6,#7));
+#5=IFCPROPERTYSETTEMPLATE('0iKwujnQL9IevVQato8f7Z',$,'BBIM_Batting','',.PSET_TYPEDRIVENOVERRIDE.,'IfcAnnotation/BATTING,IfcTypeProduct',(#6,#7));
 #6=IFCSIMPLEPROPERTYTEMPLATE('0t2LEesGT1QRQtrIZUAR8L',$,'Thickness','Batting thickness',.P_SINGLEVALUE.,'IfcPositiveLengthMeasure',$,$,$,$,$,.READWRITE.);
 #7=IFCSIMPLEPROPERTYTEMPLATE('082PndS6v2kBOiJoSboMnh',$,'Reverse pattern direction','Reverse batting pattern (swap starting and ending points)',.P_SINGLEVALUE.,'IfcBoolean',$,$,$,$,$,.READWRITE.);
-#8=IFCPROPERTYSETTEMPLATE('1Dx2EiZnP67xotInXpwz90',$,'BBIM_Section','',.PSET_OCCURRENCEDRIVEN.,'IfcAnnotation,IfcTypeProduct',(#9,#10,#11,#12,#13));
+#8=IFCPROPERTYSETTEMPLATE('1Dx2EiZnP67xotInXpwz90',$,'BBIM_Section','',.PSET_TYPEDRIVENOVERRIDE.,'IfcAnnotation/SECTION,IfcTypeProduct',(#9,#10,#11,#12,#13));
 #9=IFCSIMPLEPROPERTYTEMPLATE('2a_9s8spHDc9dZHtgg71XL',$,'ShowStartArrow','Display start arrow.',.P_SINGLEVALUE.,'IfcBoolean',$,$,$,$,$,.READWRITE.);
 #10=IFCSIMPLEPROPERTYTEMPLATE('3i6SH_GbT7zhKea$wVE56A',$,'StartArrowSymbol','Custom symbol for the start of the section marker arrow. Need to make sure it''s present in "symbols.svg".',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #11=IFCSIMPLEPROPERTYTEMPLATE('1DtsPn5a9FG8$zXHDDMavY',$,'ShowEndArrow','Display end arrow.',.P_SINGLEVALUE.,'IfcBoolean',$,$,$,$,$,.READWRITE.);
 #12=IFCSIMPLEPROPERTYTEMPLATE('2$6U0mLI9AiPRWeBabdY3u',$,'EndArrowSymbol','Custom symbol for the end of the section marker arrow. Need to make sure it''s present in "symbols.svg".',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #13=IFCSIMPLEPROPERTYTEMPLATE('1naFqntIL7igCY7hCaE7kq',$,'HasConnectedSectionLine','Connect or disconnect section markers with line (by default = True).',.P_SINGLEVALUE.,'IfcBoolean',$,$,$,$,$,.READWRITE.);
-#14=IFCPROPERTYSETTEMPLATE('3V8oZ8YRD3_O7uR5vcUleS',$,'BBIM_Documentation','',.PSET_OCCURRENCEDRIVEN.,'IfcProject',(#15,#16,#17,#18,#19,#20,#21,#22,#23));
+#14=IFCPROPERTYSETTEMPLATE('3V8oZ8YRD3_O7uR5vcUleS',$,'BBIM_Documentation','',.PSET_TYPEDRIVENOVERRIDE.,'IfcProject',(#15,#16,#17,#18,#19,#20,#21,#22,#23));
 #15=IFCSIMPLEPROPERTYTEMPLATE('0ulAhgk3v9qfGlDILauR6J',$,'SheetsDir','Default sheets directory',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #16=IFCSIMPLEPROPERTYTEMPLATE('2yvlVKiQXASucfH40deCvu',$,'LayoutsDir','Default layouts directory',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #17=IFCSIMPLEPROPERTYTEMPLATE('2kXZqXicL3jRwsOnLM_0ho',$,'TitleblocksDir','Default titleblocks directory',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
@@ -28,7 +28,7 @@ DATA;
 #21=IFCSIMPLEPROPERTYTEMPLATE('1UDakJ5_f7kBhggNSW4$h5',$,'SymbolsPath','Default symbols SVG',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #22=IFCSIMPLEPROPERTYTEMPLATE('0d53LEtgLDQxnv__NfgH7i',$,'PatternsPath','Default patterns SVG',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
 #23=IFCSIMPLEPROPERTYTEMPLATE('26qFNMv7nCHgU6Jd7Anga5',$,'ShadingStylesPath','Default shading styles',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);
-#24=IFCPROPERTYSETTEMPLATE('0I9merLinF5Ap$aZwaclgm',$,'BBIM_Dimension','',.PSET_OCCURRENCEDRIVEN.,'IfcAnnotation,IfcTypeProduct',(#25,#26,#27,#28));
+#24=IFCPROPERTYSETTEMPLATE('0I9merLinF5Ap$aZwaclgm',$,'BBIM_Dimension','',.PSET_TYPEDRIVENOVERRIDE.,'IfcAnnotation/DIMENSION,IfcTypeProduct',(#25,#26,#27,#28));
 #25=IFCSIMPLEPROPERTYTEMPLATE('1rL2AbQsXD8RbpoWH5pYOV',$,'ShowDescriptionOnly','Hide the measurement values and show only annotation description',.P_SINGLEVALUE.,'IfcBoolean',$,$,$,$,$,.READWRITE.);
 #26=IFCSIMPLEPROPERTYTEMPLATE('0SVyOfB0rC2xNfdRYf3XvY',$,'SuppressZeroInches','Suppress 0 inch values in dimension annotation text (for example: 12'' - 0" -> 12'')',.P_SINGLEVALUE.,'IfcBoolean',$,$,$,$,$,.READWRITE.);
 #27=IFCSIMPLEPROPERTYTEMPLATE('2bUmj458PBqPAtUoI3MXsb',$,'TextPrefix','Text to add before annotation measurement value',.P_SINGLEVALUE.,'IfcLabel',$,$,$,$,$,.READWRITE.);

src/blenderbim/blenderbim/bim/ifc.py

@@ -19,12 +19,15 @@
 import os
 import bpy
 import uuid
+import shutil
 import hashlib
 import zipfile
 import tempfile
+import traceback
 import ifcopenshell
 import ifcopenshell.geom
 import ifcopenshell.ifcopenshell_wrapper
+import blenderbim
 import blenderbim.bim.handler
 import blenderbim.tool as tool
 from pathlib import Path
@@ -37,19 +40,19 @@ IFC_CONNECTED_TYPE = Union[bpy.types.Material, bpy.types.Object]
 
 class IfcStore:
     path: str = ""
-    file: ifcopenshell.file = None
-    schema: ifcopenshell.ifcopenshell_wrapper.schema_definition = None
-    cache: ifcopenshell.ifcopenshell_wrapper.HdfSerializer = None
-    cache_path: str = None
+    file: Optional[ifcopenshell.file] = None
+    schema: Optional[ifcopenshell.ifcopenshell_wrapper.schema_definition] = None
+    cache: Optional[ifcopenshell.ifcopenshell_wrapper.HdfSerializer] = None
+    cache_path: Optional[str] = None
     id_map: dict[int, IFC_CONNECTED_TYPE] = {}
     guid_map: dict[str, IFC_CONNECTED_TYPE] = {}
     edited_objs: Set[bpy.types.Object] = set()
     pset_template_path: str = ""
-    pset_template_file: ifcopenshell.file = None
+    pset_template_file: Optional[ifcopenshell.file] = None
     classification_path: str = ""
-    classification_file: ifcopenshell.file = None
+    classification_file: Optional[ifcopenshell.file] = None
     library_path: str = ""
-    library_file: ifcopenshell.file = None
+    library_file: Optional[ifcopenshell.file] = None
     current_transaction = ""
     last_transaction = ""
     history = []
@@ -119,7 +122,13 @@ class IfcStore:
         ifc_hash = hashlib.md5(ifc_key.encode("utf-8")).hexdigest()
         new_cache_path = os.path.join(bpy.context.scene.BIMProperties.data_dir, "cache", f"{ifc_hash}.h5")
         IfcStore.cache = None
-        os.replace(IfcStore.cache_path, new_cache_path)
+        try:
+            shutil.move(IfcStore.cache_path, new_cache_path)
+        except PermissionError:
+            try:
+                shutil.copy2(IfcStore.cache_path, new_cache_path)
+            except PermissionError:
+                pass  # Well we tried. No cache for you!
         IfcStore.get_cache()
 
     @staticmethod
@@ -329,6 +338,7 @@ class IfcStore:
 
     @staticmethod
     def execute_ifc_operator(operator: bpy.types.Operator, context: bpy.types.Context, is_invoke=False):
+        blenderbim.last_actions.append({"type": "operator", "name": operator.bl_idname})
         bpy.context.scene.BIMProperties.is_dirty = True
         is_top_level_operator = not bool(IfcStore.current_transaction)
 
@@ -343,10 +353,14 @@ class IfcStore:
         else:
             operator.transaction_key = IfcStore.current_transaction
 
-        if is_invoke:
-            result = getattr(operator, "_invoke")(context, None)
-        else:
-            result = getattr(operator, "_execute")(context)
+        try:
+            if is_invoke:
+                result = getattr(operator, "_invoke")(context, None)
+            else:
+                result = getattr(operator, "_execute")(context)
+        except:
+            blenderbim.last_error = traceback.format_exc()
+            raise
 
         if is_top_level_operator:
             if tool.Ifc.get():

src/blenderbim/blenderbim/bim/import_ifc.py

@@ -702,15 +702,17 @@ class IfcImporter:
             mat = np.array(
                 ([m[0], m[3], m[6], m[9]], [m[1], m[4], m[7], m[10]], [m[2], m[5], m[8], m[11]], [0, 0, 0, 1])
             )
-            point = np.array(
+            point = mat @ np.array(
                 (
-                    shape.geometry.verts[0] / self.unit_scale,
-                    shape.geometry.verts[1] / self.unit_scale,
-                    shape.geometry.verts[2] / self.unit_scale,
+                    shape.geometry.verts[0],
+                    shape.geometry.verts[1],
+                    shape.geometry.verts[2],
                     0.0,
                 )
             )
-            return mat @ point
+            point = point / self.unit_scale
+            if self.is_point_far_away(point, is_meters=False):
+                return point
 
     def does_element_likely_have_geometry_far_away(self, element):
         for representation in element.Representation.Representations:
@@ -1500,10 +1502,9 @@ class IfcImporter:
         project_collection = bpy.context.view_layer.layer_collection.children[self.project["blender"].name]
         types_collection = project_collection.children[self.type_collection.name]
         types_collection.hide_viewport = False
-        for obj in types_collection.collection.objects: #turn off all objects inside Types collection.
+        for obj in types_collection.collection.objects:  # turn off all objects inside Types collection.
             obj.hide_set(True)
 
-
     def clean_mesh(self):
         obj = None
         last_obj = None
@@ -1912,11 +1913,7 @@ class IfcImporter:
                 and geometry.verts
                 and self.is_point_far_away((geometry.verts[0], geometry.verts[1], geometry.verts[2]))
             ):
-                m = shape.transformation.matrix.data
-                mat = np.array(
-                    ([m[0], m[3], m[6], m[9]], [m[1], m[4], m[7], m[10]], [m[2], m[5], m[8], m[11]], [0, 0, 0, 1])
-                )
-                offset_point = np.linalg.inv(mat) @ np.array(
+                offset_point = np.array(
                     (
                         float(props.blender_eastings),
                         float(props.blender_northings),
@@ -1924,8 +1921,15 @@ class IfcImporter:
                         0.0,
                     )
                 )
+                if geometry != shape:
+                    m = shape.transformation.matrix.data
+                    mat = np.array(
+                        ([m[0], m[3], m[6], m[9]], [m[1], m[4], m[7], m[10]], [m[2], m[5], m[8], m[11]], [0, 0, 0, 1])
+                    )
+                    offset_point = np.linalg.inv(mat) @ offset_point
                 verts = [None] * len(geometry.verts)
                 for i in range(0, len(geometry.verts), 3):
+                    # Note: this enh2xyz call is crazy slow.
                     verts[i], verts[i + 1], verts[i + 2] = ifcopenshell.util.geolocation.enh2xyz(
                         geometry.verts[i],
                         geometry.verts[i + 1],

src/blenderbim/blenderbim/bim/module/aggregate/ui.py

@@ -73,7 +73,7 @@ class BIM_PT_aggregate(Panel):
                 row.operator("bim.add_aggregate", icon="ADD", text="")
                 op = row.operator("bim.aggregate_unassign_object", icon="X", text="")
             else:
-                row.label(text="No Aggregate", icon="TRIA_UP")
+                row.label(text="No Whole relation defined", icon="TRIA_UP")
                 row.operator("bim.enable_editing_aggregate", icon="GREASEPENCIL", text="")
                 row.operator("bim.add_aggregate", icon="ADD", text="")
 

src/blenderbim/blenderbim/bim/module/attribute/operator.py

@@ -20,6 +20,7 @@ import bpy
 import json
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import blenderbim.bim.helper
 import blenderbim.bim.handler
 import blenderbim.tool as tool

src/blenderbim/blenderbim/bim/module/debug/operator.py

@@ -24,7 +24,6 @@ import random
 import logging
 import platform
 import subprocess
-import addon_utils
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
@@ -34,7 +33,7 @@ import blenderbim.tool as tool
 import blenderbim.core.debug as core
 import blenderbim.bim.handler
 import blenderbim.bim.import_ifc as import_ifc
-import blenderbim.tool as tool
+from blenderbim import get_debug_info, format_debug_info
 from blenderbim.bim.ifc import IfcStore
 
 
@@ -44,28 +43,7 @@ class CopyDebugInformation(bpy.types.Operator):
     bl_description = "Copies debugging information to your clipboard for use in bugreports"
 
     def execute(self, context):
-        version = ".".join(
-            [
-                str(x)
-                for x in [
-                    addon.bl_info.get("version", (-1, -1, -1))
-                    for addon in addon_utils.modules()
-                    if addon.bl_info["name"] == "BlenderBIM"
-                ][0]
-            ]
-        )
-        info = {
-            "os": platform.system(),
-            "os_version": platform.version(),
-            "python_version": platform.python_version(),
-            "architecture": platform.architecture(),
-            "machine": platform.machine(),
-            "processor": platform.processor(),
-            "blender_version": bpy.app.version_string,
-            "blenderbim_version": version,
-            "ifc": False,
-        }
-
+        info = get_debug_info()
         if tool.Ifc.get():
             info.update(
                 {
@@ -76,16 +54,18 @@ class CopyDebugInformation(bpy.types.Operator):
                 }
             )
 
-        # Format it in a readable way
-        text = "\n".join(f"{k}: {v}" for k, v in info.items())
+        text = format_debug_info(info)
+
+        print("-" * 80)
         print(text)
+        print("-" * 80)
 
         if platform.system() == "Windows":
-            command = "echo | set /p nul=" + text.strip()
+            command = "echo | set /p nul=" + text
         elif platform.system() == "Darwin":  # for MacOS
-            command = 'printf "' + text.strip().replace("\n", "\\n").replace('"', "") + '" | pbcopy'
+            command = 'printf "' + text.replace("\n", "\\n").replace('"', "") + '" | pbcopy'
         else:  # Linux
-            command = 'printf "' + text.strip().replace("\n", "\\n").replace('"', "") + '" | xclip -selection clipboard'
+            command = 'printf "' + text.replace("\n", "\\n").replace('"', "") + '" | xclip -selection clipboard'
         subprocess.run(command, shell=True, check=True)
         return {"FINISHED"}
 

src/blenderbim/blenderbim/bim/module/drawing/operator.py

@@ -1515,7 +1515,14 @@ class ActivateDrawing(bpy.types.Operator):
         if not self.camera_view_point:
             viewport_position = tool.Blender.get_viewport_position()
 
-        core.activate_drawing_view(tool.Ifc, tool.Drawing, drawing=drawing)
+        try:
+            core.activate_drawing_view(tool.Ifc, tool.Blender, tool.Drawing, drawing=drawing)
+        except core.CameraNotAvailableError:
+            self.report(
+                {"ERROR"},
+                "The drawing view is not available. Ensure you have not excluded it in the active view layer.",
+            )
+            return {"CANCELLED"}
 
         if not self.camera_view_point:
             tool.Blender.set_viewport_position(viewport_position)

src/blenderbim/blenderbim/bim/module/geometry/operator.py

@@ -136,19 +136,23 @@ class AddRepresentation(bpy.types.Operator, Operator):
                 "for Profile - 2D bounding box by local XZ axes.\n"
                 "For other contexts - bounding box is 3d.",
             ),
-            ("PROJECT", "Full Representation", ""),
+            ("OBJECT", "From Object", "Copies geometry from another object"),
+            ("PROJECT", "Full Representation", "Reuses the current representation"),
         ],
         name="Representation Conversion Method",
     )
 
     def _execute(self, context):
         obj = context.active_object
-        props = obj.BIMGeometryProperties
-        ifc_context = int(props.contexts or "0") or None
+        props = context.scene.BIMGeometryProperties
+        oprops = obj.BIMGeometryProperties
+        ifc_context = int(oprops.contexts or "0") or None
         if not ifc_context:
             return
         ifc_context = tool.Ifc.get().by_id(ifc_context)
 
+        original_data = obj.data
+
         if self.representation_conversion_method == "OUTLINE":
             if ifc_context.ContextType == "Plan":
                 data = tool.Geometry.generate_outline_mesh(obj, axis="+Z")
@@ -165,17 +169,31 @@ class AddRepresentation(bpy.types.Operator, Operator):
             else:
                 data = tool.Geometry.generate_3d_box_mesh(obj)
             tool.Geometry.change_object_data(obj, data, is_global=True)
+        elif (
+            self.representation_conversion_method == "OBJECT"
+            and props.representation_from_object
+            and props.representation_from_object.data
+        ):
+            data = tool.Geometry.duplicate_object_data(props.representation_from_object)
+            tool.Geometry.change_object_data(obj, data, is_global=True)
 
-        core.add_representation(
-            tool.Ifc,
-            tool.Geometry,
-            tool.Style,
-            tool.Surveyor,
-            obj=obj,
-            context=ifc_context,
-            ifc_representation_class=None,
-            profile_set_usage=None,
-        )
+        try:
+            core.add_representation(
+                tool.Ifc,
+                tool.Geometry,
+                tool.Style,
+                tool.Surveyor,
+                obj=obj,
+                context=ifc_context,
+                ifc_representation_class=None,
+                profile_set_usage=None,
+            )
+        except core.IncompatibleRepresentationError:
+            if obj.data != original_data:
+                tool.Geometry.change_object_data(obj, original_data, is_global=True)
+                bpy.data.meshes.remove(data)
+            self.report({"ERROR"}, "No compatible representation for the context could be created.")
+            return {"CANCELLED"}
 
     def invoke(self, context, event):
         return context.window_manager.invoke_props_dialog(self)
@@ -183,6 +201,9 @@ class AddRepresentation(bpy.types.Operator, Operator):
     def draw(self, context):
         row = self.layout.row()
         row.prop(self, "representation_conversion_method", text="")
+        if self.representation_conversion_method == "OBJECT":
+            row = self.layout.row()
+            row.prop(context.scene.BIMGeometryProperties, "representation_from_object", text="")
 
 
 class SelectConnection(bpy.types.Operator, Operator):

src/blenderbim/blenderbim/bim/module/geometry/prop.py

@@ -138,3 +138,4 @@ class BIMGeometryProperties(PropertyGroup):
         name="IFC Interaction Mode",
         update=update_mode,
     )
+    representation_from_object: PointerProperty(type=bpy.types.Object)

src/blenderbim/blenderbim/bim/module/model/array.py

@@ -83,8 +83,17 @@ class EnableEditingArray(bpy.types.Operator, tool.Ifc.Operator):
     def _execute(self, context):
         obj = context.active_object
         element = tool.Ifc.get_entity(obj)
-        data = json.loads(ifcopenshell.util.element.get_pset(element, "BBIM_Array", "Data"))[self.item]
         props = obj.BIMArrayProperties
+        
+        relating_obj = props.relating_array_object
+        
+        if relating_obj:
+            element = tool.Ifc.get_entity(relating_obj)
+            parent_globalid = ifcopenshell.util.element.get_pset(element, "BBIM_Array", "Parent")
+            parent_element = tool.Ifc.get().by_guid(parent_globalid)
+            data = json.loads(ifcopenshell.util.element.get_pset(parent_element, "BBIM_Array", "Data"))[self.item]
+        else:
+            data = json.loads(ifcopenshell.util.element.get_pset(element, "BBIM_Array", "Data"))[self.item]
         props.count = data["count"]
         si_conversion = ifcopenshell.util.unit.calculate_unit_scale(tool.Ifc.get())
         props.x = data["x"] * si_conversion
@@ -93,7 +102,9 @@ class EnableEditingArray(bpy.types.Operator, tool.Ifc.Operator):
         props.use_local_space = data.get("use_local_space", False)
         props.sync_children = data.get("sync_children", False)
         props.method = data.get("method", "OFFSET")
+        
         props.is_editing = self.item
+        
         return {"FINISHED"}
 
 
@@ -137,6 +148,10 @@ class EditArray(bpy.types.Operator, tool.Ifc.Operator):
 
         tool.Blender.Modifier.Array.set_children_lock_state(element, self.item, True)
         tool.Blender.Modifier.Array.constrain_children_to_parent(element)
+
+        #clears the relating_array_object so it doesn't show again next time
+        props.relating_array_object = None
+        
         return {"FINISHED"}
 
 

src/blenderbim/blenderbim/bim/module/model/prop.py

@@ -87,6 +87,21 @@ def update_type_page(self, context):
     AuthoringData.data["paginated_relating_types"] = AuthoringData.paginated_relating_types()
 
 
+def update_relating_array_from_object(self, context):
+    bpy.ops.bim.enable_editing_array(item=self.is_editing)
+    return
+
+
+def is_object_array_applicable(self, obj):
+    element = tool.Ifc.get_entity(obj)
+    if not element:
+        return False
+    return ifcopenshell.util.element.get_pset(element, "BBIM_Array")
+
+
+
+
+
 class BIMModelProperties(PropertyGroup):
     ifc_class: bpy.props.EnumProperty(items=get_ifc_class, name="Construction Class", update=update_ifc_class)
     relating_type_id: bpy.props.EnumProperty(
@@ -203,6 +218,14 @@ class BIMArrayProperties(PropertyGroup):
         description="Regenerate all children based on the parent object",
         default=False,
     )
+    relating_array_object: bpy.props.PointerProperty(
+        type=bpy.types.Object,
+        name="Copy Array Properties",
+        update=update_relating_array_from_object,
+        poll=is_object_array_applicable,
+    )
+
+
 
 
 class BIMStairProperties(PropertyGroup):

src/blenderbim/blenderbim/bim/module/model/ui.py

@@ -223,6 +223,8 @@ class BIM_PT_array(bpy.types.Panel):
                     row = col.row(align=True)
                     row.prop(props, "z")
                     row.operator("bim.input_cursor_z_array", icon="CURSOR", text="")
+                    row = col.row(align=True)
+                    row.prop(props, "relating_array_object", icon="COPYDOWN")
                 else:
                     row = box.row(align=True)
                     name = f"{array['count']} Items ({array.get('method', 'OFFSET').capitalize()})"

src/blenderbim/blenderbim/bim/module/project/operator.py

@@ -21,6 +21,7 @@ import bpy
 import time
 import logging
 import tempfile
+import traceback
 import subprocess
 import numpy as np
 import ifcopenshell
@@ -674,19 +675,23 @@ class LoadProject(bpy.types.Operator, IFCFileSelector):
             return self.finish_loading_project(context)
 
     def finish_loading_project(self, context):
-        if not self.is_existing_ifc_file():
-            return {"FINISHED"}
+        try:
+            if not self.is_existing_ifc_file():
+                return {"FINISHED"}
 
-        if tool.Blender.is_default_scene():
-            for obj in bpy.data.objects:
-                bpy.data.objects.remove(obj)
+            if tool.Blender.is_default_scene():
+                for obj in bpy.data.objects:
+                    bpy.data.objects.remove(obj)
 
-        context.scene.BIMProperties.ifc_file = self.get_filepath()
-        context.scene.BIMProjectProperties.is_loading = True
-        context.scene.BIMProjectProperties.total_elements = len(tool.Ifc.get().by_type("IfcElement"))
-        tool.Blender.register_toolbar()
-        if not self.is_advanced:
-            bpy.ops.bim.load_project_elements()
+            context.scene.BIMProperties.ifc_file = self.get_filepath()
+            context.scene.BIMProjectProperties.is_loading = True
+            context.scene.BIMProjectProperties.total_elements = len(tool.Ifc.get().by_type("IfcElement"))
+            tool.Blender.register_toolbar()
+            if not self.is_advanced:
+                bpy.ops.bim.load_project_elements()
+        except:
+            blenderbim.last_error = traceback.format_exc()
+            raise
         return {"FINISHED"}
 
     def invoke(self, context, event):

src/blenderbim/blenderbim/bim/module/pset_template/operator.py

@@ -268,7 +268,6 @@ class RemovePropTemplate(bpy.types.Operator, Operator):
     prop_template: bpy.props.IntProperty()
 
     def _execute(self, context):
-        props = context.scene.BIMPsetTemplateProperties
         ifcopenshell.api.run(
             "pset_template.remove_prop_template",
             IfcStore.pset_template_file,
@@ -287,21 +286,21 @@ class EditPropTemplate(bpy.types.Operator, Operator):
     def _execute(self, context):
         props = context.scene.BIMPsetTemplateProperties
         if props.active_prop_template.template_type == "P_ENUMERATEDVALUE":
-            enumerator = self.generate_prop_enum(props)
+            data_type = props.active_prop_template.get_value_name()
+            prop = props.active_prop_template
+            enumerators = [getattr(ev, data_type) for ev in prop.enum_values]
         else:
-            enumerator = None
+            enumerators = None
         ifcopenshell.api.run(
             "pset_template.edit_prop_template",
             IfcStore.pset_template_file,
-            **{
-                "prop_template": IfcStore.pset_template_file.by_id(props.active_prop_template_id),
-                "attributes": {
-                    "Name": props.active_prop_template.name,
-                    "Description": props.active_prop_template.description,
-                    "PrimaryMeasureType": props.active_prop_template.primary_measure_type,
-                    "TemplateType": props.active_prop_template.template_type,
-                    "Enumerators": enumerator,
-                },
+            prop_template=IfcStore.pset_template_file.by_id(props.active_prop_template_id),
+            attributes={
+                "Name": props.active_prop_template.name,
+                "Description": props.active_prop_template.description,
+                "PrimaryMeasureType": props.active_prop_template.primary_measure_type,
+                "TemplateType": props.active_prop_template.template_type,
+                "Enumerators": enumerators,
             }
         )
         bpy.ops.bim.disable_editing_prop_template()
@@ -309,18 +308,3 @@ class EditPropTemplate(bpy.types.Operator, Operator):
         blenderbim.bim.handler.refresh_ui_data()
         if tool.Ifc.get():
             blenderbim.bim.schema.reload(tool.Ifc.get().schema)
-
-    # TODO -This will need to go into the
-    # api code at some point - vulevukusej
-    def generate_prop_enum(self, props):
-        self.file = IfcStore.pset_template_file
-        data_type = props.active_prop_template.get_value_name()
-        prop = props.active_prop_template
-        prop_enum = self.file.create_entity(
-            "IFCPROPERTYENUMERATION",
-            Name=prop.name,
-            EnumerationValues=tuple(
-                self.file.create_entity(prop.primary_measure_type, getattr(ev, data_type)) for ev in prop.enum_values
-            ),
-        )
-        return prop_enum

src/blenderbim/blenderbim/bim/module/search/operator.py

@@ -20,6 +20,7 @@ import re
 import bpy
 import json
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.selector
 from ifcopenshell.util.selector import Selector

src/blenderbim/blenderbim/bim/operator.py

@@ -90,6 +90,15 @@ class OpenUri(bpy.types.Operator):
         return {"FINISHED"}
 
 
+class CloseError(bpy.types.Operator):
+    bl_idname = "bim.close_error"
+    bl_label = "Close Error"
+
+    def execute(self, context):
+        blenderbim.last_error = None
+        return {"FINISHED"}
+
+
 class SelectURIAttribute(bpy.types.Operator):
     bl_idname = "bim.select_uri_attribute"
     bl_label = "Select URI Attribute"

src/blenderbim/blenderbim/bim/ui.py

@@ -29,8 +29,9 @@ from ifcopenshell.util.doc import (
     get_attribute_doc,
 )
 from . import ifc
-import blenderbim.tool as tool
+from blenderbim import get_debug_info
 import blenderbim.bim
+import blenderbim.tool as tool
 from blenderbim.bim.helper import IfcHeaderExtractor
 from blenderbim.bim.prop import Attribute
 
@@ -402,6 +403,17 @@ class BIM_PT_tabs(Panel):
 
             row = self.layout.row(align=True)
             row.prop(aprops, "tab", text="")
+
+            if blenderbim.last_error:
+                box = self.layout.box()
+                row = box.row(align=True)
+                row.label(text="BlenderBIM experienced an error :(", icon="ERROR")
+                row.operator("bim.close_error", text="", icon="CANCEL")
+                box.label(text="View the console for full logs.", icon="CONSOLE")
+                box.operator("bim.copy_debug_information", text="Copy Error Message To Clipboard")
+                op = box.operator("bim.open_uri", text="How Can I Fix This?")
+                op.uri = "https://docs.blenderbim.org/users/troubleshooting.html"
+
         except:
             pass  # Prior to load_post, we may not have any area properties setup
 

src/blenderbim/blenderbim/core/drawing.py

@@ -441,9 +441,19 @@ def select_assigned_product(drawing, context):
     drawing.select_assigned_product(context)
 
 
-def activate_drawing_view(ifc, drawing_tool, drawing):
+def activate_drawing_view(ifc, blender, drawing_tool, drawing):
     camera = ifc.get_object(drawing)
     if not camera:
         camera = drawing_tool.import_drawing(drawing)
         drawing_tool.import_annotations_in_group(drawing_tool.get_drawing_group(drawing))
+    blender.activate_camera(camera)
+    drawing_tool.isolate_camera_collection(camera)
+    try:
+        blender.set_active_object(camera)
+    except:
+        raise CameraNotAvailableError()
     drawing_tool.activate_drawing(camera)
+
+
+class CameraNotAvailableError(Exception):
+    pass

src/blenderbim/blenderbim/core/geometry.py

@@ -47,7 +47,7 @@ def add_representation(
     data = geometry.get_object_data(obj)
 
     if not data and ifc_representation_class != "IfcTextLiteral":
-        return
+        raise IncompatibleRepresentationError()
 
     representation = ifc.run(
         "geometry.add_representation",
@@ -63,6 +63,9 @@ def add_representation(
         profile_set_usage=profile_set_usage,
     )
 
+    if not representation:
+        raise IncompatibleRepresentationError()
+
     if geometry.is_body_representation(representation):
         [geometry.run_style_add_style(obj=mat) for mat in geometry.get_object_materials_without_styles(obj)]
         ifc.run(
@@ -221,3 +224,7 @@ def edit_similar_opening_placement(geometry, opening=None, similar_openings=None
         old_placement = similar_opening.ObjectPlacement
         similar_opening.ObjectPlacement = opening.ObjectPlacement
         geometry.delete_opening_object_placement(old_placement)
+
+
+class IncompatibleRepresentationError(Exception):
+    pass

src/blenderbim/blenderbim/core/tool.py

@@ -18,6 +18,7 @@
 
 import abc
 import inspect
+from typing import Optional
 
 # fmt: off
 # pylint: skip-file
@@ -72,20 +73,21 @@ class Aggregate:
 
 @interface
 class Blender:
-    def set_active_object(cls, obj): pass
-    def get_name(cls, ifc_class, name): pass
-    def get_selected_objects(cls): pass
-    def create_ifc_object(cls, ifc_class: str, name: str = None, data=None): pass
-    def get_obj_ifc_definition_id(cls, obj=None, obj_type=None, context=None): pass
-    def is_ifc_object(cls, obj): pass
-    def is_ifc_class_active(cls, ifc_class): pass
-    def get_viewport_context(cls): pass
-    def update_viewport(cls): pass
-    def get_default_selection_keypmap(cls): pass
-    def get_object_bounding_box(cls, obj): pass
+    def activate_camera(cls, obj): pass
     def apply_bmesh(cls, mesh, bm, obj=None): pass
-    def get_bmesh_for_mesh(cls, mesh, clean=False): pass
     def bmesh_join(cls, bm_a, bm_b, callback=None): pass
+    def create_ifc_object(cls, ifc_class: str, name: Optional[str] = None, data=None): pass
+    def get_bmesh_for_mesh(cls, mesh, clean=False): pass
+    def get_default_selection_keypmap(cls): pass
+    def get_name(cls, ifc_class, name): pass
+    def get_obj_ifc_definition_id(cls, obj=None, obj_type=None, context=None): pass
+    def get_object_bounding_box(cls, obj): pass
+    def get_selected_objects(cls): pass
+    def get_viewport_context(cls): pass
+    def is_ifc_class_active(cls, ifc_class): pass
+    def is_ifc_object(cls, obj): pass
+    def set_active_object(cls, obj): pass
+    def update_viewport(cls): pass
 
 
 @interface

src/blenderbim/blenderbim/tool/blender.py

@@ -49,6 +49,23 @@ class Blender(blenderbim.core.tool.Blender):
     OBJECT_TYPES_THAT_SUPPORT_EDIT_GPENCIL_MODE = ("GPENCIL",)
     TYPE_MANAGER_ICON = "LIGHTPROBE_VOLUME" if bpy.app.version >= (4, 1, 0) else "LIGHTPROBE_GRID"
 
+    @classmethod
+    def activate_camera(cls, obj: bpy.types.Object) -> None:
+        area = tool.Blender.get_view3d_area()
+        is_local_view = area.spaces[0].local_view is not None
+        if is_local_view:
+            # Turn off local view before activating drawing, and then turn it on again.
+            for a in bpy.context.screen.areas:
+                if a.type == "VIEW_3D":
+                    override = bpy.context.copy()
+                    override["area"] = a
+                    bpy.ops.view3d.localview(override)
+            bpy.context.scene.camera = obj
+            bpy.ops.view3d.localview(override)
+        else:
+            bpy.context.scene.camera = obj
+        area.spaces[0].region_3d.view_perspective = "CAMERA"
+
     @classmethod
     def get_area_props(cls, context: bpy.types.Context) -> Any:
         try:
@@ -845,9 +862,7 @@ class Blender(blenderbim.core.tool.Blender):
             bpy.utils.register_tool(ws_model.PipeTool, after={"bim.duct_tool"}, separator=False, group=False)
             bpy.utils.register_tool(ws_model.BimTool, after={"bim.pipe_tool"}, separator=False, group=False)
             bpy.utils.register_tool(ws_drawing.AnnotationTool, after={"bim.bim_tool"}, separator=True, group=False)
-            bpy.utils.register_tool(
-                ws_spatial.SpatialTool, after={"bim.annotation_tool"}, separator=False, group=False
-            )
+            bpy.utils.register_tool(ws_spatial.SpatialTool, after={"bim.annotation_tool"}, separator=False, group=False)
             bpy.utils.register_tool(
                 ws_structural.StructuralTool, after={"bim.spatial_tool"}, separator=False, group=False
             )

src/blenderbim/blenderbim/tool/brick.py

@@ -19,6 +19,7 @@
 import os
 import bpy
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.brick
 import blenderbim.core.tool
 import blenderbim.tool as tool
@@ -604,4 +605,4 @@ class BrickStore:
     def set_last_saved(cls):
         save = os.path.getmtime(BrickStore.path)
         save = datetime.datetime.fromtimestamp(save)
-        BrickStore.last_saved = f"{save.year}-{save.month}-{save.day} {save.hour}:{save.minute}"
+        BrickStore.last_saved = f"{save.year}-{save.month}-{save.day} {save.hour}:{save.minute}"

src/blenderbim/blenderbim/tool/drawing.py

@@ -1743,21 +1743,7 @@ class Drawing(blenderbim.core.tool.Drawing):
         bpy.ops.bim.activate_model()
 
     @classmethod
-    def activate_drawing(cls, camera: bpy.types.Object) -> None:
-        area = tool.Blender.get_view3d_area()
-        is_local_view = area.spaces[0].local_view is not None
-        if is_local_view:
-            # turn off local view before activating drawing, and then turn it on again.
-            for a in bpy.context.screen.areas:
-                if a.type == "VIEW_3D":
-                    override = bpy.context.copy()
-                    override["area"] = a
-                    bpy.ops.view3d.localview(override)
-            bpy.context.scene.camera = camera
-            bpy.ops.view3d.localview(override)
-        else:
-            bpy.context.scene.camera = camera
-        area.spaces[0].region_3d.view_perspective = "CAMERA"
+    def isolate_camera_collection(cls, camera: bpy.types.Object) -> None:
         views_collection = bpy.data.collections.get("Views")
         for collection in views_collection.children:
             # We assume the project collection is at the top level
@@ -1775,8 +1761,9 @@ class Drawing(blenderbim.core.tool.Drawing):
                         camera.BIMObjectProperties.collection.name
                     ].hide_viewport = False
         camera.BIMObjectProperties.collection.hide_render = False
-        tool.Spatial.set_active_object(camera)
 
+    @classmethod
+    def activate_drawing(cls, camera: bpy.types.Object) -> None:
         # Sync viewport objects visibility with selectors from EPset_Drawing/Include and /Exclude
         drawing = tool.Ifc.get_entity(camera)
 

src/blenderbim/blenderbim/tool/geometry.py

@@ -24,6 +24,7 @@ import logging
 import numpy as np
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.system
 import blenderbim.core.tool

src/blenderbim/blenderbim/tool/search.py

@@ -3,6 +3,7 @@ import json
 import lark
 import blenderbim.core.tool
 import blenderbim.tool as tool
+import ifcopenshell.guid
 import ifcopenshell.util.selector
 from ifcopenshell.util.selector import Selector
 from blenderbim.bim.prop import BIMFacet

src/blenderbim/blenderbim/tool/spatial.py

@@ -111,16 +111,17 @@ class Spatial(blenderbim.core.tool.Spatial):
         for rel in parent.IsDecomposedBy or []:
             related_objects = []
             for element in rel.RelatedObjects:
+                # skip objects without placements
+                if not element.is_a("IfcProduct"):
+                    continue
                 related_objects.append((element, ifcopenshell.util.placement.get_storey_elevation(element)))
             related_objects = sorted(related_objects, key=lambda e: e[1])
-            for element in related_objects:
-                element = element[0]
+            for element, _ in related_objects:
                 new = props.containers.add()
                 new.name = element.Name or "Unnamed"
                 new.long_name = element.LongName or ""
                 new.has_decomposition = bool(element.IsDecomposedBy)
                 new.ifc_definition_id = element.id()
-                new.elevation = element[1]
 
     @classmethod
     def run_root_copy_class(cls, obj=None):

src/blenderbim/docs/devs/installation.rst

@@ -13,14 +13,14 @@ Unstable installation
 
 **Unstable installation** is almost the same as **Stable installation**, except
 that they are typically updated every day. Simply download a daily build from
-the `Github releases page
-<https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then follow the same
-instructions as the **Stable installation**.
+the `GitHub releases page
+<https://github.com/IfcOpenShell/IfcOpenShell/releases>`__, then follow the
+usual :doc:`installation instructions</users/installation>`.
 
 You will need to choose which build to download.
 
 - If you are on Blender >=4.1, choose py311
-- If you are on Blender >=3.1 and <=4.0, choose py10
+- If you are on Blender >=3.1 and <=4.0, choose py310
 - If you are on Blender >=2.93 and <3.1, choose py39
 - Choose ``linux``, ``macos`` (Apple Intel), ``macosm1`` (Apple Silicon), or
   ``win`` depending on your operating system

src/blenderbim/docs/devs/writing_docs.rst

@@ -16,9 +16,12 @@ You can press the edit button on the top right on any documentation page to
 quickly edit their content.
 
 You can link to `external websites
-<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_.
-You can also link to sections on the same page, like `Writing technical
-documentation`_. You can link to other pages, like :doc:`Hello
+<https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html>`_
+(note the space between the url and the link text).  You can also link to
+sections on the same page, like :ref:`devs/writing_docs:Writing technical
+documentation` or with :ref:`custom text<devs/writing_docs:writing technical
+documentation>`. Traditional references like `Writing technical documentation`_
+work too but are discouraged. You can link to other pages, like :doc:`Hello
 World<hello_world>` or sections within other pages, like
 :ref:`devs/installation:unstable installation`. We have ``autosectionlabel``
 enabled so it is not necessary to manually create labels.

src/blenderbim/docs/index.rst

@@ -32,6 +32,7 @@ Learn how to model a small building and create simple architectural plans, secti
    users/git_support
    users/other_addons
    users/general_usage
+   users/troubleshooting
 
 .. toctree::
    :hidden:

src/blenderbim/docs/users/installation.rst

@@ -58,6 +58,32 @@ You can enable add-ons permanently by using ``Save User Settings`` from the Addo
 
 .. _where is the add-on installed:
 
+Updating
+--------
+
+First follow the `Uninstalling`_ section below, then install the latest version.
+
+Uninstalling
+------------
+
+Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender,
+you have to **first disable the BlenderBIM Add-on in your Blender preferences**
+by pressing the checkbox next to the add-on, then **restart Blender**. It is
+critical to follow this sequence of disabling first, and then restarting.
+
+After restarting, you can uninstall the BlenderBIM Add-on by pressing the
+``Remove`` button in the Blender preferences window.
+
+Alternatively, you may uninstall manually by deleting the ``blenderbim``
+directory in :ref:`your Blender add-ons directory<where is the add-on
+installed>`.
+
+.. warning::
+
+    It is important to follow the sequence of disabling, restarting, then removing.
+    If you do not restart Blender, the add-on will fail to remove correctly, and you
+    will need to uninstall manually.
+
 Where is the add-on installed?
 ------------------------------
 
@@ -66,118 +92,44 @@ Upon installation, the BlenderBIM Add-on is stored in the
 folder. However, the location of your Blender configuration folder depends on
 how you have installed Blender.
 
-If you downloaded Blender as a ``.zip`` file without running an installer, you
-will find the Blender configuration folder in the following directory, where
-``X.XX`` is the Blender version:
+If you downloaded Blender as a ``.zip`` file without running an installer, the
+BlenderBIM Add-on will be installed in the following directory, where ``X.XX``
+is the Blender version:
+
 ::
 
-    /path/to/blender/X.XX/
+    /path/to/blender/X.XX/scripts/addons/blenderbim/
 
 Otherwise, if you installed Blender using an installation package, the Blender
 configuration folder depends on which operating system you use.
 
 On Linux, if you are installing the add-on as a user:
+
 ::
 
-    ~/.config/blender/X.XX/
+    ~/.config/blender/X.XX/scripts/addons/blenderbim/
 
 On Linux, if you are deploying the add-on system-wide (this may also depend on
 your Linux distribution):
+
 ::
 
-    /usr/share/blender/X.XX/
+    /usr/share/blender/X.XX/scripts/addons/blenderbim/
 
 On Mac, if you are installing the add-on as a user:
+
 ::
 
-    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/
+    /Users/{YOUR_USER}/Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/
 
 On Mac, if you are deploying the add-on system-wide:
 
 ::
 
-    /Library/Application Support/Blender/X.XX/
+    /Library/Application Support/Blender/X.XX/scripts/addons/blenderbim/
 
 On Windows:
+
 ::
 
-    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\
-
-Updating
---------
-
-First uninstall the current BlenderBIM add-on, then install the latest version.
-
-Uninstalling
-------------
-
-Navigate to ``Edit > Preferences > Add-ons``. Due to a limitation in Blender,
-you have to first disable the BlenderBIM Add-on in your Blender preferences by
-pressing the checkbox next to the add-on, then restart Blender. After
-restarting, you can uninstall the BlenderBIM Add-on by pressing the ``Remove``
-button in the Blender preferences window.
-
-Alternatively, you may uninstall manually by deleting the ``blenderbim/``
-directory in your Blender add-ons directory.
-
-.. warning::
-
-    It is important to follow the sequence of disabling, restarting, then removing.
-    If you do not restart Blender, the add-on will fail to remove correctly, and you
-    will need to uninstall manually.
-
-
-FAQ
----
-
-1. **Some other error prevents me from installing or doing basic functions with
-   the add-on. Is it specific to my environment?**
-
-   Sometimes it is helpful to try installing and using the BlenderBIM Add-on on
-   a "clean environment". A clean environment is defined as a fresh Blender
-   installation with no other add-ons enabled with factory settings.
-
-   To quickly test in a clean environment, find your Blender configuration
-   folder based on the `where is the add-on installed`_ section. Rename the
-   folder from ``X.XX`` to something else like ``X.XX_backup``, then restart
-   Blender and try follow the installation instructions again.
-
-   If this fixes your issue, consider disabling other add-ons one by one until
-   you find a conflict as a next step to isolating the issue.
-
-2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"**
-
-   If you are using a Mac, be sure to use the Mac Silicon version if you have a
-   newer Mac. The only exception is if you have installed Blender using Steam
-   on a Mac, in which case you need to use the Mac Intel download.
-
-   For all other scenarios, check the BlenderBIM Add-on zip file which you
-   downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in
-   the name. See the instructions in the :ref:`devs/installation:unstable
-   installation` section to check that you have installed the correct version.
-
-3. **I am on Ubuntu and get an error similar to "ImportError:
-   /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"**
-
-   Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS.
-   If you have an older Ubuntu version, you can either upgrade to 19.10 or above,
-   or you'll need to compile IfcOpenShell yourself.
-
-4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**"
-
-   If you have installed Blender from another source instead of from
-   `Blender.org <https://www.blender.org/download/>`__, such as from your
-   distro's package repositories, then you may be missing some modules like
-   ``numpy``. Try installing it manually like ``apt install python-numpy``.
-
-5. **I get an error similar to RuntimeError: Instance #1234 not found**
-
-   Blender saves and loads projects to a ``.blend`` file. However. the
-   BlenderBIM Add-on works with native IFC, and this means instead of saving
-   and loading ``.blend`` files, you should instead save and load the ``.ifc``
-   project.
-
-   If you have opened a ``.blend`` file, there is a risk that the contents of
-   the ``.blend`` session do not correlate to the contents of the ``.ifc``,
-   which can cause this error. Unless you are an advanced user, only save and
-   load ``.ifc`` files.
+    C:\Users\{YOUR_USER}\AppData\Roaming\Blender Foundation\X.XX\scripts\addons\blenderbim\

src/blenderbim/docs/users/troubleshooting.rst

@@ -0,0 +1,93 @@
+Troubleshooting
+===============
+
+The BlenderBIM Add-on is alpha software. There are many bugs! When something
+goes wrong, you may see some computer code flash up on your screen. You may
+also see an error message:
+
+.. image:: images/error-message.png
+
+**Don't panic!** Click on the button that says **Copy Error Message To
+Clipboard**. You will need to paste this text in a bug report.
+
+If you do not have a GitHub account, you will need to sign up to report a bug.
+In addition to pasting the error message text, please also describe what you
+were doing, and attach your IFC file or screenshots if relevant.
+
+.. container:: blockbutton
+
+    `Report a bug <https://github.com/IfcOpenShell/IfcOpenShell/issues/new>`__
+
+If your issue is particularly complex, you can also chat live with developers
+or other powerusers.
+
+.. container:: blockbutton
+
+    `Chat live with a developer <https://osarch.org/chat>`_
+
+Installation issues
+-------------------
+
+If you are unable to install the BlenderBIM Add-on, make sure you are using
+**Blender 4.1** installed from https://blender.org/ and are installing the
+latest version from https://blenderbim.org.
+
+Other common solutions are listed below. If none of these fix the problem, you
+can `report a bug <https://github.com/ifcopenshell/ifcopenshell/issues>`_ or
+`live chat with a developer <https://osarch.org/chat/>`_.
+
+1. **Some other error prevents me from installing or doing basic functions with
+   the add-on. Is it specific to my environment?**
+
+   Try installing and using the BlenderBIM Add-on on a "clean environment". A
+   clean environment is a fresh Blender installation with no other add-ons
+   enabled with factory settings.
+
+   To quickly test in a clean environment, first :ref:`find your Blender
+   configuration folder<users/installation:where is the add-on installed?>`.
+   Rename the folder from ``X.XX`` to something else like ``X.XX_backup``, then
+   restart Blender and try follow the :doc:`installation
+   instructions<installation>` again.
+
+   If this fixes your issue, consider disabling other add-ons one by one until
+   you find a conflict as a next step to isolating the issue.
+
+2. **I get an error similar to "ImportError: IfcOpenShell not built for 'linux/64bit/python3.10'"**
+
+   If you are using a Mac, be sure to use the Mac Silicon version if you have a
+   newer Mac. The only exception is if you have installed Blender using Steam
+   on a Mac, in which case you need to use the Mac Intel download.
+
+   For all other scenarios, check the BlenderBIM Add-on zip file which you
+   downloaded. The zip will have either ``py39``, ``py310``, or ``py311`` in
+   the name. See the instructions in the :ref:`devs/installation:unstable
+   installation` section to check that you have installed the correct version.
+
+3. **I am on Ubuntu and get an error similar to "ImportError:
+   /lib/x86_64-linux-gnu/libm.so.6: version GLIBC_2.29 not found"**
+
+   Our latest package which uses IfcOpenShell v0.7.0 is built using Ubuntu 20 LTS.
+   If you have an older Ubuntu version, you can either upgrade to 19.10 or above,
+   or you'll need to compile IfcOpenShell yourself.
+
+4. **I get an error saying "ModuleNotFoundError: No module named 'numpy'"**"
+
+   If you have installed Blender from another source instead of from
+   `Blender.org <https://www.blender.org/download/>`__, such as from your
+   distro's package repositories, then you may be missing some modules like
+   ``numpy``. Try installing it manually like ``apt install python-numpy``.
+
+Common issues
+-------------
+
+1. **I get an error similar to RuntimeError: Instance #1234 not found**
+
+   Blender saves and loads projects to a ``.blend`` file. However. the
+   BlenderBIM Add-on works with native IFC, and this means instead of saving
+   and loading ``.blend`` files, you should instead save and load the ``.ifc``
+   project.
+
+   If you have opened a ``.blend`` file, there is a risk that the contents of
+   the ``.blend`` session do not correlate to the contents of the ``.ifc``,
+   which can cause this error. Unless you are an advanced user, only save and
+   load ``.ifc`` files.

src/blenderbim/scripts/classifications/xml_classification.py

@@ -4,6 +4,7 @@
 
 import xml.etree.ElementTree as ET
 import ifcopenshell
+import ifcopenshell.guid
 import os
 
 class IFC4Extractor:

src/blenderbim/scripts/dxf2ifc.py

@@ -17,6 +17,7 @@
 # along with BlenderBIM Add-on.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
 import ezdxf
 
 

src/blenderbim/scripts/obj2ifc-meshlab.py

@@ -23,6 +23,7 @@ import pymeshlab
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.api.owner.settings
+import ifcopenshell.guid
 from pathlib import Path
 
 import numpy as np

src/blenderbim/scripts/obj2ifc.py

@@ -23,6 +23,7 @@ import pywavefront
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.api.owner.settings
+import ifcopenshell.guid
 from pathlib import Path
 
 import numpy as np

src/blenderbim/test/tool/test_brick.py

@@ -22,6 +22,7 @@ import brickschema
 import brickschema.persistent
 from brickschema.namespaces import REF, A
 import ifcopenshell
+import ifcopenshell.guid
 import blenderbim.core.tool
 import blenderbim.tool as tool
 from rdflib.namespace import RDF

src/blenderbim/test/tool/test_drawing.py

@@ -21,6 +21,7 @@ from pathlib import Path
 import bpy
 import mathutils
 import ifcopenshell
+import ifcopenshell.guid
 import blenderbim.core.tool
 import blenderbim.tool as tool
 from test.bim.bootstrap import NewFile

src/ifc2ca/_deprecated/ca2ifc.py

@@ -19,6 +19,7 @@
 
 import json
 import ifcopenshell
+import ifcopenshell.guid
 import os
 from datetime import datetime
 

src/ifccityjson/ifccityjson/cityjson2ifc/cityjson2ifc.py

@@ -20,6 +20,7 @@
 import os
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 from datetime import datetime
 
 from .geometry import GeometryIO

src/ifcfm/ifcfm/basic.py

@@ -72,8 +72,8 @@ def get_facility_data(ifc_file, element):
         "ModelProjectID": ifc_file.by_type("IfcProject")[0].GlobalId,
         "ModelSiteID": getattr(get_facility_parent(element, "IfcSite"), "GlobalId", None),
         "ModelBuildingID": element.GlobalId,
-        "LinearUnits": "millimeters",
-        "AreaUnits": "square meters",
+        "LengthUnit": "millimeters",
+        "AreaUnit": "square meters",
         "Phase": ifc_file.by_type("IfcProject")[0].Phase,
     }
 
@@ -99,7 +99,7 @@ def get_space_data(ifc_file, element):
         "Description": element.LongName,
         "ClassificationIdentification": get_classification_identification(element),
         "ClassificationName": get_classification_name(element),
-        "LevelName": getattr(get_facility_parent(element, "IfcBuildingStorey"), "Name", None),
+        "StoreyName": getattr(get_facility_parent(element, "IfcBuildingStorey"), "Name", None),
         "OrganizationName": get_owner_name(element),
         "CreationDate": get_owner_creation_date(element),
         "ModelSoftware": get_owner_application(element),
@@ -261,8 +261,8 @@ config = {
                 "ModelProjectID",
                 "ModelSiteID",
                 "ModelBuildingID",
-                "LinearUnits",
-                "AreaUnits",
+                "LengthUnit",
+                "AreaUnit",
                 "Phase",
             ],
             "colours": "ppppreeeeesss",
@@ -295,7 +295,7 @@ config = {
                 "Description",
                 "ClassificationIdentification",
                 "ClassificationName",
-                "LevelName",
+                "StoreyName",
                 "OrganizationName",
                 "CreationDate",
                 "ModelSoftware",
@@ -305,7 +305,7 @@ config = {
                 "NetFloorArea",
             ],
             "colours": "ppprreeess",
-            "sort": [{"name": "LevelName", "order": "ASC"}, {"name": "Name", "order": "ASC"}],
+            "sort": [{"name": "StoreyName", "order": "ASC"}, {"name": "Name", "order": "ASC"}],
             "get_category_elements": get_spaces,
             "get_element_data": get_space_data,
         },

src/ifcfm/ifcfm/cobie24legacy.py

@@ -17,6 +17,7 @@
 # along with IfcFM.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.fm
 import ifcopenshell.util.date
 import ifcopenshell.util.system

src/ifcopenshell-python/docs/ifcopenshell-python/selector_syntax.rst

@@ -186,6 +186,7 @@ Valid keys are:
     "``material`` or ``mat``", "Gets the assigned material, which may be a material set."
     "``item`` or ``i``", "If the previous key returns a material set, gets the relevant material set items"
     "``materials`` or ``mats``", "Gets a list of IfcMaterials assigned directly or indirectly (such as via a material set) to the element"
+    "``profiles``", "Gets a list of IfcProfileDefs assigned (such as via a material profile) or used (such as in an extrusion) in the element"
     "``x``", "Gets the X coordinate of the element's placement"
     "``y``", "Gets the Y coordinate of the element's placement"
     "``z``", "Gets the Z coordinate of the element's placement"

src/ifcopenshell-python/ifcopenshell/__init__.py

@@ -86,6 +86,18 @@ from .file import file
 from .entity_instance import entity_instance, register_schema_attributes
 from .sql import sqlite, sqlite_entity
 
+# explicitly specify available imported symbols
+# (it's a requirement for a typed library)
+__all__ = [
+    "ifcopenshell_wrapper",
+    "file",
+    "entity_instance",
+    "sqlite",
+    "sqlite_entity",
+    "stream",
+    "stream_entity",
+]
+
 try:
     from .stream import stream, stream_entity
 except:

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

@@ -23,11 +23,23 @@ the rules of the IFC schema. This API module provides simple to use authoring
 functions that hide this complexity from you. Things like managing differences
 between IFC versions, tracking owernship changes, or cleaning up after orphaned
 relationships are all handled automatically.
+
+If you're new to IFC authoring, start by looking at the following APIs:
+
+- See :func:`ifcopenshell.api.project.create_file` to create a new IFC.
+- See :func:`ifcopenshell.api.root.create_entity` to create new entities, like
+  the mandatory IfcProject, and then an IfcSite, IfcWall, etc.
+- See :func:`ifcopenshell.api.aggregate.assign_object` to create a spatial
+  hierarchy.
+- See :func:`ifcopenshell.api.spatial.assign_container` to place physical
+  elements (e.g. walls) inside spatial elements (e.g. building storeys).
+
+Also see how to `create a simple model from scratch
+<https://docs.ifcopenshell.org/ifcopenshell-python/code_examples.html#create-a-simple-model-from-scratch>`_.
 """
 
 import json
 import numpy
-import pkgutil
 import inspect
 import importlib
 import ifcopenshell
@@ -158,31 +170,6 @@ def run(
         for listener in pre_listeners.get(usecase_path, {}).values():
             listener(usecase_path, ifc_file, settings)
 
-
-    # TODO: settings serialization for client-server systems
-    # def serialise_entity_instance(entity):
-    #     return {"cast_type": "entity_instance", "value": entity.id(), "Name": getattr(entity, "Name", None)}
-    # vcs_settings = settings.copy()
-    # for key, value in settings.items():
-    #     if isinstance(value, ifcopenshell.entity_instance):
-    #         vcs_settings[key] = serialise_entity_instance(value)
-    #     elif isinstance(value, numpy.ndarray):
-    #         vcs_settings[key] = {"cast_type": "ndarray", "value": value.tolist()}
-    #     elif isinstance(value, list) and value and isinstance(value[0], ifcopenshell.entity_instance):
-    #         vcs_settings[key] = [serialise_entity_instance(i) for i in value]
-    if "add_representation" in usecase_path:
-        pass
-        # print(usecase_path, "{ ... settings too complex right now ... }")
-    elif "owner." in usecase_path:
-        pass
-    else:
-        pass
-        # print(vcs_settings)
-        # try:
-        #    print(usecase_path, json.dumps(vcs_settings))
-        # except:
-        #    print(usecase_path, vcs_settings)
-
     usecase_class = CACHED_USECASE_CLASSES.get(usecase_path)
     if usecase_class is None:
         importlib.import_module(f"ifcopenshell.api.{usecase_path}")
@@ -296,6 +283,29 @@ def extract_docs(module, usecase):
     return node_data
 
 
+def serialise_settings(settings):
+    def serialise_entity_instance(entity):
+        return {"cast_type": "entity_instance", "value": entity.id(), "Name": getattr(entity, "Name", None)}
+
+    vcs_settings = settings.copy()
+    for key, value in settings.items():
+        if isinstance(value, ifcopenshell.entity_instance):
+            vcs_settings[key] = serialise_entity_instance(value)
+        elif isinstance(value, numpy.ndarray):
+            vcs_settings[key] = {"cast_type": "ndarray", "value": value.tolist()}
+        elif isinstance(value, list) and value and isinstance(value[0], ifcopenshell.entity_instance):
+            vcs_settings[key] = [serialise_entity_instance(i) for i in value]
+        else:
+            try:
+                vcs_settings[key] = str(value)
+            except:
+                vcs_settings[key] = "n/a"
+    try:
+        return json.dumps(vcs_settings)
+    except:
+        return str(vcs_settings)
+
+
 def wrap_usecase(usecase_path, usecase):
     """Wraps an API function in pre/post listeners."""
 
@@ -303,7 +313,9 @@ def wrap_usecase(usecase_path, usecase):
         ifc_file = args[0] if args else None
         nonlocal usecase_path
         if should_run_listeners:
-            for listener in pre_listeners.get(usecase_path, {}).values():
+            listeners = list(pre_listeners.get(usecase_path, {}).values())
+            listeners += pre_listeners.get("*", {}).values()
+            for listener in listeners:
                 listener(usecase_path, ifc_file, settings)
 
         # see #4531
@@ -317,7 +329,9 @@ def wrap_usecase(usecase_path, usecase):
             raise TypeError(msg) from e
 
         if should_run_listeners:
-            for listener in post_listeners.get(usecase_path, {}).values():
+            listeners = list(post_listeners.get(usecase_path, {}).values())
+            listeners += post_listeners.get("*", {}).values()
+            for listener in listeners:
                 listener(usecase_path, ifc_file, settings)
 
         return result
@@ -328,50 +342,16 @@ def wrap_usecase(usecase_path, usecase):
     return wrapper
 
 
-# Expose all submodules. This means that the user can just type `import ifcopenshell.api`.
-import ifcopenshell.api.aggregate as aggregate
-import ifcopenshell.api.attribute as attribute
-import ifcopenshell.api.boundary as boundary
-import ifcopenshell.api.classification as classification
-import ifcopenshell.api.constraint as constraint
-import ifcopenshell.api.context as context
-import ifcopenshell.api.control as control
-import ifcopenshell.api.cost as cost
-import ifcopenshell.api.document as document
-import ifcopenshell.api.drawing as drawing
-import ifcopenshell.api.geometry as geometry
-import ifcopenshell.api.georeference as georeference
-import ifcopenshell.api.grid as grid
-import ifcopenshell.api.group as group
-import ifcopenshell.api.layer as layer
-import ifcopenshell.api.library as library
-import ifcopenshell.api.material as material
-import ifcopenshell.api.nest as nest
-import ifcopenshell.api.owner as owner
-import ifcopenshell.api.profile as profile
-import ifcopenshell.api.project as project
-import ifcopenshell.api.pset as pset
-import ifcopenshell.api.pset_template as pset_template
-import ifcopenshell.api.resource as resource
-import ifcopenshell.api.root as root
-import ifcopenshell.api.sequence as sequence
-import ifcopenshell.api.spatial as spatial
-import ifcopenshell.api.structural as structural
-import ifcopenshell.api.style as style
-import ifcopenshell.api.system as system
-import ifcopenshell.api.type as type  # Whoohoo!
-import ifcopenshell.api.unit as unit
-import ifcopenshell.api.void as void
+def wrap_usecases(path, name):
+    """This developer feature wraps an API module's usecases with listeners."""
+    import sys
+    import pkgutil
 
-# Wrap all submodule usecases with listeners.
-# This for loop also conveniently ensures that the above imports are comprehensive.
-for loader, module_name, is_pkg in pkgutil.iter_modules(__path__, __name__ + "."):
-    # Check if it's a direct child (only one level deep)
-    if module_name.count(".") == __name__.count(".") + 1:
-        module_name = module_name.split(".")[-1]
-        module = globals()[module_name]
-        for usecase_name in vars(module):
-            usecase = getattr(module, usecase_name)
-            if callable(usecase):
-                usecase_path = f"{module_name}.{usecase_name}"
-                setattr(module, usecase_name, wrap_usecase(usecase_path, usecase))
+    module_name = name.split(".")[-1]
+    module = sys.modules[name]
+    for loader, usecase_name, is_pkg in pkgutil.iter_modules(path):
+        # We may not be able to get the usecase if we are missing a dependency.
+        usecase = getattr(module, usecase_name, None)
+        if callable(usecase):
+            usecase_path = f"{module_name}.{usecase_name}"
+            setattr(module, usecase_name, wrap_usecase(usecase_path, usecase))

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

@@ -16,12 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
-"""Aggregates are the concept of breaking down larger wholes into smaller parts.
+"""Aggregates is the concept of breaking down larger wholes into smaller parts.
 
-One common use is spatial elements, such as how a site has multiple buildings,
-and a building has multiple storeys. Another is for regular elements, such as
-how a wall is made out of members and coverings.
+For example, spatial elements such as sites are broken down into one or more
+buildings, and a building is broken down into storeys. Another example is for
+physical elements, such as how a wall is made out of members and coverings.
 """
 
+from .. import wrap_usecases
 from .assign_object import assign_object
 from .unassign_object import unassign_object
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/aggregate/assign_object.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.placement
 from typing import Union

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

@@ -16,4 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Basic modification of the attributes of an element.
+
+All IFC entities have attributes. Some of these attributes contain rules about
+inheritance and what they are allowed to contain. These usecases make sure that
+any editing complies with these rules.
+"""
+
+from .. import wrap_usecases
 from .edit_attributes import edit_attributes
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/attribute/edit_attributes.py

@@ -17,9 +17,11 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api
+import ifcopenshell.util.element
+from typing import Any
 
 
-def edit_attributes(file, product=None, attributes=None) -> None:
+def edit_attributes(file: ifcopenshell.file, product: ifcopenshell.entity_instance, attributes: dict[str, Any]) -> None:
     """Edit the attributes of a product
 
     All IFC entities have attributes. Normally they can be edited directly,
@@ -31,7 +33,7 @@ def edit_attributes(file, product=None, attributes=None) -> None:
         entity.
     :type product: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

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

@@ -18,9 +18,15 @@
 
 """Boundaries are primarily used for representing virtual interfaces between
 spaces for energy analysis.
+
+Boundaries may be associated with spaces or physical elements that enclose
+spaces such as walls, doors, and windows.
 """
 
+from .. import wrap_usecases
 from .assign_connection_geometry import assign_connection_geometry
 from .copy_boundary import copy_boundary
 from .edit_attributes import edit_attributes
 from .remove_boundary import remove_boundary
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/boundary/assign_connection_geometry.py

@@ -17,17 +17,18 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.util.unit
+from typing import Optional
 
 
 def assign_connection_geometry(
-    file,
-    rel_space_boundary=None,
-    outer_boundary=None,
-    inner_boundaries=None,
-    location=None,
-    axis=None,
-    ref_direction=None,
-    unit_scale=None,
+    file: ifcopenshell.file,
+    rel_space_boundary: ifcopenshell.entity_instance,
+    outer_boundary: list[tuple[float, float]],
+    location: tuple[float, float, float],
+    axis: tuple[float, float, float],
+    ref_direction: tuple[float, float, float],
+    inner_boundaries: Optional[list[list[tuple[float, float]]]] = None,
+    unit_scale: Optional[float] = None,
 ) -> None:
     """Create and assign a connection geometry to a space boundary relationship
 
@@ -44,24 +45,24 @@ def assign_connection_geometry(
         polyline.  The last point will connect to the first point. Each
         point is represented by an interable of 2 floats. The coordinates of
         the points are relative to the positional matrix arguments.
-    :type outer_boundary: list[list[float]]
+    :type outer_boundary: list[tuple[float, float]]
     :param inner_boundaries: A list of zero or more inner boundaries to use
         for the plane. Each boundary is represented by an open polyline, as
         defined by the outer_boundary argument.
-    :type inner_boundaries: list[list[list[float]]], optional
+    :type inner_boundaries: list[list[tuple[float, float]]], optional
     :param location: The local origin of the connection geometry, defined as
         an XYZ coordinate relative to the placement of the space that is
         being bounded.
-    :type location: list[float]
+    :type location: tuple[float, float, float]
     :param axis: The local X axis of the connection geometry, defined as an
         XYZ vector relative to the placement of the space that is being
         bounded.
-    :type axis: list[float]
+    :type axis: tuple[float, float, float]
     :param ref_direction: The local Z axis of the connection geometry,
         defined as an XYZ vector relative to the placement of the space that
         is being bounded. The Y vector is automatically derived using the
         right hand rule.
-    :type ref_direction: list[float]
+    :type ref_direction: tuple[float, float, float]
     :param unit_scale: The unit scale as calculated by
         ifcopenshell.util.unit.calculate_unit_scale. If not provided, it
         will be automatically calculated for you.

src/ifcopenshell-python/ifcopenshell/api/boundary/copy_boundary.py

@@ -19,13 +19,13 @@
 import ifcopenshell.util.element
 
 
-def copy_boundary(file, boundary=None) -> None:
+def copy_boundary(file: ifcopenshell.file, boundary: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """Copies a space boundary
 
     :param boundary: The IfcRelSpaceBoundary you want to copy.
     :type boundary: ifcopenshell.entity_instance
-    :return: None
-    :rtype: None
+    :return: Duplicate of the IfcRelSpaceBoundary
+    :rtype: ifcopenshell.entity_instance
 
     Example:
 

src/ifcopenshell-python/ifcopenshell/api/boundary/edit_attributes.py

@@ -15,15 +15,17 @@
 #
 # 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
+from typing import Optional
 
 
 def edit_attributes(
-    file,
-    entity=None,
-    relating_space=None,
-    related_building_element=None,
-    parent_boundary=None,
-    corresponding_boundary=None,
+    file: ifcopenshell.file,
+    entity: ifcopenshell.entity_instance,
+    relating_space: ifcopenshell.entity_instance,
+    related_building_element: ifcopenshell.entity_instance,
+    parent_boundary: Optional[ifcopenshell.entity_instance] = None,
+    corresponding_boundary: Optional[ifcopenshell.entity_instance] = None,
 ) -> None:
     """Modify the relationships of a space boundary relationship
 

src/ifcopenshell-python/ifcopenshell/api/boundary/remove_boundary.py

@@ -20,7 +20,7 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def remove_boundary(file, boundary=None) -> None:
+def remove_boundary(file: ifcopenshell.file, boundary: ifcopenshell.entity_instance) -> None:
     """Removes a space boundary
 
     The relating space or related building element is untouched. Only the

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

@@ -16,9 +16,23 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Classification systems are a way of categorising objects
+
+Although IFC itself comes with a built-in classification hierarchy (e.g.
+IfcWall and its predefined types of PARTITIONING, etc), there are many external
+or custom classification systems such as Uniclass, Omniclass and more. IFC is
+able to integrate with any external classification system.
+
+This API allows you to manage and assign external classification systems and
+references.
+"""
+
+from .. import wrap_usecases
 from .add_classification import add_classification
 from .add_reference import add_reference
 from .edit_classification import edit_classification
 from .edit_reference import edit_reference
 from .remove_classification import remove_classification
 from .remove_reference import remove_reference
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/classification/add_classification.py

@@ -17,6 +17,7 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
 import ifcopenshell.util.schema
 import ifcopenshell.util.date
 from typing import Union

src/ifcopenshell-python/ifcopenshell/api/classification/add_reference.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 import ifcopenshell.util.element
 import ifcopenshell.util.schema
 from typing import Optional, Union

src/ifcopenshell-python/ifcopenshell/api/classification/edit_classification.py

@@ -15,9 +15,13 @@
 #
 # 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
+from typing import Any
 
 
-def edit_classification(file, classification=None, attributes=None) -> None:
+def edit_classification(
+    file: ifcopenshell.file, classification: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcClassification
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_classification(file, classification=None, attributes=None) -> None:
     :param classification: The IfcClassification entity you want to edit
     :type classification: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/classification/edit_reference.py

@@ -15,9 +15,13 @@
 #
 # 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
+from typing import Any
 
 
-def edit_reference(file, reference=None, attributes=None) -> None:
+def edit_reference(
+    file: ifcopenshell.file, reference: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcClassificationReference
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_reference(file, reference=None, attributes=None) -> None:
     :param reference: The IfcClassificationReference entity you want to edit
     :type reference: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/classification/remove_classification.py

@@ -20,7 +20,7 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def remove_classification(file: ifcopenshell.entity_instance, classification: ifcopenshell.entity_instance) -> None:
+def remove_classification(file: ifcopenshell.file, classification: ifcopenshell.entity_instance) -> None:
     """Removes an IfcClassification from the project and all references
 
     The classification and all of its relationships, children references,
@@ -58,15 +58,20 @@ class Usecase:
                 self.file.remove(rel)
                 if history:
                     ifcopenshell.util.element.remove_deep2(self.file, history)
-        for rel in self.file.by_type("IfcExternalReferenceRelationship"):
-            if not rel.RelatingReference:
-                self.file.remove(rel)
 
-    def get_references(self, classification):
+        if self.file.schema != "IFC2X3":
+            for rel in self.file.by_type("IfcExternalReferenceRelationship"):
+                if not rel.RelatingReference:
+                    self.file.remove(rel)
+
+    def get_references(self, classification: ifcopenshell.entity_instance) -> list[ifcopenshell.entity_instance]:
         results = []
-        if not classification.HasReferences:
-            return results
-        for reference in classification.HasReferences:
-            results.append(reference)
-            results.extend(self.get_references(reference))
+        if self.file.schema == "IFC2X3":
+            for reference in self.file.by_type("IfcClassificationReference"):
+                if reference.ReferencedSource == classification:
+                    results.append(reference)
+        else:
+            for reference in classification.HasReferences:
+                results.append(reference)
+                results.extend(self.get_references(reference))
         return results

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

@@ -16,6 +16,13 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Constraints are an advanced feature allowing you to specify parametric
+limits on properties
+
+Warning: usage of constraints are mostly untested in real life applications.
+"""
+
+from .. import wrap_usecases
 from .add_metric import add_metric
 from .add_metric_reference import add_metric_reference
 from .add_objective import add_objective
@@ -25,3 +32,5 @@ from .edit_objective import edit_objective
 from .remove_constraint import remove_constraint
 from .remove_metric import remove_metric
 from .unassign_constraint import unassign_constraint
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric.py

@@ -19,7 +19,7 @@
 import ifcopenshell
 
 
-def add_metric(file, objective=None) -> None:
+def add_metric(file: ifcopenshell.file, objective: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """Add a new metric benchmark
 
     Qualitative constraints may have a series of quantitative benchmarks
@@ -50,7 +50,7 @@ def add_metric(file, objective=None) -> None:
             "Name": "Unnamed",
             "ConstraintGrade": "NOTDEFINED",
             "Benchmark": "EQUALTO",
-        }
+        },
     )
     if settings["objective"]:
         benchmark_values = list(settings["objective"].BenchmarkValues or [])

src/ifcopenshell-python/ifcopenshell/api/constraint/add_metric_reference.py

@@ -19,16 +19,18 @@
 import ifcopenshell
 
 
-def add_metric_reference(file, metric=None, reference_path=None) -> None:
+def add_metric_reference(
+    file: ifcopenshell.file, metric: ifcopenshell.entity_instance, reference_path: str
+) -> list[ifcopenshell.entity_instance]:
     """
     Adds a chain of references to a metric. The reference path is a string of the form "attribute.attribute.attribute"
     Used to reference a value of an attribute of an instance through a metric objective entity.
     """
     settings = {"metric": metric, "reference_path": reference_path}
 
+    references_created = []
     if settings["reference_path"]:
         attributes = settings["reference_path"].split(".")
-        references_created = []
         for i in range(len(attributes)):
             if i == 0:
                 reference = file.create_entity("IfcReference")
@@ -40,4 +42,4 @@ def add_metric_reference(file, metric=None, reference_path=None) -> None:
                 reference.AttributeIdentifier = attributes[i]
                 references_created[i - 1].InnerReference = reference
                 references_created.append(reference)
-        return references_created
+    return references_created

src/ifcopenshell-python/ifcopenshell/api/constraint/add_objective.py

@@ -19,7 +19,7 @@
 import ifcopenshell
 
 
-def add_objective(file) -> None:
+def add_objective(file: ifcopenshell.file) -> ifcopenshell.entity_instance:
     """Add a new objective constraint
 
     Parametric constraints may be defined by the user. The constraint is defined

src/ifcopenshell-python/ifcopenshell/api/constraint/assign_constraint.py

@@ -18,6 +18,7 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
 from typing import Union
 
 

src/ifcopenshell-python/ifcopenshell/api/constraint/edit_metric.py

@@ -15,9 +15,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/>.
+import ifcopenshell
+from typing import Any
 
 
-def edit_metric(file, metric=None, attributes=None) -> None:
+def edit_metric(file: ifcopenshell.file, metric: ifcopenshell.entity_instance, attributes: dict[str, Any]) -> None:
     """Edit the attributes of a metric
 
     For more information about the attributes and data types of an
@@ -26,7 +28,7 @@ def edit_metric(file, metric=None, attributes=None) -> None:
     :param metric: The IfcMetric you want to edit.
     :type metric: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/constraint/edit_objective.py

@@ -15,9 +15,13 @@
 #
 # 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
+from typing import Any
 
 
-def edit_objective(file, objective=None, attributes=None) -> None:
+def edit_objective(
+    file: ifcopenshell.file, objective: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edit the attributes of a objective
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_objective(file, objective=None, attributes=None) -> None:
     :param objective: The IfcObjective you want to edit.
     :type objective: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/constraint/remove_constraint.py

@@ -20,7 +20,7 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def remove_constraint(file, constraint=None) -> None:
+def remove_constraint(file: ifcopenshell.file, constraint: ifcopenshell.entity_instance) -> None:
     """Remove a constraint (typically an objective)
 
     Removes a constraint definition and all of its associations to any

src/ifcopenshell-python/ifcopenshell/api/constraint/remove_metric.py

@@ -15,9 +15,10 @@
 #
 # 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
 
 
-def remove_metric(file, metric=None) -> None:
+def remove_metric(file: ifcopenshell.file, metric: ifcopenshell.entity_instance) -> None:
     """Remove a metric benchmark
 
     Removes a metric benchmark and all of its associations to any products

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

@@ -16,6 +16,18 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Contexts allow you to classify when geometry should be used in different
+purposes
+
+For example, a door may have many geometries assigned to it: a 3D body
+geometry, a clearance zone for disabled access and egress, and a 2D top down
+plan view representation annotating swing extents. Each geometry is assigned to
+a context to distinguish its purpose and level of detail.
+"""
+
+from .. import wrap_usecases
 from .add_context import add_context
 from .edit_context import edit_context
 from .remove_context import remove_context
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/context/remove_context.py

@@ -17,9 +17,11 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.api
+import ifcopenshell.util.element
 
 
-def remove_context(file: ifcopenshell.entity_instance, context: ifcopenshell.entity_instance) -> None:
+def remove_context(file: ifcopenshell.file, context: ifcopenshell.entity_instance) -> None:
     """Removes an IfcGeometricRepresentationContext
 
     Any representation geometry that is assigned to the context is also

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

@@ -16,5 +16,14 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Processes and costs may be controlled by other entities which indicate
+constraints that determine how they can change
+
+This is an advanced feature mostly used in 4D/5D
+"""
+
+from .. import wrap_usecases
 from .assign_control import assign_control
 from .unassign_control import unassign_control
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/control/assign_control.py

@@ -18,9 +18,15 @@
 
 import ifcopenshell
 import ifcopenshell.api
+import ifcopenshell.guid
+from typing import Union
 
 
-def assign_control(file, relating_control=None, related_object=None) -> None:
+def assign_control(
+    file: ifcopenshell.file,
+    relating_control: ifcopenshell.entity_instance,
+    related_object: ifcopenshell.entity_instance,
+) -> Union[ifcopenshell.entity_instance, None]:
     """Assigns a planning control or constraint to an object
 
     IFC can describe concepts that control other objects. For example, a

src/ifcopenshell-python/ifcopenshell/api/control/unassign_control.py

@@ -19,9 +19,14 @@
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
+from typing import Union
 
 
-def unassign_control(file, relating_control=None, related_object=None) -> None:
+def unassign_control(
+    file: ifcopenshell.file,
+    relating_control: ifcopenshell.entity_instance,
+    related_object: ifcopenshell.entity_instance,
+) -> Union[ifcopenshell.entity_instance, None]:
     """Unassigns a planning control or constraint to an object
 
     :param relating_control: The IfcControl entity that is creating the

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

@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Manage cost schedules, cost items, cost estimation and parametric quantity
+take-off
+
+IFC supports storing cost schedules and detailed cost breakdown structures,
+including formulas, subtotals, and parametric links to model element
+quantities.
+"""
+
+from .. import wrap_usecases
 from .add_cost_item import add_cost_item
 from .add_cost_item_quantity import add_cost_item_quantity
 from .add_cost_schedule import add_cost_schedule
@@ -35,3 +44,5 @@ from .remove_cost_item_quantity import remove_cost_item_quantity
 from .remove_cost_schedule import remove_cost_schedule
 from .remove_cost_value import remove_cost_value
 from .unassign_cost_item_quantity import unassign_cost_item_quantity
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_item.py

@@ -17,22 +17,30 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api
+import ifcopenshell.guid
+from typing import Optional
 
 
-def add_cost_item(file, cost_schedule=None, cost_item=None) -> None:
+def add_cost_item(
+    file: ifcopenshell.file,
+    cost_schedule: Optional[ifcopenshell.entity_instance] = None,
+    cost_item: Optional[ifcopenshell.entity_instance] = None,
+) -> ifcopenshell.entity_instance:
     """Add a new cost item
 
     A cost item represents a single line item in a cost schedule. Cost items
     may then be broken down into cost subitems.
 
+    Either `cost_schedule` or `cost_item` must be provided.
+
     :param cost_schedule: If the cost item is to be added as a root or top
         level cost item to a cost schedule, the IfcCostSchedule may be
         specified. This is mutually exlclusive to the cost_item parameter.
-    :type cost_schedule: ifcopenshell.entity_instance
+    :type cost_schedule: ifcopenshell.entity_instance, optional.
     :param cost_item: If the cost item is to be added as a subitem to an
         existing cost item, the parent IfcCostItem may be specified. This is
         mutually exclusive to the cost_schedule parameter.
-    :type cost_item: ifcopenshell.entity_instance
+    :type cost_item: ifcopenshell.entity_instance, optional
     :return: The newly created IfcCostItem
     :rtype: ifcopenshell.entity_instance
 
@@ -61,7 +69,7 @@ def add_cost_item(file, cost_schedule=None, cost_item=None) -> None:
                 "OwnerHistory": ifcopenshell.api.run("owner.create_owner_history", file),
                 "RelatedObjects": [cost_item],
                 "RelatingControl": settings["cost_schedule"],
-            }
+            },
         )
     elif settings["cost_item"]:
         ifcopenshell.api.run(

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_item_quantity.py

@@ -19,7 +19,9 @@
 import ifcopenshell.api
 
 
-def add_cost_item_quantity(file, cost_item=None, ifc_class="IfcQuantityCount") -> None:
+def add_cost_item_quantity(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, ifc_class: str = "IfcQuantityCount"
+) -> ifcopenshell.entity_instance:
     """Adds a new quantity associated with a cost item
 
     Cost items calculate their subtotal by multiplying the sum of the cost

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_schedule.py

@@ -19,9 +19,10 @@
 import ifcopenshell.api
 import ifcopenshell.util.date
 from datetime import datetime
+from typing import Optional
 
 
-def add_cost_schedule(file, name=None, predefined_type="NOTDEFINED") -> None:
+def add_cost_schedule(file: ifcopenshell.file, name: Optional[str] = None, predefined_type="NOTDEFINED") -> None:
     """Add a new cost schedule
 
     A cost schedule is a group of cost items which typically represent a
@@ -61,5 +62,17 @@ def add_cost_schedule(file, name=None, predefined_type="NOTDEFINED") -> None:
         predefined_type=settings["predefined_type"],
         name=settings["name"],
     )
-    cost_schedule.UpdateDate = ifcopenshell.util.date.datetime2ifc(datetime.now(), "IfcDateTime")
+    if file.schema == "IFC2X3":
+        cost_schedule.UpdateDate = createIfcDateAndTime(file, datetime.now())
+    else:
+        cost_schedule.UpdateDate = ifcopenshell.util.date.datetime2ifc(datetime.now(), "IfcDateTime")
     return cost_schedule
+
+
+def createIfcDateAndTime(file: ifcopenshell.file, dt: datetime):
+    ifc_dt = file.create_entity("IfcDateAndTime")
+    ifc_dt.DateComponent = file.create_entity(
+        "IfcCalendarDate", **ifcopenshell.util.date.datetime2ifc(dt, "IfcCalendarDate")
+    )
+    ifc_dt.TimeComponent = file.create_entity("IfcLocalTime", **ifcopenshell.util.date.datetime2ifc(dt, "IfcLocalTime"))
+    return ifc_dt

src/ifcopenshell-python/ifcopenshell/api/cost/add_cost_value.py

@@ -15,9 +15,10 @@
 #
 # 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
 
 
-def add_cost_value(file, parent=None) -> None:
+def add_cost_value(file: ifcopenshell.file, parent: ifcopenshell.entity_instance) -> ifcopenshell.entity_instance:
     """Adds a new value or subvalue to a cost item
 
     A cost item's subtotal can be specified in two ways.

src/ifcopenshell-python/ifcopenshell/api/cost/assign_cost_item_quantity.py

@@ -17,9 +17,15 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.api
+from typing import Optional
 
 
-def assign_cost_item_quantity(file, cost_item=None, products=None, prop_name="") -> None:
+def assign_cost_item_quantity(
+    file: ifcopenshell.file,
+    cost_item: ifcopenshell.entity_instance,
+    products: list[ifcopenshell.entity_instance],
+    prop_name: Optional[str] = "",
+) -> None:
     """Adds a cost item quantity that is parametrically connected to a product
 
     A cost item may have its subtotal calculated by multiplying a unit value

src/ifcopenshell-python/ifcopenshell/api/cost/assign_cost_value.py

@@ -19,7 +19,9 @@
 import ifcopenshell.api
 
 
-def assign_cost_value(file, cost_item=None, cost_rate=None) -> None:
+def assign_cost_value(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, cost_rate: ifcopenshell.entity_instance
+) -> None:
     """Assigns a cost value to a cost item from a schedule of rates
 
     Instead of assigning cost values from scratch for each cost item in a

src/ifcopenshell-python/ifcopenshell/api/cost/calculate_cost_item_resource_value.py

@@ -21,7 +21,7 @@ import ifcopenshell.util.date
 import ifcopenshell.util.resource
 
 
-def calculate_cost_item_resource_value(file, cost_item=None) -> None:
+def calculate_cost_item_resource_value(file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance) -> None:
     """Calculates the total cost of all resources associated with a cost item
 
     A cost item may have construction resources (e.g. equipment, material,

src/ifcopenshell-python/ifcopenshell/api/cost/copy_cost_item.py

@@ -19,9 +19,14 @@
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
+from typing import Union
 
 
-def copy_cost_item(file, cost_item=None) -> None:
+def copy_cost_item(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance
+) -> Union[ifcopenshell.entity_instance, list[ifcopenshell.entity_instance]]:
+    # TODO: currently it never returns list of duplicated cost items
+    # though it is stated in the docs
     """Copies all cost items and related relationships
 
     The following relationships are also duplicated:
@@ -33,7 +38,7 @@ def copy_cost_item(file, cost_item=None) -> None:
     :param cost_item: The cost item to be duplicated
     :type cost_item: ifcopenshell.entity_instance
     :return: The duplicated cost item or the list of duplicated cost items if the latter has children
-    :rtype: ifcopenshell.entity_instance or list of ifcopenshell.entity_instance
+    :rtype: ifcopenshell.entity_instance or list[ifcopenshell.entity_instance]
 
     Example:
     .. code:: python
@@ -55,7 +60,7 @@ def copy_cost_item(file, cost_item=None) -> None:
 class Usecase:
     def execute(self):
         self.new_cost_items = []
-        self.duplicate_cost_item(self.settings["cost_item"])
+        return self.duplicate_cost_item(self.settings["cost_item"])
 
     def duplicate_cost_item(self, cost_item):
         new_cost_item = ifcopenshell.util.element.copy_deep(self.file, cost_item)

src/ifcopenshell-python/ifcopenshell/api/cost/copy_cost_item_values.py

@@ -20,7 +20,9 @@ import ifcopenshell.util.element
 import ifcopenshell.api
 
 
-def copy_cost_item_values(file, source=None, destination=None) -> None:
+def copy_cost_item_values(
+    file: ifcopenshell.file, source: ifcopenshell.entity_instance, destination: ifcopenshell.entity_instance
+) -> None:
     """Copies all cost values from one cost item to another
 
     Any previously existing values will be removed. The entire value is

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_item.py

@@ -15,9 +15,13 @@
 #
 # 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
+from typing import Any
 
 
-def edit_cost_item(file, cost_item=None, attributes=None) -> None:
+def edit_cost_item(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcCostItem
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_cost_item(file, cost_item=None, attributes=None) -> None:
     :param cost_item: The IfcCostItem entity you want to edit
     :type cost_item: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_item_quantity.py

@@ -15,9 +15,13 @@
 #
 # 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
+from typing import Any
 
 
-def edit_cost_item_quantity(file, physical_quantity=None, attributes=None) -> None:
+def edit_cost_item_quantity(
+    file: ifcopenshell.file, physical_quantity: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcPhysicalQuantity
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_cost_item_quantity(file, physical_quantity=None, attributes=None) -> No
     :param physical_quantity: The IfcPhysicalQuantity entity you want to edit
     :type physical_quantity: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_schedule.py

@@ -15,9 +15,13 @@
 #
 # 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
+from typing import Any
 
 
-def edit_cost_schedule(file, cost_schedule=None, attributes=None) -> None:
+def edit_cost_schedule(
+    file: ifcopenshell.file, cost_schedule: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcCostSchedule
 
     For more information about the attributes and data types of an
@@ -26,7 +30,7 @@ def edit_cost_schedule(file, cost_schedule=None, attributes=None) -> None:
     :param cost_schedule: The IfcCostSchedule entity you want to edit
     :type cost_schedule: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_value.py

@@ -19,9 +19,12 @@
 import ifcopenshell
 import ifcopenshell.util.unit
 import ifcopenshell.util.element
+from typing import Any
 
 
-def edit_cost_value(file, cost_value=None, attributes=None) -> None:
+def edit_cost_value(
+    file: ifcopenshell.file, cost_value: ifcopenshell.entity_instance, attributes: dict[str, Any]
+) -> None:
     """Edits the attributes of an IfcCostValue
 
     For more information about the attributes and data types of an
@@ -30,7 +33,7 @@ def edit_cost_value(file, cost_value=None, attributes=None) -> None:
     :param cost_value: The IfcCostValue entity you want to edit
     :type cost_value: ifcopenshell.entity_instance
     :param attributes: a dictionary of attribute names and values.
-    :type attributes: dict, optional
+    :type attributes: dict
     :return: None
     :rtype: None
 

src/ifcopenshell-python/ifcopenshell/api/cost/edit_cost_value_formula.py

@@ -22,7 +22,7 @@ import ifcopenshell.util.unit
 import ifcopenshell.util.element
 
 
-def edit_cost_value_formula(file, cost_value=None, formula=None) -> None:
+def edit_cost_value_formula(file: ifcopenshell.file, cost_value: ifcopenshell.entity_instance, formula: str) -> None:
     """Sets a cost value based on a formula, similar to formulas in spreadsheets
 
     Costs may be made up of many components (e.g. labour, material, waste

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_item.py

@@ -21,7 +21,7 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def remove_cost_item(file, cost_item=None) -> None:
+def remove_cost_item(file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance) -> None:
     """Removes a cost item
 
     All associated relationships with the cost item are also removed,

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_item_quantity.py

@@ -15,9 +15,12 @@
 #
 # 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
 
 
-def remove_cost_item_quantity(file, cost_item=None, physical_quantity=None) -> None:
+def remove_cost_item_quantity(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, physical_quantity: ifcopenshell.entity_instance
+) -> None:
     """Removes a quantity assigned to a cost item
 
     If the quantity is part of a product (e.g. wall), then the quantity will

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_schedule.py

@@ -21,7 +21,7 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def remove_cost_schedule(file, cost_schedule=None) -> None:
+def remove_cost_schedule(file: ifcopenshell.file, cost_schedule: ifcopenshell.entity_instance) -> None:
     """Removes a cost schedule
 
     All associated relationships with the cost schedule are also removed,

src/ifcopenshell-python/ifcopenshell/api/cost/remove_cost_value.py

@@ -15,9 +15,12 @@
 #
 # 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
 
 
-def remove_cost_value(file, parent=None, cost_value=None) -> None:
+def remove_cost_value(
+    file: ifcopenshell.file, parent: ifcopenshell.entity_instance, cost_value: ifcopenshell.entity_instance
+) -> None:
     """Removes a cost value
 
     The cost value may be assigned either to a cost item, a construction

src/ifcopenshell-python/ifcopenshell/api/cost/unassign_cost_item_quantity.py

@@ -19,7 +19,9 @@
 import ifcopenshell.api
 
 
-def unassign_cost_item_quantity(file, cost_item=None, products=None) -> None:
+def unassign_cost_item_quantity(
+    file: ifcopenshell.file, cost_item: ifcopenshell.entity_instance, products: list[ifcopenshell.entity_instance]
+) -> None:
     """Removes quantities of a cost item that are calculated on products
 
     A cost item may have quantities that are parametrically calculated on

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

@@ -16,6 +16,15 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+"""Reference external project documents and associate them to model elements
+
+Some project information (drawings, specifications, certificates, reports, etc)
+may be stored in external documents (locally or in a CDE). IFC lets you store a
+register of documents with metadata and associate them with elements (both
+physical and non-physical).
+"""
+
+from .. import wrap_usecases
 from .add_information import add_information
 from .add_reference import add_reference
 from .assign_document import assign_document
@@ -24,3 +33,5 @@ from .edit_reference import edit_reference
 from .remove_information import remove_information
 from .remove_reference import remove_reference
 from .unassign_document import unassign_document
+
+wrap_usecases(__path__, __name__)

src/ifcopenshell-python/ifcopenshell/api/document/add_information.py

@@ -17,9 +17,13 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell
+import ifcopenshell.guid
+from typing import Optional
 
 
-def add_information(file, parent=None) -> None:
+def add_information(
+    file: ifcopenshell.file, parent: Optional[ifcopenshell.entity_instance] = None
+) -> ifcopenshell.entity_instance:
     """Adds a new document information to the project
 
     An IFC document information is a document associated with the project.
@@ -52,11 +56,8 @@ def add_information(file, parent=None) -> None:
             attributes={"Identification": "A-GA-6100", "Name": "Overall Plan",
             "Location": "A-GA-6100 - Overall Plan.pdf"})
     """
-    settings = {"parent": parent}
-
     id_attribute = "DocumentId" if file.schema == "IFC2X3" else "Identification"
     information = file.create_entity("IfcDocumentInformation", **{id_attribute: "X", "Name": "Unnamed"})
-    parent = settings["parent"]
     if not parent and file.by_type("IfcProject"):
         parent = file.by_type("IfcProject")[0]
     if parent.is_a("IfcProject") or parent.is_a("IfcContext"):