diff --git a/docs/assets/examples/example_benchy_01.png b/docs/assets/examples/example_benchy_01.png new file mode 100644 index 00000000..9efbade9 Binary files /dev/null and b/docs/assets/examples/example_benchy_01.png differ diff --git a/docs/assets/examples/example_benchy_02.png b/docs/assets/examples/example_benchy_02.png new file mode 100644 index 00000000..6cdff344 Binary files /dev/null and b/docs/assets/examples/example_benchy_02.png differ diff --git a/docs/assets/examples/example_benchy_03.png b/docs/assets/examples/example_benchy_03.png new file mode 100644 index 00000000..e15a2bef Binary files /dev/null and b/docs/assets/examples/example_benchy_03.png differ diff --git a/docs/assets/examples/example_boxes_on_faces_01.png b/docs/assets/examples/example_boxes_on_faces_01.png new file mode 100644 index 00000000..47ce2c93 Binary files /dev/null and b/docs/assets/examples/example_boxes_on_faces_01.png differ diff --git a/docs/assets/examples/example_build123d_customizable_logo_01.png b/docs/assets/examples/example_build123d_customizable_logo_01.png new file mode 100644 index 00000000..79508e9a Binary files /dev/null and b/docs/assets/examples/example_build123d_customizable_logo_01.png differ diff --git a/docs/assets/examples/thumbnail_benchy_01.png b/docs/assets/examples/thumbnail_benchy_01.png new file mode 100644 index 00000000..982ab17c Binary files /dev/null and b/docs/assets/examples/thumbnail_benchy_01.png differ diff --git a/docs/assets/examples/thumbnail_boxes_on_faces_01.png b/docs/assets/examples/thumbnail_boxes_on_faces_01.png new file mode 100644 index 00000000..65724fff Binary files /dev/null and b/docs/assets/examples/thumbnail_boxes_on_faces_01.png differ diff --git a/docs/assets/examples/thumbnail_build123d_customizable_logo_01.png b/docs/assets/examples/thumbnail_build123d_customizable_logo_01.png new file mode 100644 index 00000000..a8c81f19 Binary files /dev/null and b/docs/assets/examples/thumbnail_build123d_customizable_logo_01.png differ diff --git a/docs/examples_1.rst b/docs/examples_1.rst new file mode 100644 index 00000000..50f83fb3 --- /dev/null +++ b/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 `_ + +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] \ No newline at end of file diff --git a/docs/tutorials.rst b/docs/tutorials.rst index 12d27338..5f8a1a95 100644 --- a/docs/tutorials.rst +++ b/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 diff --git a/examples/benchy.py b/examples/benchy.py index 892056cf..eda356f4 100644 --- a/examples/benchy.py +++ b/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] diff --git a/examples/benchy_v2024.py b/examples/benchy_v2024.py new file mode 100644 index 00000000..a32462a8 --- /dev/null +++ b/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] diff --git a/examples/boxes_on_faces.py b/examples/boxes_on_faces.py index 526b1db1..5698f7a3 100644 --- a/examples/boxes_on_faces.py +++ b/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] \ No newline at end of file diff --git a/examples/boxes_on_faces_algebra.py b/examples/boxes_on_faces_algebra.py index 1acc56a2..7f440583 100644 --- a/examples/boxes_on_faces_algebra.py +++ b/examples/boxes_on_faces_algebra.py @@ -1,5 +1,9 @@ +# 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()]: @@ -7,3 +11,4 @@ if "show_object" in locals(): show_object(b, name="box on faces") +# [End] \ No newline at end of file diff --git a/examples/build123d_customizable_logo.py b/examples/build123d_customizable_logo.py index db053cdc..3ad8fc62 100644 --- a/examples/build123d_customizable_logo.py +++ b/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] \ No newline at end of file diff --git a/examples/build123d_customizable_logo_algebra.py b/examples/build123d_customizable_logo_algebra.py index ce5b4ec0..d72f5774 100644 --- a/examples/build123d_customizable_logo_algebra.py +++ b/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] \ No newline at end of file diff --git a/examples/build123d_logo_algebra.py b/examples/build123d_logo_algebra.py index 01e82395..05c8097a 100644 --- a/examples/build123d_logo_algebra.py +++ b/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