typing

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

@@ -17,9 +17,14 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.util.unit
+from typing import Union
+
+COORD = Union[tuple[float, float], tuple[float, float, float]]
 
 
-def add_axis_representation(file, context=None, axis=None) -> None:
+def add_axis_representation(
+    file: ifcopenshell.file, context: ifcopenshell.entity_instance, axis: tuple[COORD, COORD]
+) -> ifcopenshell.entity_instance:
     """Adds a new axis representation
 
     Certain objects are typically "axis-based", such as walls, beams,

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

@@ -16,27 +16,51 @@
 # You should have received a copy of the GNU Lesser General Public License
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
+from __future__ import annotations
 import ifcopenshell.util.unit
 import numpy as np
+import numpy.typing as npt
+from typing import Optional, TYPE_CHECKING, Literal
+
+if TYPE_CHECKING:
+    import bpy.types
 
 
-def add_boolean(file, **usecase_settings) -> None:
+NPArrayOfFloats = npt.NDArray[np.float64]
+
+
+def add_boolean(
+    file: ifcopenshell.file,
+    representation: ifcopenshell.entity_instance,
+    # A matrix to define a clipping Ifchalfspacesolid.
+    # The XY plane is the clipping boundary and +Z is removed.
+    operator: str = "DIFFERENCE",
+    # IfcHalfSpaceSolid, Mesh
+    type: Literal["IfcHalfSpaceSolid", "Mesh"] = "IfcHalfSpaceSolid",
+    matrix: Optional[NPArrayOfFloats] = None,
+    # A Blender OBJ to define the voided OBJ for a "Mesh" type
+    blender_obj: Optional[bpy.types.Object] = None,
+    # A Blender OBJ to define the void OBJ for a "Mesh" type
+    blender_void: Optional[bpy.types.Object] = None,
+    should_force_faceted_brep: bool = False,
+    should_force_triangulation: bool = False,
+) -> list[ifcopenshell.entity_instance]:
+    """For `type` values:
+    - "IfcHalfSpaceSolid" - `matrix` is not optional.
+    - "Mesh" - `blender_obj` and `blender_void` are not optional
+    """
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {
-        "representation": None,
-        "operator": "DIFFERENCE",
-        # IfcHalfSpaceSolid, Mesh
-        "type": "IfcHalfSpaceSolid",
-        # The XY plane is the clipping boundary and +Z is removed.
-        "matrix": None,  # A matrix to define a clipping Ifchalfspacesolid.
-        "blender_obj": None,  # A Blender OBJ to define the voided OBJ for a "Mesh" type
-        "blender_void": None,  # A Blender OBJ to define the void OBJ for a "Mesh" type
-        "should_force_faceted_brep": False,
-        "should_force_triangulation": False,
+        "representation": representation,
+        "operator": operator,
+        "type": type,
+        "matrix": matrix,
+        "blender_obj": blender_obj,
+        "blender_void": blender_void,
+        "should_force_faceted_brep": should_force_faceted_brep,
+        "should_force_triangulation": should_force_triangulation,
     }
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
     return usecase.execute()
 
 

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

@@ -16,13 +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/>.
 
+from __future__ import annotations
+import collections.abc
 import ifcopenshell.util.unit
 from ifcopenshell.util.shape_builder import ShapeBuilder, V
 from ifcopenshell.api.geometry.add_window_representation import create_ifc_window
 from mathutils import Vector
 from math import cos, radians
-
-import collections
+from typing import Any, Optional, Literal, Union
+import dataclasses
 
 
 SUPPORTED_DOOR_TYPES = (
@@ -38,9 +40,14 @@ SUPPORTED_DOOR_TYPES = (
 )
 
 
+def mm(x: float) -> float:
+    """mm to meters shortcut for readability"""
+    return x / 1000
+
+
 def create_ifc_door_lining(
     builder: ShapeBuilder, size: Vector, thickness: list, position: Vector = V(0, 0, 0).freeze()
-):
+) -> ifcopenshell.entity_instance:
     """`thickness` of the profile is defined as list in the following order: `(SIDE, TOP)`
 
     `thickness` can be also defined just as 1 float value.
