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

closing issue #493 - examples to documentation

docs/examples_1.rst

@@ -34,7 +34,23 @@ Most of the examples show the builder and algebra modes.
         :link: examples-build123d_customizable_logo
         :link-type: ref
 
+    .. grid-item-card:: Former build123d Logo |Builder| |Algebra|
+            :img-top: assets/examples/thumbnail_build123d_logo_01.png
+            :link: examples-build123d_logo
+            :link-type: ref
+    
 
+    .. grid-item-card:: Circuit Board With Holes |Builder| |Algebra| 
+            :img-top: assets/examples/thumbnail_canadian_flag_01.png
+            :link: examples-canadian_flag
+            :link-type: ref
+        
+
+    .. grid-item-card:: Canadian Flag Blowing in The Wind |Builder| |Algebra| 
+            :img-top: assets/examples/thumbnail_circuit_board_01.png
+            :link: examples-circuit_board
+            :link-type: ref
+    
 .. NOTE 01: insert new example thumbnails above this line
 
 .. TODO: Copy this block to add the example thumbnails here
@@ -125,6 +141,106 @@ It shows how text is created, placed and sizes of text is calulated to define si
         :start-after: [Code]
         :end-before: [End]
 
+
+.. _examples-build123d_logo:
+
+Former build123d Logo
+--------------------------------
+.. image:: assets/examples/example_build123d_logo_01.png
+    :align: center
+
+
+This example creates the former build123d logo (new logo was created in the end of 2023).
+
+Using text and lines to create the first build123d logo. 
+The builder mode example also generates the SVG file `logo.svg`.
+
+
+.. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+    .. literalinclude:: ../examples/build123d_logo.py
+        :start-after: [Code]
+        :end-before: [End]
+    
+.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) 
+
+    .. literalinclude:: ../examples/build123d_logo_algebra.py
+        :start-after: [Code]
+        :end-before: [End]
+
+
+.. _examples-canadian_flag:
+
+Canadian Flag Blowing in The Wind
+----------------------------------
+.. image:: assets/examples/example_canadian_flag_01.png
+    :align: center
+
+
+
+A Canadian Flag blowing in the wind created by projecting planar faces onto a non-planar face (the_wind).
+
+This example also demonstrates building complex lines that snap to existing features.
+
+
+.. dropdown:: More Images
+
+    .. image:: assets/examples/example_canadian_flag_02.png
+        :align: center
+
+    .. image:: assets/examples/example_canadian_flag_03.png
+        :align: center
+
+
+.. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+    .. literalinclude:: ../examples/canadian_flag.py
+        :start-after: [Code]
+        :end-before: [End]
+    
+.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) 
+
+    .. literalinclude:: ../examples/canadian_flag_algebra.py
+        :start-after: [Code]
+        :end-before: [End]
+    
+
+.. _examples-circuit_board:
+
+
+Circuit Board With Holes
+------------------------
+.. image:: assets/examples/example_circuit_board_01.png
+    :align: center
+
+
+
+This example demonstrates placing holes around a part.
+
+- Builder mode uses `Locations` context to place the positions.
+- Algebra mode uses `product` and `range` to calculate the positions.
+
+
+
+.. dropdown:: More Images
+
+    .. image:: assets/examples/example_circuit_board_02.png
+        :align: center
+
+
+.. dropdown:: |Builder| Reference Implementation (Builder Mode) 
+
+    .. literalinclude:: ../examples/circuit_board.py
+        :start-after: [Code]
+        :end-before: [End]
+    
+.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) 
+
+    .. literalinclude:: ../examples/circuit_board_algebra.py
+        :start-after: [Code]
+        :end-before: [End]
+    
+
 .. NOTE 02: insert new example thumbnails above this line
     
 

examples/build123d_logo.py

@@ -1,33 +1,31 @@
 """
+name: "build_123d_logo.py"
+title: "Former build123d Logo"
+authors: "Gumyr"
+license: "http://www.apache.org/licenses/LICENSE-2.0"
+created: "2022-08-05"
+modified: "2023-07-31"
 
-name: build123d_logo.py
-by:   Gumyr
-date: August 5th 2022
+description: | 
+    This example creates the former build123d logo (new logo was created in the end of 2023).
 
-desc:
+    Using text and lines to create the first build123d logo. 
+    The builder mode example also generates the SVG file `logo.svg`.
 
-    This example creates the build123d logo.
-
-license:
-
-    Copyright 2022 Gumyr
-
-    Licensed under the Apache License, Version 2.0 (the "License");
-    you may not use this file except in compliance with the License.
-    You may obtain a copy of the License at
-
-        http://www.apache.org/licenses/LICENSE-2.0
-
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
+has_builder_mode: true
+has_algebra_mode: true
+image_files:
+    - "example_build123d_logo_01.png"
 """
+# [Imports]
 from build123d import *
 from build123d import Shape
 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
@@ -120,3 +118,4 @@ show_object(two, name="two")
 show_object(three_d, name="three_d")
 show_object(extension_lines, name="extension_lines")
 show_object(build, name="build")
+# [End]

examples/build123d_logo_algebra.py

@@ -1,6 +1,14 @@
+"""
+for details see `build123d_logo.py`
+"""
+# [Imports]
 from build123d import *
 from ocp_vscode import *
 
+# [Parameters]
+# - none
+
+# [Code]
 logo_text = Text("123d", font_size=10, align=Align.MIN)
 font_height = logo_text.vertices().sort_by(Axis.Y).last.Y
 
@@ -30,7 +38,7 @@ l2 = Line(
 )
 extension_lines = l1 + l2
 extension_lines += Pos(*(l1 @ 0.5)) * arrow_left
-extension_lines += (Pos(*(l2 @ 0.5)) * Rot(z=180)) * arrow_left
+extension_lines += (Pos(*(l2 @ 0.5)) * Rot(Z=180)) * arrow_left
 extension_lines += Line(l1 @ 0.5, l1 @ 0.5 + Vector(dim_line_length, 0))
 extension_lines += Line(l2 @ 0.5, l2 @ 0.5 - Vector(dim_line_length, 0))
 
@@ -40,5 +48,6 @@ build = p1 * build_text
 
 cmpd = Compound.make_compound([three_d, two, one, build, extension_lines])
 
-if "show_object" in locals():
-    show_object(cmpd, name="compound")
+show_object(cmpd, name="compound")
+
+# [End]

examples/canadian_flag.py

@@ -1,43 +1,36 @@
 """
+name: "canadian_flag.py"
+title: "Canadian Flag blowing in the wind"
+authors: "Gumyr"
+license: "http://www.apache.org/licenses/LICENSE-2.0"
+created: "2023-02-23"
+modified: "2023-07-31"
+
+description: | 
+    A Canadian Flag blowing in the wind created by projecting planar faces onto a non-planar face (the_wind).
+
+    This example also demonstrates building complex lines that snap to existing features.
+
+has_builder_mode: true
+has_algebra_mode: true
+image_files:
+    - "example_canadian_flag_01.png"
+    - "example_canadian_flag_02.png"
+    - "example_canadian_flag_03.png"
+"""
 
-Projection Examples: Canadian Flag in the Wind
-
-name: canadian_flag.py
-by:   Gumyr
-date: February 23th 2023
-
-desc: A Canadian Flag blowing in the wind created by projecting planar
-      faces onto a non-planar face (the_wind).
-
-      This example also demonstrates building complex lines that snap to
-      existing features.
-
-license:
-
-    Copyright 2023 Gumyr
-
-    Licensed under the Apache License, Version 2.0 (the "License");
-    you may not use this file except in compliance with the License.
-    You may obtain a copy of the License at
-
-        http://www.apache.org/licenses/LICENSE-2.0
-
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
-
-"""
+# [Imports]
 from math import sin, cos, pi
 from build123d import *
 from ocp_vscode import show_object
 
+# [Parameters]
 # Canadian Flags have a 2:1 aspect ratio
 height = 50
 width = 2 * height
 wave_amplitude = 3
 
+# [Code]
 
 def surface(amplitude, u, v):
     """Calculate the surface displacement of the flag at a given position"""
@@ -112,3 +105,4 @@ show_object(west_field, name="west", options={"color": (255, 0, 0)})
 show_object(east_field, name="east", options={"color": (255, 0, 0)})
 show_object(center_field, name="center", options={"color": (255, 255, 255)})
 show_object(maple_leaf, name="maple", options={"color": (255, 0, 0)})
+# [End]

examples/canadian_flag_algebra.py

@@ -1,12 +1,18 @@
+"""
+for details see `canadian_flag.py`
+"""
+# [Imports]
 from math import sin, cos, pi
 from build123d import *
+from ocp_vscode import *
 
+# [Parameters]
 # Canadian Flags have a 2:1 aspect ratio
 height = 50
 width = 2 * height
 wave_amplitude = 3
 
-
+# [Code]
 def surface(amplitude, u, v):
     """Calculate the surface displacement of the flag at a given position"""
     return v * amplitude / 20 * cos(3.5 * pi * u) + amplitude / 10 * v * sin(
@@ -80,8 +86,8 @@ center_field = project(center_field_planar)
 maple_leaf = project(maple_leaf_planar)
 
 
-if "show_object" in locals():
-    show_object(west_field, name="west", options={"color": (255, 0, 0)})
-    show_object(east_field, name="east", options={"color": (255, 0, 0)})
-    show_object(center_field, name="center", options={"color": (255, 255, 255)})
-    show_object(maple_leaf, name="maple", options={"color": (255, 0, 0)})
+show_object(west_field, name="west", options={"color": (255, 0, 0)})
+show_object(east_field, name="east", options={"color": (255, 0, 0)})
+show_object(center_field, name="center", options={"color": (255, 255, 255)})
+show_object(maple_leaf, name="maple", options={"color": (255, 0, 0)})
+# [End]

examples/circuit_board.py

@@ -1,34 +1,38 @@
 """
