Add documentation for grid API module

src/ifcopenshell-python/ifcopenshell/api/grid/create_axis_curve.py

@@ -23,14 +23,42 @@ from mathutils import Matrix  # For now, we depend on Blender
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, axis_curve=None, grid_axis=None):
+        """Adds curve geometry to a grid axis to represent the axis extents
+
+        This currently depends on the Blender geometry kernel to function.
+
+        An IFC grid will have a minimum of two axes (typically perpendicular). Each
+        axis will then have a line which represents the extents of the axis.
+
+        :param axis_curve: The Blender object that contains a mesh data block with a
+            single edge.
+        :type axis_curve: bpy.types.Object
+        :param grid_axis: The IfcGridAxis element to add geometry to.
+        :type grid_axis: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example::
+
+            # A pretty standard rectangular grid, with only two axes.
+            grid = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcGrid")
+            axis_a = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="A", uvw_axes="UAxes", grid=grid)
+            axis_1 = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="1", uvw_axes="VAxes", grid=grid)
+
+            # Assume you have these Blender objects in your active Blender session
+            obj1 = bpy.data.objects.get("AxisA")
+            obj2 = bpy.data.objects.get("Axis1")
+            ifcopenshell.api.run("grid.create_axis_curve", model, axis_curve=obj1, grid_axis=axis_a)
+            ifcopenshell.api.run("grid.create_axis_curve", model, axis_curve=obj2, grid_axis=axis_1)
+        """
         self.file = file
         self.settings = {
-            "axis_curve": None,  # A Blender object
+            "axis_curve": axis_curve,  # A Blender object
-            "grid_axis": None,
+            "grid_axis": grid_axis,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         existing_curve = self.settings["grid_axis"].AxisCurve

src/ifcopenshell-python/ifcopenshell/api/grid/create_grid_axis.py

@@ -18,16 +18,62 @@
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, axis_tag=None, same_sense=None, uvw_axes=None, grid=None):
+        """Adds a new grid axis to a grid
+
+        An IFC grid will typically have a minimum of two axes which will be
+        perpendicular to one another. Grids may be rectangular (typically
+        perpendicular lines), radial (where one set of axes is a circle and the
+        other is a line), or triangular (three sets of axes, each at a different
+        angle to one another).
+
+        For a simple rectangular grid, the "UAxes" are a set of one or more
+        horizontal axes, which are typically labeled with the convention of A,
+        B, C, etc. The "VAxes" is another set of one or more vertical axes,
+        typically labeled with the convention of 1, 2, 3, etc. These axes are
+        horizontal or vertical relative to project north.
+
+        For a radial grid, the "UAxes" are straight lines, typically radiating
+        from a central point. The "VAxes" are circular perimeters, with the
+        center of these circles being the same central point.
+
+        For a triangular grid, the UAxes, VAxes, and WAxes are all sets of one
+        or more straight lines.
+
+        :param axis_tag: The name of the axis, that would typically be labeled
+            on drawings or described on site during coordination, such as A, B,
+            C, 1, 2, 3, etc. Defaults to "A".
+        :type axis_tag: str, optional
+        :param same_sense: Determines whether the direction of the axis's line
+            is reversed. True means the direction the geometry is defined in
+            represents the direction of the axis. False means the direction is
+            reversed. Leave as True if unsure. Defaults to "True".
+        :type same_sense: bool, optional
+        :param uvw_axes: Choose from "UAxes", "VAxes" or "WAxes" depending on
+            which set of axes the new axis you are adding should belong to.
+            Defaults to "UAxes".
+        :type uvw_axes: str, optional
+        :param grid: The IfcGrid you are adding the axis to.
+        :type grid: ifcopenshell.entity_instance.entity_instance
+        :return: The newly created IfcGridAxis
+        :rtype: ifcopenshell.entity_instance.entity_instance
+
+        Example:
+
+            # A pretty standard rectangular grid, with only two axes.
+            grid = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcGrid")
+            axis_a = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="A", uvw_axes="UAxes", grid=grid)
+            axis_1 = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="1", uvw_axes="VAxes", grid=grid)
+        """
         self.file = file
         self.settings = {
-            "axis_tag": "A",
+            "axis_tag": axis_tag or "A",
-            "same_sense": True,
+            "same_sense": same_sense or True,
-            "uvw_axes": "UAxes",  # Choose which axes
+            "uvw_axes": uvw_axes or "UAxes",  # Choose which axes
-            "grid": None,
+            "grid": grid,
         }
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         element = self.file.create_entity(

src/ifcopenshell-python/ifcopenshell/api/grid/remove_grid_axis.py

@@ -20,11 +20,32 @@ import ifcopenshell.util.element
 
 
 class Usecase:
-    def __init__(self, file, **settings):
+    def __init__(self, file, axis=None):
+        """Removes a grid axis from a grid
+
+        :param axis: The IfcGridAxis you want to remove.
+        :type axis: ifcopenshell.entity_instance.entity_instance
+        :return: None
+        :rtype: None
+
+        Example:
+
+            # A pretty standard rectangular grid, with only two axes.
+            grid = ifcopenshell.api.run("root.create_entity", model, ifc_class="IfcGrid")
+            axis_a = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="A", uvw_axes="UAxes", grid=grid)
+            axis_1 = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="1", uvw_axes="VAxes", grid=grid)
+
+            # Let's create a third so we can remvoe it later
+            axis_2 = ifcopenshell.api.run("grid.create_grid_axis", model,
+                axis_tag="2", uvw_axes="VAxes", grid=grid)
+
+            # Let's remove it!
+            ifcopenshell.api.run("grid.remove_grid_axis", model, axis=axis_2)
+        """
         self.file = file
-        self.settings = {"axis": None}
+        self.settings = {"axis": axis}
-        for key, value in settings.items():
-            self.settings[key] = value
 
     def execute(self):
         if len(self.file.get_inverse(self.settings["axis"].AxisCurve)) == 1: