Merge pull request #490 from 42sol-eu/dev

Example in Documentation (updated rev1)

docs/examples_1.rst

@@ -0,0 +1,156 @@
+#######################
+The build123d Examples
+#######################
+.. |siren| replace:: 🚨 
+.. |Builder| replace:: 🔨
+.. |Algebra| replace:: ✏️ 
+
+Overview
+--------------------------------
+
+In the GitHub repository you will find an `examples folder <https://github.com/42sol-eu/build123d/tree/examples>`_ 
+
+Most of the examples show the builder and algebra modes.
+
+.. ----------------------------------------------------------------------------------------------
+.. Index Section
+.. ----------------------------------------------------------------------------------------------
+
+
+.. grid:: 3
+
+    .. grid-item-card:: Low Poly Benchy |Builder|
+        :img-top:  assets/examples/thumbnail_benchy_01.png
+        :link: examples-benchy
+        :link-type: ref
+
+    .. grid-item-card:: Boxes on Faces |Builder| |Algebra|
+        :img-top: assets/examples/thumbnail_boxes_on_faces_01.png
+        :link: examples-boxes_on_faces
+        :link-type: ref
+
+    .. grid-item-card:: build123d customizable logo |Builder| |Algebra|
+        :img-top: assets/examples/thumbnail_build123d_customizable_logo_01.png
+        :link: examples-build123d_customizable_logo
+        :link-type: ref
+
+
+.. NOTE 01: insert new example thumbnails above this line
+
+.. TODO: Copy this block to add the example thumbnails here
+    .. grid-item-card:: name-of-your-example-with-spaces |Builder| |Algebra|
+            :img-top: assets/examples/thumbnail_{name-of-your-example}_01.{extension}
+            :link: examples-{name-of-your-example}
+            :link-type: ref
+   
+.. ----------------------------------------------------------------------------------------------
+.. Details Section
+.. ----------------------------------------------------------------------------------------------
+
+.. _examples-benchy:
+
+Low Poly Benchy
+--------------------------------
+.. image:: assets/examples/example_benchy_01.png
+    :align: center
+
+
+The Benchy examples shows hot to import a STL model as a `Solid` object with the class `Mesher` and change it to low poly.
+
+.. note 
+
+     *Attribution:*
+     The low-poly-benchy used in this example is by `reddaugherty`, see
+     https://www.printables.com/model/151134-low-poly-benchy.
+
+
+.. dropdown:: Gallery
+
+    .. image:: assets/examples/example_benchy_02.png
+        :align: center
+
+
+    .. image:: assets/examples/example_benchy_03.png
+        :align: center
+
+.. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+    .. literalinclude:: ../examples/benchy.py
+        :start-after: [Code]
+        :end-before: [End]
+
+.. ----------------------------------------------------------------------------------------------
+
+.. _examples-boxes_on_faces:
+
+Boxes on Faces
+--------------------------------
+.. image:: assets/examples/example_boxes_on_faces_01.png
+    :align: center
+
+Create elements on every face of a box.
+
+
+.. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+    .. literalinclude:: ../examples/boxes_on_faces.py
+        :start-after: [Code]
+        :end-before: [End]
+
+.. dropdown:: |Algebra| Reference Implementation (Algebra Mode)  
+
+    .. literalinclude:: ../examples/boxes_on_faces_algebra.py
+        :start-after: [Code]
+        :end-before: [End]
+
+.. _examples-build123d_customizable_logo:
+
+The build123d customizable logo
+--------------------------------
+.. image:: assets/examples/example_build123d_customizable_logo_01.png
+    :align: center
+
+This example creates the build123d customizable logo.
+It shows how text is created, placed and sizes of text is calulated to define sizes of other elements.
+
+.. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+    .. literalinclude:: ../examples/build123d_customizable_logo.py
+        :start-after: [Code]
+        :end-before: [End]
+
+.. dropdown:: |Algebra| Reference Implementation (Algebra Mode)  
+
+    .. literalinclude:: ../examples/build123d_customizable_logo_algebra.py
+        :start-after: [Code]
+        :end-before: [End]
+
+.. NOTE 02: insert new example thumbnails above this line
+    
+
+.. TODO: Copy this block to add your example details here
+    .. _examples-{name-of-your-example}:
+
+    {name-of-your-example-with-spaces}
+    --------------------------------
+    .. image:: assets/examples/example_{name-of-your-example}_01.{extension}
+    :align: center
+
+    .. image:: assets/examples/example_{name-of-your-example}_02.{extension}
+    :align: center
+
+    .. dropdown:: info
+
+        TODO: add more information about your example 
+
+    .. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+        .. literalinclude:: ../examples/boxes_on_faces.py
+            :start-after: [Code]
+            :end-before: [End]
+
+    .. dropdown:: |Algebra| Reference Implementation (Algebra Mode)  
+
+        .. literalinclude:: ../examples/boxes_on_faces_algebra.py
+            :start-after: [Code]
+            :end-before: [End]

docs/tutorials.rst

@@ -12,4 +12,5 @@ as later tutorials build on the concepts introduced in earlier ones.
     tutorial_selectors.rst
     tutorial_lego.rst
     tutorial_joints.rst
+    examples_1.rst
     tttt.rst

examples/benchy.py

@@ -27,15 +27,19 @@
     limitations under the License.
 
 """
+# [Imports]
 from build123d import *
 from ocp_vscode import *
 
+# [Parameters]
+# - none
+
+# [Code]
 # Import the benchy as a Solid model
 importer = Mesher()
 benchy_stl = importer.read("low_poly_benchy.stl")[0]
 
 with BuildPart() as benchy:
-    # Add benchy
     add(benchy_stl)
 
     # Determine the plane that defines the top of the roof
@@ -77,3 +81,4 @@
     extrude(amount=roof_plane_vertices[1].Z - smoke_stack_center.Z)
 
 show(benchy)
+# [End]

examples/benchy_v2024.py

@@ -0,0 +1,90 @@
+"""
+name: "benchy.py"
+title: "Low Poly Benchy"
+authors: "Gumyr"
+license: "http://www.apache.org/licenses/LICENSE-2.0"
+created: "2023-07-09"
+modified: "2024-01-09"
+
+description: | 
+    STL import and edit example.
+
+    The Benchy examples shows hot to import a STL model as a `Solid` object and change it.
+
+    .. note::
+
+        *Attribution:*
+        The low-poly-benchy used in this example is by `reddaugherty`, see
+        https://www.printables.com/model/151134-low-poly-benchy.
+
+
+    .. dropdown:: Info
+
+        - uses file `low_poly_benchy.stl`
+        - uses `class Mesher`
+        - uses `group_by` and `sort_by`
+        - uses `make_polygon`
+        - uses `split`     
+
+has_builder_mode: true
+has_algebra_mode: false
+image_files:
+    - "example_benchy_01.png"
+    - "example_benchy_02.png"
+    - "example_benchy_03.png"
+"""
+# [Imports]
+from build123d import *
+from ocp_vscode import *
+
+# [Parameters]
+# - none
+
+# [Code]
+# Import the benchy as a Solid model
+importer = Mesher()
+benchy_stl = importer.read("low_poly_benchy.stl")[0]
+
+with BuildPart() as benchy:
+    add(benchy_stl)
+
+    # Determine the plane that defines the top of the roof
+    vertices = benchy.vertices()
+    roof_vertices = vertices.filter_by_position(Axis.Z, 38, 42)
+    roof_plane_vertices = [
+        roof_vertices.group_by(Axis.Y, tol_digits=2)[-1].sort_by(Axis.X)[0],
+        roof_vertices.sort_by(Axis.Z)[0],
+        roof_vertices.group_by(Axis.Y, tol_digits=2)[0].sort_by(Axis.X)[0],
+    ]
+    roof_plane = Plane(
+        Face.make_from_wires(
+            Wire.make_polygon([v.to_tuple() for v in roof_plane_vertices])
+        )
+    )
+    # Remove the faceted smoke stack
+    split(bisect_by=roof_plane, keep=Keep.BOTTOM)
+
+    # Determine the position and size of the smoke stack
+    smoke_stack_vertices = vertices.group_by(Axis.Z, tol_digits=0)[-1]
+    smoke_stack_center = sum(
+        [Vector(v.X, v.Y, v.Z) for v in smoke_stack_vertices], Vector()
+    ) * (1 / len(smoke_stack_vertices))
+    smoke_stack_radius = max(
+        [
+            (Vector(*v.to_tuple()) - smoke_stack_center).length
+            for v in smoke_stack_vertices
+        ]
+    )
+
+    # Create the new smoke stack
+    with BuildSketch(Plane(smoke_stack_center)):
+        Circle(smoke_stack_radius)
+        Circle(smoke_stack_radius - 2 * MM, mode=Mode.SUBTRACT)
+    extrude(amount=-3 * MM)
+    with BuildSketch(Plane(smoke_stack_center)):
+        Circle(smoke_stack_radius - 0.5 * MM)
+        Circle(smoke_stack_radius - 2 * MM, mode=Mode.SUBTRACT)
+    extrude(amount=roof_plane_vertices[1].Z - smoke_stack_center.Z)
+
+show(benchy)
+# [End]

examples/boxes_on_faces.py

@@ -23,8 +23,11 @@
     limitations under the License.
 
 """
+# [Imports]
 import build123d as bd
+from ocp_vscode import *
 
+# [Code]
 with bd.BuildPart() as bp:
     bd.Box(3, 3, 3)
     with bd.BuildSketch(*bp.faces()):
@@ -35,3 +38,4 @@
 
 if "show_object" in locals():
     show_object(bp.part.wrapped, name="box on faces")
+# [End]

examples/boxes_on_faces_algebra.py

@@ -1,9 +1,14 @@
+# license see [build123d_license](../LICENSE)
+# [Imports]
 from build123d import *
+from ocp_vscode import *
 
+# [Code]
 b = Box(3, 3, 3)
 b2 = Rot(0, 0, 45) * extrude(Rectangle(1, 2), 0.1)
 for plane in [Plane(f) for f in b.faces()]:
     b += plane * b2
 
 if "show_object" in locals():
     show_object(b, name="box on faces")
+# [End]

examples/build123d_customizable_logo.py

@@ -24,9 +24,14 @@
     See the License for the specific language governing permissions and
     limitations under the License.
 """
+# [Imports]
 from build123d import *
 from ocp_vscode import *
 
+# [Parameters]
+# - none
+
+# [Code]
 with BuildSketch() as logo_text:
     Text("123d", font_size=10, align=(Align.MIN, Align.MIN))
     font_height = logo_text.vertices().sort_by(Axis.Y)[-1].Y
@@ -106,3 +111,5 @@
 # show_object(three_d.part.wrapped, name="three_d")
 # show_object(extension_lines.line.wrapped, name="extension_lines")
 # show_object(build.sketch.wrapped, name="build")
+
+# [End]

examples/build123d_customizable_logo_algebra.py

@@ -1,5 +1,10 @@
+# [Imports]
 from build123d import *
+from ocp_vscode import *
 
+# [Parameters]
+
+# [Code]
 logo_text = Text("123d", font_size=10, align=Align.MIN)
 font_height = logo_text.vertices().sort_by(Axis.Y)[-1].Y
 
@@ -59,3 +64,4 @@
     # show_object(three_d.part.wrapped, name="three_d")
     # show_object(extension_lines.line.wrapped, name="extension_lines")
     # show_object(build.sketch.wrapped, name="build")
+# [End]

examples/build123d_logo_algebra.py

@@ -1,4 +1,5 @@
 from build123d import *
+from ocp_vscode import *
 
 logo_text = Text("123d", font_size=10, align=Align.MIN)
 font_height = logo_text.vertices().sort_by(Axis.Y).last.Y