+name: "circuit_board.py"
+title: "Circuit Board With Holes"
+authors: "Gumyr"
+license: "http://www.apache.org/licenses/LICENSE-2.0"
+created: "2022-09-01"
+modified: "2024-01-27"
 
-name: circuit_board.py
-by:   Gumyr
-date: September 1st 2022
-
-desc:
-
+description: | 
     This example demonstrates placing holes around a part.
+    
+    - Builder mode uses `Locations` context to place the positions.
+    - Algebra mode uses `product` and `range` to calculate the positions.
 
-license:
-
-    Copyright 2022 Gumyr
-
-    Licensed under the Apache License, Version 2.0 (the "License");
-    you may not use this file except in compliance with the License.
-    You may obtain a copy of the License at
-
-        http://www.apache.org/licenses/LICENSE-2.0
-
-    Unless required by applicable law or agreed to in writing, software
-    distributed under the License is distributed on an "AS IS" BASIS,
-    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-    See the License for the specific language governing permissions and
-    limitations under the License.
+has_builder_mode: true
+has_algebra_mode: true
+image_files:
+    - "example_circuit_board_01.png"
+    - "example_circuit_board_02.png"
 """
-from build123d import *
 
+# [Imports]
+from build123d import *
+from ocp_vscode import *
+
+# [Parameters]
+pcb_length = 70 * MM
+pcb_width = 30 * MM
+pcb_height = 3 * MM
+
+# [Code]
 with BuildPart() as pcb:
     with BuildSketch():
-        Rectangle(70, 30)
+        Rectangle(pcb_length, pcb_width)
+
         for i in range(65 // 5):
             x = i * 5 - 30
             with Locations((x, -15), (x, -10), (x, 10), (x, 15)):
@@ -39,7 +43,7 @@ with BuildPart() as pcb:
                 Circle(1, mode=Mode.SUBTRACT)
         with GridLocations(60, 20, 2, 2):
             Circle(2, mode=Mode.SUBTRACT)
-    extrude(amount=3)
+    extrude(amount=pcb_height)
 
-if "show_object" in locals():
-    show_object(pcb.part.wrapped)
+show_object(pcb.part.wrapped)
+# [End]

examples/circuit_board_algebra.py

@@ -1,15 +1,26 @@
+"""
+for details see `circuit_board.py`
+"""
+# [Imports]
 from itertools import product
 from build123d import *
+from ocp_vscode import show
 
+# [Parameters]
+pcb_length = 70 * MM
+pcb_width = 30 * MM
+pcb_height = 3 * MM
+
+# [Code]
 x_coords = product(range(65 // 5), (-15, -10, 10, 15))
 y_coords = product((30, 35), range(30 // 5 - 1))
 
-pcb = Rectangle(70, 30)
+pcb = Rectangle(pcb_length, pcb_width)
 pcb -= [Pos(i * 5 - 30, y) * Circle(1) for i, y in x_coords]
 pcb -= [Pos(x, i * 5 - 10) * Circle(1) for x, i in y_coords]
 pcb -= [loc * Circle(2) for loc in GridLocations(60, 20, 2, 2)]
 
-pcb = extrude(pcb, 3)
+pcb = extrude(pcb, pcb_height)
 
-if "show_object" in locals():
-    show(pcb)
+show(pcb)
+# [End]