From b34caa1b5f7135c528c180655932a50e197e0770 Mon Sep 17 00:00:00 2001 From: Dion Moult Date: Mon, 5 Dec 2022 17:10:22 +1100 Subject: [PATCH] Add documentation for grid API module --- .../api/grid/create_axis_curve.py | 38 ++++++++++-- .../ifcopenshell/api/grid/create_grid_axis.py | 60 ++++++++++++++++--- .../ifcopenshell/api/grid/remove_grid_axis.py | 29 +++++++-- 3 files changed, 111 insertions(+), 16 deletions(-) diff --git a/src/ifcopenshell-python/ifcopenshell/api/grid/create_axis_curve.py b/src/ifcopenshell-python/ifcopenshell/api/grid/create_axis_curve.py index bb99292585..decfb6c466 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/grid/create_axis_curve.py +++ b/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 - "grid_axis": None, + "axis_curve": axis_curve, # A Blender object + "grid_axis": grid_axis, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): existing_curve = self.settings["grid_axis"].AxisCurve diff --git a/src/ifcopenshell-python/ifcopenshell/api/grid/create_grid_axis.py b/src/ifcopenshell-python/ifcopenshell/api/grid/create_grid_axis.py index 99e127a1f7..e794cbdc86 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/grid/create_grid_axis.py +++ b/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", - "same_sense": True, - "uvw_axes": "UAxes", # Choose which axes - "grid": None, + "axis_tag": axis_tag or "A", + "same_sense": same_sense or True, + "uvw_axes": uvw_axes or "UAxes", # Choose which axes + "grid": grid, } - for key, value in settings.items(): - self.settings[key] = value def execute(self): element = self.file.create_entity( diff --git a/src/ifcopenshell-python/ifcopenshell/api/grid/remove_grid_axis.py b/src/ifcopenshell-python/ifcopenshell/api/grid/remove_grid_axis.py index 9e449edf06..ab688a59d1 100644 --- a/src/ifcopenshell-python/ifcopenshell/api/grid/remove_grid_axis.py +++ b/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} - for key, value in settings.items(): - self.settings[key] = value + self.settings = {"axis": axis} def execute(self): if len(self.file.get_inverse(self.settings["axis"].AxisCurve)) == 1: