Design organization example (#181)

Co-authored-by: Roberto Pastor Muela <roberto.pastormuela@ansys.com>

Author: chadqueen

doc/source/_static/thumbnails/design_organization.png

@@ -122,6 +122,7 @@
 nbsphinx_thumbnails = {
     "examples/basic_usage": "_static/thumbnails/basic_usage.png",
     "examples/dynamic_sketch_plane": "_static/thumbnails/dynamic_sketch_plane.png",
+    "examples/design_organization": "_static/thumbnails/design_organization.png",
 }
 
 typehints_defaults = "comma"

doc/source/conf.py

@@ -5,5 +5,6 @@ All examples are collected in this page.
 
 .. nbgallery::
 
+    examples/design_organization.mystnb
     examples/dynamic_sketch_plane.mystnb
     examples/basic_usage.mystnb

doc/source/examples.rst

@@ -0,0 +1,95 @@
+---
+jupytext:
+  text_representation:
+    extension: .mystnb
+    format_name: myst
+    format_version: 0.13
+    jupytext_version: 1.14.1
+kernelspec:
+  display_name: Python 3 (ipykernel)
+  language: python
+  name: python3
+---
+
+# Design Organization
+
+The ``Design`` instance creates a new design project within the remote Geometry Service to
+complete all CAD modeling against.
+
+All of the solid and surface bodies within each design can be organized within a customizable
+component hierarchy.
+
+The top-level design node and each child-component node can have one or more bodies assigned
+and one or more components assigned.
+
+The API requires each component of the design hierarchy to be given a user-defined name.
+
+There are several design operations that result in a new body being created within the design.
+Executing each of these methods against a specific component instance explicitly specifies the
+node of the design tree to which the new body should be organized under.
+
++++
+
+Start by importing the fundamental objects:
+
+```{code-cell} ipython3
+from ansys.geometry.core import Modeler
+from ansys.geometry.core.math import UNITVECTOR3D_X, Point2D
+from ansys.geometry.core.misc import UNITS, Distance
+from ansys.geometry.core.sketch import Sketch
+```
+
+## Design organization
+
+Two sketches are extruded to create bodies. The cylinder is assigned to the
+top-level design component. The slot is assigned to the component nested 
+one level beneath the top-level design component.
+
+```{code-cell} ipython3
+modeler = Modeler()
+
+design = modeler.create_design("DesignHierarchyExample")
+
+circle_sketch = Sketch()
+circle_sketch.circle(Point2D([10, 10], UNITS.mm), Distance(10, UNITS.mm))
+
+cylinder_body = design.extrude_sketch("10mmCylinder", circle_sketch, Distance(10, UNITS.mm))
+
+slot_sketch = Sketch()
+slot_sketch.slot(Point2D([40, 10], UNITS.mm), Distance(20, UNITS.mm), Distance(10, UNITS.mm))
+
+nested_component = design.add_component("NestedComponent")
+slot_body = nested_component.extrude_sketch("SlotExtrusion", slot_sketch, Distance(20, UNITS.mm))
+
+design.plot()
+```
+
+## Another Nested Component
+
+A component is simply an organization mechanism. The following creates a component nested
+under the previously created component and then creates another cylinder from the previously
+used sketch.
+
+```{code-cell} ipython3
+
+double_nested_component = nested_component.add_component("DoubleNestedComponent")
+
+circle_surface_body = double_nested_component.create_surface("CircularSurfaceBody", circle_sketch)
+circle_surface_body.translate(UNITVECTOR3D_X, Distance(-10, UNITS.mm))
+
+design.plot()
+```
+
+## Cross Component Targets
+
+Surfaces from any body across the entire design can be used as a reference for creating new bodies.
+
+This example extrudes a cylinder from the surface body assigned to the child component.
+
+```{code-cell} ipython3
+
+cylinder_from_face = nested_component.extrude_face("CylinderFromFace", circle_surface_body.faces[0], Distance(30, UNITS.mm))
+cylinder_from_face.translate(UNITVECTOR3D_X, Distance(-25, UNITS.mm))
+
+design.plot()
+```

doc/source/examples/design_organization.mystnb

@@ -307,21 +307,19 @@ def translate(self, direction: UnitVector3D, distance: Union[Quantity, Distance]
         """
         check_type(direction, UnitVector3D)
         check_type(distance, (Quantity, Distance))
-        check_pint_unit_compatibility(distance, SERVER_UNIT_LENGTH)
 
-        magnitude = (
-            distance.m_as(SERVER_UNIT_LENGTH)
-            if not isinstance(distance, Distance)
-            else distance.value.m_as(SERVER_UNIT_LENGTH)
-        )
+        translate_distance = distance if isinstance(distance, Quantity) else distance.value
+        check_pint_unit_compatibility(translate_distance.units, SERVER_UNIT_LENGTH)
+
+        translation_magnitude = translate_distance.m_as(SERVER_UNIT_LENGTH)
 
         self._grpc_client.log.debug(f"Translating body {self.id}.")
 
         self._bodies_stub.Translate(
             TranslateRequest(
                 bodies=[self.id],
                 direction=unit_vector_to_grpc_direction(direction),
-                distance=magnitude,
+                distance=translation_magnitude,
             )
         )
 

src/ansys/geometry/core/designer/body.py

@@ -216,7 +216,7 @@ def extrude_sketch(
 
         # Perform extrusion request
         request = CreateExtrudedBodyRequest(
-            distance=distance.m_as(SERVER_UNIT_LENGTH),
+            distance=extrude_distance.m_as(SERVER_UNIT_LENGTH),
             parent=self.id,
             plane=plane_to_grpc_plane(sketch._plane),
             geometries=sketch_shapes_to_grpc_geometries(sketch._plane, sketch.edges, sketch.faces),
@@ -262,7 +262,7 @@ def extrude_face(self, name: str, face: Face, distance: Union[Quantity, Distance
 
         # Take the face source directly. No need to verify the source of the face.
         request = CreateExtrudedBodyFromFaceProfileRequest(
-            distance=distance.m_as(SERVER_UNIT_LENGTH),
+            distance=extrude_distance.m_as(SERVER_UNIT_LENGTH),
             parent=self.id,
             face=face.id,
             name=name,

src/ansys/geometry/core/designer/component.py

@@ -14,6 +14,7 @@
 from ansys.geometry.core.materials import Material, MaterialProperty, MaterialPropertyType
 from ansys.geometry.core.math import UNITVECTOR3D_Z, Frame, Plane, Point2D, Point3D, UnitVector3D
 from ansys.geometry.core.misc import UNITS
+from ansys.geometry.core.misc.measurements import Distance
 from ansys.geometry.core.sketch import Sketch
 
 
@@ -114,13 +115,23 @@ def test_face_to_body_creation(modeler: Modeler):
     assert len(design.bodies) == 2
     assert longer_body.volume.m == pytest.approx(Quantity(2e-6, UNITS.m**3).m, rel=1e-6, abs=1e-8)
 
+    longest_body = design.extrude_face(
+        "LongestBoxFromFace", box_body.faces[0], Distance(30, UNITS.mm)
+    )
+
+    assert len(design.components) == 0
+    assert len(design.bodies) == 3
+    assert longest_body.volume.m == pytest.approx(
+        Quantity(3e-6, UNITS.m**3).m, rel=1e-6, abs=1e-8
+    )
+
     nested_component = design.add_component("NestedComponent")
     surface_body = nested_component.create_surface_from_face(
         "SurfaceFromFace", longer_body.faces[2]
     )
 
     assert len(design.components) == 1
-    assert len(design.bodies) == 2
+    assert len(design.bodies) == 3
     assert len(nested_component.components) == 0
     assert len(nested_component.bodies) == 1
     assert surface_body.volume.m == Quantity(0, UNITS.m**3).m
@@ -665,7 +676,7 @@ def test_single_body_translation(modeler: Modeler):
     polygon_comp = design.add_component("PolygonComponent")
     body_polygon_comp = polygon_comp.extrude_sketch("Polygon", sketch_2, Quantity(30, UNITS.mm))
 
-    body_circle_comp.translate(UnitVector3D([1, 0, 0]), Quantity(50, UNITS.mm))
+    body_circle_comp.translate(UnitVector3D([1, 0, 0]), Distance(50, UNITS.mm))
     body_polygon_comp.translate(UnitVector3D([-1, 1, -1]), Quantity(88, UNITS.mm))
 
 
@@ -757,7 +768,7 @@ def test_slot_extrusion(modeler: Modeler):
     sketch.slot(Point2D([10, 10], UNITS.mm), Quantity(10, UNITS.mm), Quantity(5, UNITS.mm))
 
     # Extrude the sketch
-    body = design.extrude_sketch(name="MySlot", sketch=sketch, distance=Quantity(50, UNITS.mm))
+    body = design.extrude_sketch(name="MySlot", sketch=sketch, distance=Distance(50, UNITS.mm))
 
     # A slot has 6 faces and 12 edges
     assert len(body.faces) == 6