@@ -69,80 +76,212 @@ def create_ifc_door_lining(
     return door_lining
 
 
-def create_ifc_box(builder: ShapeBuilder, size: Vector, position: Vector = V(0, 0, 0).freeze()):
+def create_ifc_box(
+    builder: ShapeBuilder, size: Vector, position: Vector = V(0, 0, 0).freeze()
+) -> ifcopenshell.entity_instance:
     rect = builder.rectangle(size.xy)
     box = builder.extrude(rect, size.z, position=position, extrusion_vector=V(0, 0, 1))
     return box
 
 
-def add_door_representation(file, **usecase_settings) -> None:
-    """units in usecase_settings expected to be in ifc project units"""
+# we use dataclass as we need default values for arguments
+# it's okay to use slots since we don't need dynamic attributes
+@dataclasses.dataclass(slots=True)
+class DoorLiningProperties:
+    LiningDepth: Optional[float] = None
+    """Optional, defaults to 50mm."""
+
+    LiningThickness: Optional[float] = None
+    """Optional, defaults to 50mm."""
+
+    LiningOffset: Optional[float] = None
+    """Offset from the outer side of the wall (by Y-axis). Optional, defaults to 0.0."""
+
+    LiningToPanelOffsetX: Optional[float] = None
+    """Offset from the wall. Optional, defaults to 25mm."""
+
+    LiningToPanelOffsetY: Optional[float] = None
+    """Offset from the X-axis (unlike windows). Optional, defaults to 25mm."""
+
+    TransomThickness: Optional[float] = None
+    """Vertical distance between door and window panels. Optional, defaults to 0.0."""
+
+    TransomOffset: Optional[float] = None
+    """Distance from the bottom door opening
+    to the beginning of the transom
+    unlike windows TransomOffset which goes to the center of the transom.
+    Optional, defaults 1.525m."""
+
+    ShapeAspectStyle: None = None
+    """Optional. Deprecated argument."""
+
+    CasingDepth: Optional[float] = None
+    """Casing cover wall faces around the opening
+    on the left, right and upper sides
+    Casing should be either on both sides of the wall or no casing
+    If `LiningOffset` is present then therefore casing is not possible on outer wall
+    therefore there will be no casing on inner wall either. Optional, defaults to 5mm."""
+
+    CasingThickness: Optional[float] = None
+    """Casing thickness by Z-axis. Optional, defaults to 75mm."""
+
+    ThresholdDepth: Optional[float] = None
+    """Threshold covers the bottom side of the opening. Optional, defaults to 100mm."""
+
+    ThresholdThickness: Optional[float] = None
+    """Theshold thickness by Z-axis. Optional, defaults to 25mm."""
+
+    ThresholdOffset: Optional[float] = None
+    """Threshold offset by Y-axis. Optional, defaults to 0.0."""
+
+    def initialize_properties(self, unit_scale: float) -> None:
+        # in meters
+        # fmt: off
+        default_values: dict[str, float] = dict(
+            LiningDepth          = mm(50),
+            LiningThickness      = mm(50),
+            LiningOffset         = 0.0,
+            LiningToPanelOffsetX = mm(25),
+            LiningToPanelOffsetY = mm(25),
+            TransomThickness     = 0.0,
+            TransomOffset        = mm(1525),
+            CasingDepth          = mm(5),
+            CasingThickness      = mm(75),
+            ThresholdDepth       = mm(100),
+            ThresholdThickness   = mm(25),
+            ThresholdOffset      = 0.0,
+        )
+        # fmt: on
+
+        si_conversion = 1 / unit_scale
+        for attr, default_value in default_values.items():
+            if getattr(self, attr) is not None:
+                continue
+            setattr(self, attr, default_value * si_conversion)
+
+
+@dataclasses.dataclass(slots=True)
+class DoorPanelProperties:
+    PanelDepth: Optional[float] = None
+    """Frame thickness by Y axis. Optional, defaults to 35 mm."""
+
+    PanelWidth: float = 1.0
+    """Ratio to the clear door opening. Optional, defaults to 1.0."""
+
+    FrameDepth: Optional[float] = None
+    """Frame thickness by Y axis. Optional, defaults to 35 mm."""
+
+    FrameThickness: Optional[float] = None
+    """Frame thickness by X axis. Optional, defaults to 35 mm."""
+
+    PanelPosition: None = None
+    """Optional, value is never used"""
+
+    PanelOperation: None = None
+    """Optional, value is never used.
+    Defines the basic ways to describe how door panels operate."""
+
+    ShapeAspectStyle: None = None
+    """Optional. Deprecated argument."""
+
+    def initialize_properties(self, unit_scale: float) -> None:
+        # in meters
+        # fmt: off
+        default_values: dict[str, float] = dict(
+            PanelDepth     = mm(35),
+            FrameDepth     = mm(35),
+            FrameThickness = mm(35),
+        )
+        # fmt: on
+
+        si_conversion = 1 / unit_scale
+        for attr, default_value in default_values.items():
+            if getattr(self, attr) is not None:
+                continue
+            setattr(self, attr, default_value * si_conversion)
+
+
+def add_door_representation(
+    file: ifcopenshell.file,
+    *,  # keywords only as this API implementation is probably not final
+    context: ifcopenshell.entity_instance,
+    overall_height: Optional[float] = None,
+    overall_width: Optional[float] = None,
+    # door type
+    # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcDoorTypeOperationEnum.htm
+    operation_type: Literal[
+        "SINGLE_SWING_LEFT",
+        "SINGLE_SWING_RIGHT",
+        "DOUBLE_SWING_RIGHT",
+        "DOUBLE_SWING_LEFT",
+        "DOUBLE_DOOR_SINGLE_SWING",
+        "DOUBLE_DOOR_DOUBLE_SWING",
+        "SLIDING_TO_LEFT",
+        "SLIDING_TO_RIGHT",
+        "DOUBLE_DOOR_SLIDING",
+    ] = "SINGLE_SWING_LEFT",
+    lining_properties: Optional[Union[DoorLiningProperties, dict[str, Any]]] = None,
+    panel_properties: Optional[Union[DoorPanelProperties, dict[str, Any]]] = None,
+    unit_scale: Optional[float] = None,
+) -> ifcopenshell.entity_instance:
+    """units in usecase_settings expected to be in ifc project units
+
+    :param context: IfcGeometricRepresentationContext for the representation.
+    :type context: ifcopenshell.entity_instance
+    :param overall_height: Overall door height. Defaults to 2m.
+    :type overall_height: float, optional
+    :param overall_width: Overall door width. Defaults to 0.9m.
+    :type overall_width: float, optional
+    :param operation_type: Type of the door. Defaults to SINGLE_SWING_LEFT.
+    :type operation_type: str, optional
+    :param lining_properties: DoorLiningProperties or a dictionary to create one.
+        See DoorLiningProperties description for details.
+    :type lining_properties: Union[DoorLiningProperties, dict[str, Any]]]
+    :param panel_properties: DoorPanelProperties or a dictionary to create one.
+        See DoorPanelProperties description for details.
+    :type panel_properties: Union[DoorPanelProperties, dict[str, Any]]]
+    :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.
+    :type unit_scale: float, optional
+    :return: IfcShapeRepresentation for a door.
+    :rtype: ifcopenshell.entity_instance
+
+    """
     usecase = Usecase()
     usecase.file = file
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcDoor.htm
-    # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcDoorTypeOperationEnum.htm
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcDoorLiningProperties.htm
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcDoorPanelProperties.htm
-    usecase.settings = {"unit_scale": ifcopenshell.util.unit.calculate_unit_scale(usecase.file)}
-    usecase.settings.update(
+    # define unit_scale first as it's going to be used setting default arguments
+    unit_scale = ifcopenshell.util.unit.calculate_unit_scale(file) if unit_scale is None else unit_scale
+    settings: dict[str, Any] = {"unit_scale": unit_scale}
+
+    if lining_properties is None:
+        lining_properties = DoorLiningProperties()
+    elif not isinstance(lining_properties, DoorLiningProperties):
+        lining_properties = DoorLiningProperties(**lining_properties)
+    lining_properties.initialize_properties(unit_scale)
+    lining_properties = dataclasses.asdict(lining_properties)
+
+    if panel_properties is None:
+        panel_properties = DoorPanelProperties()
+    elif not isinstance(panel_properties, DoorPanelProperties):
+        panel_properties = DoorPanelProperties(**panel_properties)
+    panel_properties.initialize_properties(unit_scale)
+    panel_properties = dataclasses.asdict(panel_properties)
+
+    settings.update(
         {
-            "context": None,  # IfcGeometricRepresentationContext
-            "overall_height": usecase.convert_si_to_unit(2.0),
-            "overall_width": usecase.convert_si_to_unit(0.9),
-            # DOUBLE_DOOR_DOUBLE_SWING, DOUBLE_DOOR_FOLDING, DOUBLE_DOOR_LIFTING_VERTICAL,
-            # DOUBLE_DOOR_SINGLE_SWING, DOUBLE_DOOR_SINGLE_SWING_OPPOSITE_LEFT,
-            # DOUBLE_DOOR_SINGLE_SWING_OPPOSITE_RIGHT, DOUBLE_DOOR_SLIDING,
-            # DOUBLE_SWING_LEFT, DOUBLE_SWING_RIGHT, FOLDING_TO_LEFT,
-            # FOLDING_TO_RIGHT, LIFTING_HORIZONTAL, LIFTING_VERTICAL_LEFT,
-            # LIFTING_VERTICAL_RIGHT, REVOLVING, REVOLVING_VERTICAL,
-            # ROLLINGUP, SINGLE_SWING_LEFT, SINGLE_SWING_RIGHT, SLIDING_TO_LEFT,
-            # SLIDING_TO_RIGHT, SWING_FIXED_LEFT, SWING_FIXED_RIGHT
-            "operation_type": "SINGLE_SWING_LEFT",  # door type
-            "lining_properties": {
-                "LiningDepth": usecase.convert_si_to_unit(0.050),
-                "LiningThickness": usecase.convert_si_to_unit(0.050),
-                # offset from the outer side of the wall (by Y-axis)
-                "LiningOffset": usecase.convert_si_to_unit(0.0),
-                # offset from the wall
-                "LiningToPanelOffsetX": usecase.convert_si_to_unit(0.025),
-                # offset from the X-axis (unlike windows)
-                "LiningToPanelOffsetY": usecase.convert_si_to_unit(0.025),
-                # transom - vertical distance between door and window panels
-                "TransomThickness": usecase.convert_si_to_unit(0.000),
-                # TransomOffset - distance from the bottom door opening
-                # to the beginning of the transom
-                # unlike windows TransomOffset which goes to the center of the transom
-                "TransomOffset": usecase.convert_si_to_unit(1.525),
-                "ShapeAspectStyle": None,  # DEPRECATED
-                # Casing cover wall faces around the opening
-                # on the left, right and upper sides
-                # Casing should be either on both sides of the wall or no casing
-                # If `LiningOffset` is present then therefore casing is not possible on outer wall
-                # therefore there will be no casing on inner wall either
-                "CasingDepth": usecase.convert_si_to_unit(0.005),
-                "CasingThickness": usecase.convert_si_to_unit(0.075),  # by Z-axis
-                # Threshold covers the bottom side of the opening
-                "ThresholdDepth": usecase.convert_si_to_unit(0.1),
-                "ThresholdThickness": usecase.convert_si_to_unit(0.025),  # by Z-axis
-                # offset by Y-axis
-                "ThresholdOffset": usecase.convert_si_to_unit(0.000),
-            },
-            "panel_properties": {
-                "PanelDepth": usecase.convert_si_to_unit(0.035),  # by Y
-                "PanelWidth": 1.0,  # as ratio to the clear door opening
-                "FrameDepth": usecase.convert_si_to_unit(0.035),  # by Y
-                "FrameThickness": usecase.convert_si_to_unit(0.035),  # by X
-                # LEFT, MIDDLE, RIGHT, NOTDEFINED
-                "PanelPosition": ...,  # NEVER USED
-                # defines the basic ways to describe how door panels operate
-                # basically how it opens
-                "PanelOperation": None,  # NEVER USED
-                "ShapeAspectStyle": None,  # DEPRECATED
-            },
+            "context": context,
+            "overall_height": overall_height if overall_height is not None else usecase.convert_si_to_unit(2.0),
+            "overall_width": overall_width if overall_width is not None else usecase.convert_si_to_unit(0.9),
+            "operation_type": operation_type,
+            "lining_properties": lining_properties,
+            "panel_properties": panel_properties,
         }
     )
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
+    usecase.settings = settings
     return usecase.execute()
 
 

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

@@ -19,13 +19,17 @@
 import ifcopenshell.util.unit
 
 
-def add_footprint_representation(file, **usecase_settings) -> None:
+def add_footprint_representation(
+    file,
+    # IfcGeometricRepresentationContext
+    context: ifcopenshell.entity_instance,
+    # A list of IFC curves to include in the curve set
+    curves: list[ifcopenshell.entity_instance],
+) -> ifcopenshell.entity_instance:
     settings = {
-        "context": None,  # IfcGeometricRepresentationContext
-        "curves": [],  # A list of IFC curves to include in the curve set
+        "context": context,
+        "curves": curves,
     }
-    for key, value in usecase_settings.items():
-        settings[key] = value
 
     return file.createIfcShapeRepresentation(
         settings["context"],

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

@@ -17,26 +17,43 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.util.unit
+from typing import Optional
+
+COORD_3D = tuple[float, float, float]
 
 
-def add_mesh_representation(file: ifcopenshell.file, **usecase_settings) -> None:
+def add_mesh_representation(
+    file: ifcopenshell.file,
+    # IfcGeometricRepresentationContext
+    context: ifcopenshell.entity_instance,
+    # Vertices, edges, and faces are given in the form of: [item1, item2, item3, ...]
+    # A list of coordinates
+    # ... where itemN = [(0., 0., 0.), (1., 1., 1.), (x, y, z), ...]
+    vertices: list[COORD_3D],
+    # A list of edges, represented by vertex index pairs
+    # ... where itemN = [(0, 1), (1, 2), (v1, v2), ...]
+    edges: list[tuple[int, int]],
+    # A list of polygons, represented by vertex indices
+    # ... where itemN = [(0, 1, 2), (5, 4, 2, 3), (v1, v2, v3, ... vN), ...]
+    faces: list[list[int]],
+    # Optionally apply a vector offset to all coordinates
+    cooridnate_offset: Optional[COORD_3D] = None,
+    # A scale factor to apply for all vectors in case the unit is different
+    unit_scale: Optional[float] = None,
+    # Force using IfcFacetedBreps instead of IfcPolygonalFaceSets
+    force_faceted_brep: bool = False,
+) -> ifcopenshell.entity_instance:
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {
-        "context": None,  # IfcGeometricRepresentationContext
-        # Vertices, edges, and faces are given in the form of: [item1, item2, item3, ...]
-        # ... where itemN = [(0., 0., 0.), (1., 1., 1.), (x, y, z), ...]
-        "vertices": None,  # A list of coordinates
-        # ... where itemN = [(0, 1), (1, 2), (v1, v2), ...]
-        "edges": None,  # A list of edges, represented by vertex index pairs
-        # ... where itemN = [(0, 1, 2), (5, 4, 2, 3), (v1, v2, v3, ... vN), ...]
-        "faces": None,  # A list of polygons, represented by vertex indices
-        "coordinate_offset": None,  # Optionally apply a vector offset to all coordinates
-        "unit_scale": None,  # A scale factor to apply for all vectors in case the unit is different
-        "force_faceted_brep": False,  # Force using IfcFacetedBreps instead of IfcPolygonalFaceSets
+        "context": context,
+        "vertices": vertices,
+        "edges": edges,
+        "faces": faces,
+        "coordinate_offset": cooridnate_offset,
+        "unit_scale": unit_scale,
+        "force_faceted_brep": force_faceted_brep,
     }
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
     return usecase.execute()
 
 

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

@@ -19,23 +19,35 @@
 import ifcopenshell.geom
 import ifcopenshell.util.unit
 from ifcopenshell.util.data import Clipping
+from typing import Any, Union, Optional, Literal
+
+VECTOR_3D = tuple[float, float, float]
 
 
-def add_profile_representation(file, **usecase_settings) -> None:
+def add_profile_representation(
+    file: ifcopenshell.file,
+    # IfcGeometricRepresentationContext
+    context: ifcopenshell.entity_instance,
+    profile: ifcopenshell.entity_instance,
+    # in meters
+    depth: float = 1.0,
+    cardinal_point: Literal[0, 1, 2, 3, 4, 5, 6, 7, 8, 9] = 5,
+    # A list of planes that define clipping half space solids
+    # Planes are defined either by Clipping objects
+    # or by dictionaries of arguments for `Clipping.parse`
+    clippings: Optional[list[Union[Clipping, dict[str, Any]]]] = None,
+    placement_zx_axes: tuple[Union[VECTOR_3D, None], Union[VECTOR_3D, None]] = (None, None),
+) -> None:
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {
-        "context": None,  # IfcGeometricRepresentationContext
-        "profile": None,
-        "depth": 1.0,
-        "cardinal_point": 5,
-        # Planes are defined either by Clipping objects
-        # or by dictionaries of arguments for `Clipping.parse`
-        "clippings": [],  # A list of planes that define clipping half space solids
-        "placement_zx_axes": (None, None),
+        "context": context,
+        "profile": profile,
+        "depth": depth,
+        "cardinal_point": cardinal_point,
+        "clippings": clippings if clippings is not None else [],
+        "placement_zx_axes": placement_zx_axes,
     }
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
     return usecase.execute()
 
 

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

@@ -22,46 +22,100 @@ from itertools import chain
 from mathutils import Vector, Matrix
 import collections
 import mathutils
-from pprint import pprint
 from math import pi, cos, sin, tan, radians
+from typing import Literal, Optional, Any
 
 
-def mm(x):
+def mm(x: float) -> float:
     """mm to meters shortcut for readability"""
     return x / 1000
 
 
-def add_railing_representation(file, **usecase_settings) -> None:
+def add_railing_representation(
+    file: ifcopenshell.file,
+    *,  # keywords only as this API implementation is probably not final
+    # IfcGeometricRepresentationContext
+    context: ifcopenshell.entity_instance,
+    railing_type: Literal["WALL_MOUNTED_HANDRAIL"] = "WALL_MOUNTED_HANDRAIL",
+    railing_path: list[Vector],
+    use_manual_supports: bool = False,
+    support_spacing: Optional[float] = None,
+    railing_diameter: Optional[float] = None,
+    clear_width: Optional[float] = None,
+    terminal_type: Literal[
+        "180",
+        "TO_END_POST",
+        "TO_WALL",
+        "TO_FLOOR",
+        "TO_END_POST_AND_FLOOR",
+    ] = "180",
+    height: Optional[float] = None,
+    looped_path: bool = False,
+    unit_scale: Optional[float] = None,
+) -> ifcopenshell.entity_instance:
     """
-    units in usecase_settings expected to be in ifc project units
+    Units are expected to be in IFC project units.
 
-    `railing_path` is a list of point coordinates for the railing path,
-    coordinates are expected to be at the top of the railing, not at the center
+    :param context: IfcGeometricRepresentationContext for the representation.
+    :type context: ifcopenshell.entity_instance
+    :param railing_type: Type of the railing. Defaults to "WALL_MOUNTED_HANDRAIL".
+    :type railing_type: Literal["WALL_MOUNTED_HANDRAIL"], optional
+    :param railing_path: A list of points coordinates for the railing path,
+        coordinates are expected to be at the top of the railing, not at the center.
+        If not provided, default path [(0, 0, 1), (1, 0, 1), (2, 0, 1)] (in meters) will be used
+    :type railing_path: list[Vector], optional.
+    :param use_manual_supports: If enabled, supports are added on every vertex on the edges of the railing path.
+        If disabled, supports are added automatically based on the support spacing. Default to False.
+    :type use_manual_supports: bool, optional
+    :param support_spacing: Distance between supports if automatic supports are used. Defaults to 1m.
+    :type support_spacing: float, optional
+    :param railing_diameter: Railing diameter. Defaults to 50mm.
+    :type railing_diameter: float, optional
+    :param clear_width: Clear width between the railing and the wall. Defaults to 40mm.
+    :type clear_width: float, optional
+    :param terminal_type: type of the cap. Defaults to "180".
+    :type terminal_type: Literal["180","TO_END_POST","TO_WALL","TO_FLOOR","TO_END_POST_AND_FLOOR"], optional
+    :param height: defaults to 1m
+    :type height: float, optional
+    :param looped_path: Whether to end the railing on the first point of `railing_path`. Defaults to False.
+    :type looped_path: bool, optional
+    :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.
+    :type unit_scale: float, optional
+    :return: IfcShapeRepresentation for a railing.
+    :rtype: ifcopenshell.entity_instance
 
-    `railing_path` is expected to be a list of Vector objects
     """
     usecase = Usecase()
     usecase.file = file
-    usecase.settings = {"unit_scale": ifcopenshell.util.unit.calculate_unit_scale(usecase.file)}
-    usecase.settings.update(
+    # define unit_scale first as it's going to be used setting default arguments
+    settings: dict[str, Any] = {
+        "unit_scale": ifcopenshell.util.unit.calculate_unit_scale(file) if unit_scale is None else unit_scale,
+    }
+    settings.update(
         {
-            "context": None,  # IfcGeometricRepresentationContext
-            "railing_type": "WALL_MOUNTED_HANDRAIL",
-            "railing_path": usecase.path_si_to_units([V(0, 0, 1), V(1, 0, 1), V(2, 0, 1)]),
-            "use_manual_supports": False,
-            "support_spacing": usecase.convert_si_to_unit(mm(1000)),
-            "railing_diameter": usecase.convert_si_to_unit(mm(50)),
-            "clear_width": usecase.convert_si_to_unit(mm(40)),
-            "terminal_type": "180",
-            "height": usecase.convert_si_to_unit(mm(1000)),
-            "looped_path": False,
+            "context": context,
+            "railing_type": railing_path,
+            "railing_path": (
+                railing_path
+                if railing_path is not None
+                else usecase.path_si_to_units([V(0, 0, 1), V(1, 0, 1), V(2, 0, 1)])
+            ),
+            "use_manual_supports": use_manual_supports,
+            "support_spacing": support_spacing if support_spacing is not None else usecase.convert_si_to_unit(mm(1000)),
+            "railing_diameter": (
+                railing_diameter if railing_diameter is not None else usecase.convert_si_to_unit(mm(50))
+            ),
+            "clear_width": clear_width if clear_width is not None else usecase.convert_si_to_unit(mm(40)),
+            "terminal_type": terminal_type,
+            "height": height if height is not None else usecase.convert_si_to_unit(mm(1000)),
+            "looped_path": looped_path,
         }
     )
+    usecase.settings = settings
 
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
-
-    if usecase.settings["railing_type"] != "WALL_MOUNTED_HANDRAIL":
+    if railing_type != "WALL_MOUNTED_HANDRAIL":
         raise Exception('Only "WALL_MOUNTED_HANDRAIL" railing_type is supported at the moment.')
     return usecase.execute()
 

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

@@ -16,11 +16,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/>.
 from __future__ import annotations
-import bpy
+import bpy.types
 import math
 import bmesh
 import ifcopenshell.util.unit
 from mathutils import Vector, Matrix
+from typing import Union, Optional, Literal
 
 
 Z_AXIS = Vector((0, 0, 1))
@@ -28,7 +29,44 @@ X_AXIS = Vector((1, 0, 0))
 EPSILON = 1e-6
 
 
-def add_representation(file: ifcopenshell.file, **usecase_settings) -> ifcopenshell.entity_instance:
+def add_representation(
+    file: ifcopenshell.file,
+    *,  # keywords only as this API implementation is probably not final
+    # IfcGeometricRepresentationContext
+    context: ifcopenshell.entity_instance,
+    # This is (currently) a Blender object, hence this depends on Blender now
+    blender_object: bpy.types.Object,
+    # This is (currently) a Blender data object, hence this depends on Blender now
+    geometry: Union[bpy.types.Mesh, bpy.types.Curve],
+    # Optionally apply a vector offset to all coordinates
+    coordinate_offset: Optional[Vector] = None,
+    # How many representation items to create
+    total_items: int = 1,
+    # A scale factor to apply for all vectors in case the unit is different
+    unit_scale: Optional[float] = None,
+    # If we should force faceted breps for meshes
+    should_force_faceted_brep: bool = False,
+    # If we should force triangulation for meshes
+    should_force_triangulation: bool = False,
+    # If UV coordinates should also be generated
+    should_generate_uvs: bool = False,
+    # Whether to cast a mesh into a particular class
+    ifc_representation_class: Optional[
+        Literal[
+            "IfcExtrudedAreaSolid/IfcRectangleProfileDef",
+            "IfcExtrudedAreaSolid/IfcCircleProfileDef",
+            "IfcExtrudedAreaSolid/IfcArbitraryClosedProfileDef",
+            "IfcExtrudedAreaSolid/IfcArbitraryProfileDefWithVoids",
+            "IfcExtrudedAreaSolid/IfcMaterialProfileSetUsage",
+            "IfcGeometricCurveSet/IfcTextLiteral",
+            "IfcTextLiteral",
+        ]
+    ] = None,
+    # The material profile set if the extrusion requires it
+    profile_set_usage: Optional[ifcopenshell.entity_instance] = None,
+    # The text literal if the representation requires it
+    text_literal: Optional[ifcopenshell.entity_instance] = None,
+) -> ifcopenshell.entity_instance:
     # lazy import Helper to avoid circular import
     if "Helper" not in globals():
         from blenderbim.bim.module.geometry.helper import Helper
@@ -37,30 +75,20 @@ def add_representation(file: ifcopenshell.file, **usecase_settings) -> ifcopensh
     # TODO: This usecase currently depends on Blender's data model
     usecase.file = file
     usecase.settings = {
-        "context": None,  # IfcGeometricRepresentationContext
-        "blender_object": None,  # This is (currently) a Blender object, hence this depends on Blender now
-        "geometry": None,  # This is (currently) a Blender data object, hence this depends on Blender now
-        "coordinate_offset": None,  # Optionally apply a vector offset to all coordinates
-        "total_items": 1,  # How many representation items to create
-        "unit_scale": None,  # A scale factor to apply for all vectors in case the unit is different
-        "should_force_faceted_brep": False,  # If we should force faceted breps for meshes
-        "should_force_triangulation": False,  # If we should force triangulation for meshes
-        "should_generate_uvs": False,  # If UV coordinates should also be generated
-        #  Possible IFC representation classes:
-        #  IfcExtrudedAreaSolid/IfcRectangleProfileDef
-        #  IfcExtrudedAreaSolid/IfcCircleProfileDef
-        #  IfcExtrudedAreaSolid/IfcArbitraryClosedProfileDef
-        #  IfcExtrudedAreaSolid/IfcArbitraryProfileDefWithVoids
-        #  IfcExtrudedAreaSolid/IfcMaterialProfileSetUsage
-        #  IfcGeometricCurveSet/IfcTextLiteral
-        #  IfcTextLiteral
-        "ifc_representation_class": None,  # Whether to cast a mesh into a particular class
-        "profile_set_usage": None,  # The material profile set if the extrusion requires it
-        "text_literal": None,  # The text literal if the representation requires it
+        "context": context,
+        "blender_object": blender_object,
+        "geometry": geometry,
+        "coordinate_offset": coordinate_offset,
+        "total_items": total_items,
+        "unit_scale": unit_scale,
+        "should_force_faceted_brep": should_force_faceted_brep,
+        "should_force_triangulation": should_force_triangulation,
+        "should_generate_uvs": should_generate_uvs,
+        "ifc_representation_class": ifc_representation_class,
+        "profile_set_usage": profile_set_usage,
+        "text_literal": text_literal,
     }
     usecase.ifc_vertices = []
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
     return usecase.execute()
 
 

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

@@ -17,22 +17,32 @@
 # along with IfcOpenShell.  If not, see <http://www.gnu.org/licenses/>.
 
 import ifcopenshell.util.unit
+from ifcopenshell.util.data import Clipping
 from math import sin, cos
+from typing import Any, Optional, Union
 
 
-def add_slab_representation(file, **usecase_settings) -> None:
+def add_slab_representation(
+    file,
+    # IfcGeometricRepresentationContext
+    context: ifcopenshell.entity_instance,
+    # in meters
+    depth: float = 0.2,
+    # in radians
+    x_angle: float = 0.0,
+    # A list of planes that define clipping half space solids
+    # Planes are defined either by Clipping objects
+    # or by dictionaries of arguments for `Clipping.parse`
+    clippings: Optional[list[Union[Clipping, dict[str, Any]]]] = None,
+) -> ifcopenshell.entity_instance:
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {
-        "context": None,  # IfcGeometricRepresentationContext
-        "depth": 0.2,
-        "x_angle": 0,  # Radians
-        # Planes are defined either by Clipping objects
-        # or by dictionaries of arguments for `Clipping.parse`
-        "clippings": [],  # A list of planes that define clipping half space solids
+        "context": context,
+        "depth": depth,
+        "x_angle": x_angle,
+        "clippings": clippings if clippings is not None else [],
     }
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
     return usecase.execute()
 
 

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

@@ -18,27 +18,39 @@
 
 import ifcopenshell.util.unit
 from math import sin, cos
+from typing import Optional, Union, Any
 from ifcopenshell.util.data import Clipping
 
 
-def add_wall_representation(file, **usecase_settings) -> None:
+def add_wall_representation(
+    file: ifcopenshell.file,
+    context: ifcopenshell.entity_instance,  # IfcGeometricRepresentationContext
+    # all lengths are in meters
+    length: float = 1.0,
+    height: float = 3.0,
+    offset: float = 0.0,
+    thickness: float = 0.2,
+    # Sloped walls along the wall's X axis, provided in radians
+    x_angle: float = 0.0,
+    # A list of planes that define clipping half space solids
+    # Planes are defined either by Clipping objects
+    # or by dictionaries of arguments for `Clipping.parse`
+    clippings: Optional[list[Union[Clipping, dict[str, Any]]]] = None,
+    # Any existing IfcBooleanResults
+    booleans: Optional[list[ifcopenshell.entity_instance]] = None,
+) -> ifcopenshell.entity_instance:
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {
-        "context": None,  # IfcGeometricRepresentationContext
-        "length": 1.0,
-        "height": 3.0,
-        "offset": 0.0,
-        "thickness": 0.2,
-        # Sloped walls along the wall's X axis, provided in radians
-        "x_angle": 0,
-        # Planes are defined either by Clipping objects
-        # or by dictionaries of arguments for `Clipping.parse`
-        "clippings": [],  # A list of planes that define clipping half space solids
-        "booleans": [],  # Any existing IfcBooleanResults
+        "context": context,
+        "length": length,
+        "height": height,
+        "offset": offset,
+        "thickness": thickness,
+        "x_angle": x_angle,
+        "clippings": clippings if clippings is not None else [],
+        "booleans": booleans if booleans is not None else [],
     }
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
     return usecase.execute()
 
 

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

@@ -16,11 +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/>.
 
+from __future__ import annotations
+import collections.abc
 import ifcopenshell.util.unit
 from ifcopenshell.util.shape_builder import ShapeBuilder, V
 from itertools import chain
 from mathutils import Vector
-import collections
+import dataclasses
+from typing import Any, Optional, Literal, Union
 
 
 # SCHEMAS describe panels setup
@@ -42,6 +45,11 @@ DEFAULT_PANEL_SCHEMAS = {
 }
 
 
+def mm(x: float) -> float:
+    """mm to meters shortcut for readability"""
+    return x / 1000
+
+
 def create_ifc_window_frame_simple(
     builder: ShapeBuilder, size: Vector, thickness: list, position: Vector = V(0, 0, 0).freeze()
 ):
@@ -210,71 +218,209 @@ def create_ifc_window(
     return output_items
 
 
-def add_window_representation(file, **usecase_settings) -> None:
-    """units in usecase_settings expected to be in ifc project units"""
+# we use dataclass as we need default values for arguments
+# it's okay to use slots since we don't need dynamic attributes
+@dataclasses.dataclass(slots=True)
+class WindowLiningProperties:
+    LiningDepth: Optional[float] = None
+    """Optional, defaults to 50mm."""
+
+    LiningThickness: Optional[float] = None
+    """Optional, defaults to 50mm."""
+
+    LiningOffset: Optional[float] = None
+    """Offset to the wall. Optional, defaults to 50mm."""
+
+    LiningToPanelOffsetX: Optional[float] = None
+    """Offset from the wall. Optional, defaults to 25mm."""
+
+    # that way it allows you to define overall_depth constant between all panels
+    # and still have panels with different size:
+    # overall_depth = lining_depth + offset_y
+    # full offset from X axis = overall_depth - frame_depth.
+    LiningToPanelOffsetY: Optional[float] = None
+    """Offset from the lining. Optional, defaults to 25mm."""
+
+    MullionThickness: Optional[float] = None
+    """Mullion thickness (horizontal distance between panels).
+
+    Applies to windows of types: DoublePanelVertical, TriplePanelBottom, TriplePanelTop,
+    TriplePanelLeft, TriplePanelRight.
+
+    Optional, defaults to 50mm."""
+
+    FirstMullionOffset: Optional[float] = None
+    """Distance from the first lining to the mullion center. Optional, defaults to 300mm."""
+
+    SecondMullionOffset: Optional[float] = None
+    """Distance from the first lining to the second mullion center. 
+
+    Applies to windows of type: TriplePanelVertical.
+
+    Optional, defaults to 450mm."""
+
+    TransomThickness: Optional[float] = None
+    """Transom thickness (vertical distance between panels), works similar way to mullions.
+
+    Applies to windows of types:DoublePanelHorizontal, TriplePanelBottom, TriplePanelTop,
+    TriplePanelLeft, TriplePanelRight.
+
+    Optional, defaults to 50mm."""
+
+    FirstTransomOffset: Optional[float] = None
+    """Optional, defaults to 300mm."""
+
+    SecondTransomOffset: Optional[float] = None
+    """
+    Applies to windows of type: TriplePanelHorizontal.
+    Optional, defaults to 600mm."""
+
+    ShapeAspectStyle: None = None
+    """Optional. Deprecated argument."""
+
+    def initialize_properties(self, unit_scale: float) -> None:
+        # in meters
+        # fmt: off
+        default_values: dict[str, float] = dict(
+            LiningDepth          = mm(50),
+            LiningThickness      = mm(50),
+            LiningOffset         = mm(50),
+            LiningToPanelOffsetX = mm(25),
+            LiningToPanelOffsetY = mm(25),
+            MullionThickness     = mm(50),
+            FirstMullionOffset   = mm(300),
+            SecondMullionOffset  = mm(450),
+            TransomThickness     = mm(50),
+            FirstTransomOffset   = mm(300),
+            SecondTransomOffset  = mm(600),
+        )
+        # fmt: on
+
+        si_conversion = 1 / unit_scale
+        for attr, default_value in default_values.items():
+            if getattr(self, attr) is not None:
+                continue
+            setattr(self, attr, default_value * si_conversion)
+
+
+@dataclasses.dataclass(slots=True)
+class WindowPanelProperties:
+    FrameDepth: Optional[float] = None
+    """Frame thickness by Y axis. Optional, defaults to 35 mm."""
+
+    FrameThickness: Optional[float] = None
+    """Frame thickness by X axis. Optional, defaults to 35 mm."""
+
+    PanelPosition: None = None
+    """Optional, value is never used"""
+
+    PanelOperation: None = None
+    """Optional, value is never used.
+    Defines the basic ways to describe how window panels operate."""
+
+    ShapeAspectStyle: None = None
+    """Optional. Deprecated argument."""
+
+    def initialize_properties(self, unit_scale: float) -> None:
+        # in meters
+        # fmt: off
+        default_values: dict[str, float] = dict(
+            FrameDepth     = mm(35),
+            FrameThickness = mm(35),
+        )
+        # fmt: on
+
+        si_conversion = 1 / unit_scale
+        for attr, default_value in default_values.items():
+            if getattr(self, attr) is not None:
+                continue
+            setattr(self, attr, default_value * si_conversion)
+
+
+def add_window_representation(
+    file: ifcopenshell.file,
+    *,  # keywords only as this API implementation is probably not final
+    context: ifcopenshell.entity_instance,
+    overall_height: Optional[float] = None,
+    overall_width: Optional[float] = None,
+    partition_type: Literal[
+        "SINGLE_PANEL",
+        "DOUBLE_PANEL_HORIZONTAL",
+        "DOUBLE_PANEL_VERTICAL",
+        "TRIPLE_PANEL_BOTTOM",
+        "TRIPLE_PANEL_HORIZONTAL",
+        "TRIPLE_PANEL_LEFT",
+        "TRIPLE_PANEL_RIGHT",
+        "TRIPLE_PANEL_TOP",
+        "TRIPLE_PANEL_VERTICAL",
+    ] = "SINGLE_PANEL",
+    lining_properties: Optional[Union[WindowLiningProperties, dict[str, Any]]] = None,
+    panel_properties: Optional[list[Union[WindowPanelProperties, dict[str, Any]]]] = None,
+    unit_scale: Optional[float] = None,
+) -> ifcopenshell.entity_instance:
+    """units in usecase_settings expected to be in ifc project units
+
+    :param context: IfcGeometricRepresentationContext for the representation.
+    :type context: ifcopenshell.entity_instance
+    :param overall_height: Overall window height. Defaults to 0.9m.
+    :type overall_height: float, optional
+    :param overall_width: Overall window width. Defaults to 0.6m.
+    :type overall_width: float, optional
+    :param partition_type: Type of the window. Defaults to SINGLE_PANEL.
+    :type partition_type: str, optional
+    :param lining_properties: WindowLiningProperties or a dictionary to create one.
+        See WindowLiningProperties description for details.
+    :type lining_properties: Union[WindowLiningProperties, dict[str, Any]]]
+    :param panel_properties: A list of WindowPanelProperties or dictionaries to create one.
+        See WindowPanelProperties description for details.
+    :type panel_properties: list[Union[WindowPanelProperties, dict[str, Any]]]]
+    :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.
+    :type unit_scale: float, optional
+    :return: IfcShapeRepresentation for a window.
+    :rtype: ifcopenshell.entity_instance
+
+    """
     usecase = Usecase()
     usecase.file = file
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWindow.htm
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWindowTypePartitioningEnum.htm
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWindowLiningProperties.htm
     # http://ifc43-docs.standards.buildingsmart.org/IFC/RELEASE/IFC4x3/HTML/lexical/IfcWindowPanelProperties.htm
-    usecase.settings = {"unit_scale": ifcopenshell.util.unit.calculate_unit_scale(usecase.file)}
-    usecase.settings.update(
+    # define unit_scale first as it's going to be used setting default arguments
+    unit_scale = ifcopenshell.util.unit.calculate_unit_scale(file) if unit_scale is None else unit_scale
+    settings: dict[str, Any] = {"unit_scale": unit_scale}
+
+    if lining_properties is None:
+        lining_properties = WindowLiningProperties()
+    elif not isinstance(lining_properties, WindowLiningProperties):
+        lining_properties = WindowLiningProperties(**lining_properties)
+    lining_properties.initialize_properties(unit_scale)
+    lining_properties = dataclasses.asdict(lining_properties)
+
+    if panel_properties is None:
+        panel_properties = [WindowPanelProperties()]
+
+    for i in range(len(panel_properties)):
+        properties = panel_properties[i]
+        if not isinstance(properties, WindowPanelProperties):
+            properties = WindowPanelProperties(**properties)
+        properties.initialize_properties(unit_scale)
+        panel_properties[i] = dataclasses.asdict(properties)
+
+    settings.update(
         {
-            "context": None,  # IfcGeometricRepresentationContext
-            # SINGLE_PANEL, DOUBLE_PANEL_HORIZONTAL, DOUBLE_PANEL_VERTICAL,
-            # TRIPLE_PANEL_BOTTOM, TRIPLE_PANEL_HORIZONTAL, TRIPLE_PANEL_LEFT,
-            # TRIPLE_PANEL_RIGHT, TRIPLE_PANEL_TOP, TRIPLE_PANEL_VERTICAL
-            "partition_type": "SINGLE_PANEL",
-            "overall_height": usecase.convert_si_to_unit(0.9),
-            "overall_width": usecase.convert_si_to_unit(0.6),
-            "lining_properties": {
-                "LiningDepth": usecase.convert_si_to_unit(0.050),
-                "LiningThickness": usecase.convert_si_to_unit(0.050),
-                "LiningOffset": usecase.convert_si_to_unit(0.050),  # offset to the wall
-                # offset from the wall
-                "LiningToPanelOffsetX": usecase.convert_si_to_unit(0.025),
-                # offset from the lining
-                # that way it allows you to define overall_depth constant between all panels
-                # and still have panels with different size:
-                # overall_depth = lining_depth + offset_y
-                # full offset from X axis = overall_depth - frame_depth
-                "LiningToPanelOffsetY": usecase.convert_si_to_unit(0.025),
-                # applies to DoublePanelVertical, TriplePanelBottom, TriplePanelTop,
-                # TriplePanelLeft, TriplePanelRight
-                # mullion - horizontal distance between panels
-                "MullionThickness": usecase.convert_si_to_unit(0.050),
-                # distance from the first lining to the mullion center
-                "FirstMullionOffset": usecase.convert_si_to_unit(0.3),
-                # applies to TriplePanelVertical
-                # distance from the first lining to the second mullion center
-                "SecondMullionOffset": usecase.convert_si_to_unit(0.45),
-                # applies to DoublePanelHorizontal, TriplePanelBottom, TriplePanelTop,
-                # TriplePanelLeft, TriplePanelRight
-                # works similar way to mullion
-                "TransomThickness": usecase.convert_si_to_unit(0.050),
-                "FirstTransomOffset": usecase.convert_si_to_unit(0.3),
-                # applies to TriplePanelHorizontal
-                "SecondTransomOffset": usecase.convert_si_to_unit(0.6),
-                "ShapeAspectStyle": None,  # DEPRECATED
-            },
-            "panel_properties": [
-                {
-                    "FrameDepth": usecase.convert_si_to_unit(0.035),  # by Y
-                    "FrameThickness": usecase.convert_si_to_unit(0.035),  # by X
-                    # BOTTOM, LEFT, MIDDLE, RIGHT, TOP
-                    "PanelPosition": ...,  # NEVER USED
-                    # defines the basic ways to describe how window panels operate
-                    # how it's hanged, how it opens
-                    "OperationType": None,  # NEVER USED
-                    "ShapeAspectStyle": None,  # DEPRECATED
-                },
-            ],
+            "context": context,
+            "overall_height": overall_height if overall_height is not None else usecase.convert_si_to_unit(0.9),
+            "overall_width": overall_width if overall_width is not None else usecase.convert_si_to_unit(0.6),
+            "partition_type": partition_type,
+            "lining_properties": lining_properties,
+            "panel_properties": panel_properties,
         }
     )
 
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
+    usecase.settings = settings
     usecase.settings["panel_schema"] = DEFAULT_PANEL_SCHEMAS[usecase.settings["partition_type"]]
     return usecase.execute()
 

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

@@ -20,12 +20,12 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def assign_representation(file, **usecase_settings) -> None:
+def assign_representation(
+    file: ifcopenshell.file, product: ifcopenshell.entity_instance, representation: ifcopenshell.entity_instance
+) -> None:
     usecase = Usecase()
     usecase.file = file
-    usecase.settings = {"product": None, "representation": None}
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
+    usecase.settings = {"product": product, "representation": representation}
     return usecase.execute()
 
 

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

@@ -20,16 +20,20 @@ import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.guid
 import ifcopenshell.util.element
+from typing import Optional
 
 
-def connect_element(file, **usecase_settings) -> None:
+def connect_element(
+    file: ifcopenshell.file,
+    relating_element: ifcopenshell.entity_instance,
+    related_element: ifcopenshell.entity_instance,
+    description: Optional[str] = None,
+) -> ifcopenshell.entity_instance:
     settings = {
-        "relating_element": None,
-        "related_element": None,
-        "description": None,
+        "relating_element": relating_element,
+        "related_element": related_element,
+        "description": description,
     }
-    for key, value in usecase_settings.items():
-        settings[key] = value
 
     incompatible_connections = []
 

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

@@ -20,18 +20,24 @@ import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.guid
 import ifcopenshell.util.element
+from typing import Optional
 
 
-def connect_path(file, **usecase_settings) -> None:
+def connect_path(
+    file: ifcopenshell.file,
+    relating_element: ifcopenshell.entity_instance,
+    related_element: ifcopenshell.entity_instance,
+    relating_connection: str = "NOTDEFINED",
+    related_connection: str = "NOTDEFINED",
+    description: Optional[str] = None,
+) -> ifcopenshell.entity_instance:
     settings = {
-        "relating_element": None,
-        "related_element": None,
-        "relating_connection": "NOTDEFINED",
-        "related_connection": "NOTDEFINED",
-        "description": None,
+        "relating_element": relating_element,
+        "related_element": related_element,
+        "relating_connection": relating_connection,
+        "related_connection": related_connection,
+        "description": description,
     }
-    for key, value in usecase_settings.items():
-        settings[key] = value
 
     incompatible_connections = []
     for rel in settings["relating_element"].ConnectedTo:

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

@@ -22,8 +22,16 @@ import ifcopenshell.util.unit
 
 
 def create_2pt_wall(
-    file, element=None, context=None, p1=None, p2=None, elevation=None, height=None, thickness=None, is_si=True
-) -> None:
+    file: ifcopenshell.file,
+    element: ifcopenshell.entity_instance,
+    context: ifcopenshell.entity_instance,
+    p1: tuple[float, float],
+    p2: tuple[float, float],
+    elevation: float,
+    height: float,
+    thickness: float,
+    is_si: bool = True,
+) -> ifcopenshell.entity_instance:
     usecase = Usecase()
     usecase.file = file
     usecase.settings = {

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

@@ -20,30 +20,31 @@ import ifcopenshell
 import ifcopenshell.util.element
 
 
-def disconnect_element(file, **usecase_settings) -> None:
-    settings = {
-        "relating_element": None,
-        "related_element": None,
-    }
-    for key, value in usecase_settings.items():
-        settings[key] = value
-
+def disconnect_element(
+    file: ifcopenshell.file,
+    relating_element: ifcopenshell.entity_instance,
+    related_element: ifcopenshell.entity_instance,
+) -> None:
+    # TODO: arguments relating_element, related_element probably
+    # should be renamed to element1, element2
+    # as api call doesn't really treat them as "relating" and "related"
+    # and just purging all connections between them
     incompatible_connections = []
 
-    for rel in settings["relating_element"].ConnectedTo:
-        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatedElement == settings["related_element"]:
+    for rel in relating_element.ConnectedTo:
+        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatedElement == related_element:
             incompatible_connections.append(rel)
 
-    for rel in settings["relating_element"].ConnectedFrom:
-        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatingElement == settings["related_element"]:
+    for rel in relating_element.ConnectedFrom:
+        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatingElement == related_element:
             incompatible_connections.append(rel)
 
-    for rel in settings["related_element"].ConnectedTo:
-        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatedElement == settings["relating_element"]:
+    for rel in related_element.ConnectedTo:
+        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatedElement == relating_element:
             incompatible_connections.append(rel)
 
-    for rel in settings["related_element"].ConnectedFrom:
-        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatingElement == settings["relating_element"]:
+    for rel in related_element.ConnectedFrom:
+        if rel.is_a() == "IfcRelConnectsElements" and rel.RelatingElement == relating_element:
             incompatible_connections.append(rel)
 
     if incompatible_connections:

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

@@ -19,33 +19,36 @@
 import ifcopenshell
 import ifcopenshell.api
 import ifcopenshell.util.element
+from typing import Optional
 
 
-def disconnect_path(file, **usecase_settings) -> None:
-    settings = {
-        "relating_element": None,
-        "related_element": None,
-        "element": None,
-        "connection_type": None,
-    }
-    for key, value in usecase_settings.items():
-        settings[key] = value
-
-    if settings["connection_type"] and settings["element"]:
+def disconnect_path(
+    file: ifcopenshell.file,
+    element: Optional[ifcopenshell.entity_instance] = None,
+    connection_type: Optional[str] = None,
+    relating_element: Optional[ifcopenshell.entity_instance] = None,
+    related_element: Optional[ifcopenshell.entity_instance] = None,
+) -> None:
+    """There are two options to use this API method:
+    - provide `element` (connected from) and `connection_type` that should be disconnected.
+    - provide connected elements to disconnect explicitly:
+    `relating_element` (connected from) and `related_element` (connected to)
+    """
+    if connection_type and element:
         connections = [
             r
-            for r in settings["element"].ConnectedTo
-            if r.is_a("IfcRelConnectsPathElements") and r.RelatingConnectionType == settings["connection_type"]
+            for r in element.ConnectedTo
+            if r.is_a("IfcRelConnectsPathElements") and r.RelatingConnectionType == connection_type
         ] + [
             r
-            for r in settings["element"].ConnectedFrom
-            if r.is_a("IfcRelConnectsPathElements") and r.RelatedConnectionType == settings["connection_type"]
+            for r in element.ConnectedFrom
+            if r.is_a("IfcRelConnectsPathElements") and r.RelatedConnectionType == connection_type
         ]
-    else:
+    elif related_element:
         connections = [
             r
-            for r in settings["relating_element"].ConnectedTo
-            if r.is_a("IfcRelConnectsPathElements") and r.RelatedElement == settings["related_element"]
+            for r in relating_element.ConnectedTo
+            if r.is_a("IfcRelConnectsPathElements") and r.RelatedElement == related_element
         ]
 
     for connection in set(connections):

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

@@ -31,8 +31,8 @@ def edit_object_placement(
     file: ifcopenshell.file,
     product: ifcopenshell.entity_instance,
     matrix: Optional[NPArrayOfFloats] = None,
-    is_si=True,
-    should_transform_children=False,
+    is_si: bool = True,
+    should_transform_children: bool = False,
 ) -> ifcopenshell.entity_instance:
     usecase = Usecase()
     usecase.file = file

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

@@ -16,14 +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/>.
 
+import ifcopenshell
 
-def map_representation(file, **usecase_settings) -> None:
+
+def map_representation(
+    file: ifcopenshell.file, representation: ifcopenshell.entity_instance
+) -> ifcopenshell.entity_instance:
     usecase = Usecase()
     usecase.file = file
-    usecase.settings = {"representation": None}
-    usecase.ifc_vertices = []
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
+    usecase.settings = {"representation": representation}
     return usecase.execute()
 
 

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

@@ -19,12 +19,10 @@
 import ifcopenshell.util.element
 
 
-def remove_boolean(file, **usecase_settings) -> None:
+def remove_boolean(file: ifcopenshell.file, item: ifcopenshell.entity_instance) -> None:
     usecase = Usecase()
     usecase.file = file
-    usecase.settings = {"item": None}
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
+    usecase.settings = {"item": item}
     return usecase.execute()
 
 

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

@@ -20,12 +20,12 @@ import ifcopenshell.api
 import ifcopenshell.util.element
 
 
-def unassign_representation(file, **usecase_settings) -> None:
+def unassign_representation(
+    file: ifcopenshell.file, product: ifcopenshell.entity_instance, representation: ifcopenshell.entity_instance
+) -> None:
     usecase = Usecase()
     usecase.file = file
-    usecase.settings = {"product": None, "representation": None}
-    for key, value in usecase_settings.items():
-        usecase.settings[key] = value
+    usecase.settings = {"product": product, "representation": representation}
     return usecase.execute()