diff --git a/docs/examples_1.rst b/docs/examples_1.rst index 55c7cd2..7da082c 100644 --- a/docs/examples_1.rst +++ b/docs/examples_1.rst @@ -1,9 +1,9 @@ ####################### The build123d Examples ####################### -.. |siren| replace:: 🚨 +.. |siren| replace:: 🚨 .. |Builder| replace:: 🔨 -.. |Algebra| replace:: ✏️ +.. |Algebra| replace:: ✏️ Overview -------------------------------- @@ -24,17 +24,17 @@ Most of the examples show the builder and algebra modes. :link: examples-benchy :link-type: ref - .. grid-item-card:: Circuit Board With Holes |Builder| |Algebra| - :img-top: assets/examples/thumbnail_circuit_board_01.png + .. grid-item-card:: Canadian Flag Blowing in The Wind |Builder| |Algebra| + :img-top: assets/examples/example_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/example_canadian_flag_01.png + + .. grid-item-card:: Circuit Board With Holes |Builder| |Algebra| + :img-top: assets/examples/thumbnail_circuit_board_01.png :link: examples-circuit_board :link-type: ref - .. grid-item-card:: Clock Face |Builder| |Algebra| + .. grid-item-card:: Clock Face |Builder| |Algebra| :img-top: assets/examples/clock_face.png :link: clock_face :link-type: ref @@ -58,43 +58,43 @@ Most of the examples show the builder and algebra modes. :img-top: assets/examples/thumbnail_build123d_logo_01.png :link: examples-build123d_logo :link-type: ref - - .. grid-item-card:: Maker Coin |Builder| + + .. grid-item-card:: Maker Coin |Builder| :img-top: assets/examples/maker_coin.png :link: maker_coin :link-type: ref - .. grid-item-card:: Multi-Sketch Loft |Builder| |Algebra| + .. grid-item-card:: Multi-Sketch Loft |Builder| |Algebra| :img-top: assets/examples/loft.png :link: multi_sketch_loft :link-type: ref - .. grid-item-card:: Peg Board J Hook |Builder| |Algebra| + .. grid-item-card:: Peg Board J Hook |Builder| |Algebra| :img-top: assets/examples/peg_board_hook.png :link: peg_board_hook :link-type: ref - .. grid-item-card:: Platonic Solids |Algebra| + .. grid-item-card:: Platonic Solids |Algebra| :img-top: assets/examples/platonic_solids.png :link: platonic_solids :link-type: ref - .. grid-item-card:: Playing Cards |Builder| + .. grid-item-card:: Playing Cards |Builder| :img-top: assets/examples/playing_cards.png :link: playing_cards :link-type: ref - .. grid-item-card:: Stud Wall |Algebra| + .. grid-item-card:: Stud Wall |Algebra| :img-top: assets/examples/stud_wall.png :link: stud_wall :link-type: ref - .. grid-item-card:: Tea Cup |Builder| |Algebra| + .. grid-item-card:: Tea Cup |Builder| |Algebra| :img-top: assets/examples/tea_cup.png :link: tea_cup :link-type: ref - .. grid-item-card:: Vase |Builder| |Algebra| + .. grid-item-card:: Vase |Builder| |Algebra| :img-top: assets/examples/vase.png :link: vase :link-type: ref @@ -106,7 +106,7 @@ Most of the examples show the builder and algebra modes. :img-top: assets/examples/thumbnail_{name-of-your-example}_01.{extension} :link: examples-{name-of-your-example} :link-type: ref - + .. ---------------------------------------------------------------------------------------------- .. Details Section .. ---------------------------------------------------------------------------------------------- @@ -119,10 +119,10 @@ Benchy :align: center -The Benchy examples shows how to import a STL model as a `Solid` object with the class `Mesher` and +The Benchy examples shows how to import a STL model as a `Solid` object with the class `Mesher` and modify it by replacing chimney with a BREP version. -.. note +.. note *Attribution:* The low-poly-benchy used in this example is by `reddaugherty`, see @@ -138,7 +138,7 @@ modify it by replacing chimney with a BREP version. .. image:: assets/examples/example_benchy_03.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/benchy.py :start-after: [Code] @@ -156,17 +156,17 @@ Former build123d Logo 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. +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) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/build123d_logo.py :start-after: [Code] :end-before: [End] - -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) + +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/build123d_logo_algebra.py :start-after: [Code] @@ -196,18 +196,18 @@ This example also demonstrates building complex lines that snap to existing feat :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/canadian_flag.py :start-after: [Code] :end-before: [End] - -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) + +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/canadian_flag_algebra.py :start-after: [Code] :end-before: [End] - + .. _examples-circuit_board: @@ -232,13 +232,13 @@ This example demonstrates placing holes around a part. :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/circuit_board.py :start-after: [Code] :end-before: [End] - -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) + +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/circuit_board_algebra.py :start-after: [Code] @@ -252,22 +252,22 @@ Clock Face .. image:: assets/examples/clock_face.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/clock.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/clock_algebra.py :start-after: [Code] :end-before: [End] -The Python code utilizes the build123d library to create a 3D model of a clock face. -It defines a minute indicator with arcs and lines, applying fillets, and then -integrates it into the clock face sketch. The clock face includes a circular outline, -hour labels, and slots at specified positions. The resulting 3D model represents +The Python code utilizes the build123d library to create a 3D model of a clock face. +It defines a minute indicator with arcs and lines, applying fillets, and then +integrates it into the clock face sketch. The clock face includes a circular outline, +hour labels, and slots at specified positions. The resulting 3D model represents a detailed and visually appealing clock design. :class:`~build_common.PolarLocations` are used to position features on the clock face. @@ -280,13 +280,13 @@ Handle .. image:: assets/examples/handle.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/handle.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/handle_algebra.py :start-after: [Code] @@ -301,13 +301,13 @@ Heat Exchanger .. image:: assets/examples/heat_exchanger.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/heat_exchanger.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/heat_exchanger_algebra.py :start-after: [Code] @@ -325,13 +325,13 @@ Key Cap .. image:: assets/examples/key_cap.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/key_cap.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/key_cap_algebra.py :start-after: [Code] @@ -350,14 +350,14 @@ Maker Coin This example creates the maker coin as defined by Angus on the Maker's Muse YouTube channel. There are two key features: -#. the use of :class:`~objects_curve.DoubleTangentArc` to create a smooth +#. the use of :class:`~objects_curve.DoubleTangentArc` to create a smooth transition from the central dish to the outside arc, and #. embossing the text into the top of the coin not just as a simple extrude but from a projection which results in text with even depth. -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/maker_coin.py :start-after: [Code] @@ -375,13 +375,13 @@ Multi-Sketch Loft This example demonstrates lofting a set of sketches, selecting the top and bottom by type, and shelling. -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/loft.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/loft_algebra.py :start-after: [Code] @@ -395,20 +395,20 @@ Peg Board Hook .. image:: assets/examples/peg_board_hook.png :align: center -This script creates a a J-shaped pegboard hook. These hooks are commonly used for -organizing tools in garages, workshops, or other spaces where tools and equipment +This script creates a a J-shaped pegboard hook. These hooks are commonly used for +organizing tools in garages, workshops, or other spaces where tools and equipment need to be stored neatly and accessibly. The hook is created by defining a complex path and then sweeping it to define the hook. The sides of the hook are flattened to aid 3D printing. -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/pegboard_j_hook.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/pegboard_j_hook_algebra.py :start-after: [Code] @@ -424,17 +424,17 @@ Platonic Solids This example creates a custom Part object PlatonicSolid. -Platonic solids are five three-dimensional shapes that are highly symmetrical, -known since antiquity and named after the ancient Greek philosopher Plato. -These solids are unique because their faces are congruent regular polygons, -with the same number of faces meeting at each vertex. The five Platonic solids -are the tetrahedron (4 triangular faces), cube (6 square faces), octahedron -(8 triangular faces), dodecahedron (12 pentagonal faces), and icosahedron -(20 triangular faces). Each solid represents a unique way in which identical -polygons can be arranged in three dimensions to form a convex polyhedron, +Platonic solids are five three-dimensional shapes that are highly symmetrical, +known since antiquity and named after the ancient Greek philosopher Plato. +These solids are unique because their faces are congruent regular polygons, +with the same number of faces meeting at each vertex. The five Platonic solids +are the tetrahedron (4 triangular faces), cube (6 square faces), octahedron +(8 triangular faces), dodecahedron (12 pentagonal faces), and icosahedron +(20 triangular faces). Each solid represents a unique way in which identical +polygons can be arranged in three dimensions to form a convex polyhedron, embodying ideals of symmetry and balance. -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/platonic_solids.py :start-after: [Code] @@ -447,12 +447,12 @@ Playing Cards .. image:: assets/examples/playing_cards.png :align: center -This example creates a customs Sketch objects: Club, Spade, Heart, Diamond, -and PlayingCard in addition to a two part playing card box which has suit -cutouts in the lid. The four suits are created with Bézier curves that were -imported as code from an SVG file and modified to the code found here. +This example creates a customs Sketch objects: Club, Spade, Heart, Diamond, +and PlayingCard in addition to a two part playing card box which has suit +cutouts in the lid. The four suits are created with Bézier curves that were +imported as code from an SVG file and modified to the code found here. -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/playing_cards.py :start-after: [Code] @@ -469,14 +469,14 @@ This example demonstrates creatings custom `Part` objects and putting them into assemblies. The custom object is a `Stud` used in the building industry while the assembly is a `StudWall` created from copies of `Stud` objects for efficiency. Both the `Stud` and `StudWall` objects use `RigidJoints` to define snap points which -are used to position all of objects. +are used to position all of objects. -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/stud_wall.py :start-after: [Code] :end-before: [End] - + .. _tea_cup: Tea Cup @@ -484,32 +484,32 @@ Tea Cup .. image:: assets/examples/tea_cup.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/tea_cup.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/tea_cup_algebra.py :start-after: [Code] :end-before: [End] -This example demonstrates the creation a tea cup, which serves as an example of +This example demonstrates the creation a tea cup, which serves as an example of constructing complex, non-flat geometrical shapes programmatically. The tea cup model involves several CAD techniques, such as: -* Revolve Operations: There is 1 occurrence of a revolve operation. This is used - to create the main body of the tea cup by revolving a profile around an axis, +* Revolve Operations: There is 1 occurrence of a revolve operation. This is used + to create the main body of the tea cup by revolving a profile around an axis, a common technique for generating symmetrical objects like cups. * Sweep Operations: There are 2 occurrences of sweep operations. The handle are created by sweeping a profile along a path to generate non-planar surfaces. * Offset/Shell Operations: the bowl of the cup is hollowed out with the offset - operation leaving the top open. -* Fillet Operations: There is 1 occurrence of a fillet operation which is used to - round the edges for aesthetic improvement and to mimic real-world objects more + operation leaving the top open. +* Fillet Operations: There is 1 occurrence of a fillet operation which is used to + round the edges for aesthetic improvement and to mimic real-world objects more closely. .. _vase: @@ -519,37 +519,37 @@ Vase .. image:: assets/examples/vase.png :align: center -.. dropdown:: |Builder| Reference Implementation (Builder Mode) +.. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/vase.py :start-after: [Code] :end-before: [End] -.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) +.. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/vase_algebra.py :start-after: [Code] :end-before: [End] -This example demonstrates the build123d techniques involving the creation of a vase. -Specifically, it showcases the processes of revolving a sketch, shelling -(creating a hollow object by removing material from its interior), and -selecting edges by position range and type for the application of fillets +This example demonstrates the build123d techniques involving the creation of a vase. +Specifically, it showcases the processes of revolving a sketch, shelling +(creating a hollow object by removing material from its interior), and +selecting edges by position range and type for the application of fillets (rounding off the edges). -* Sketching: Drawing a 2D profile or outline that represents the side view of +* Sketching: Drawing a 2D profile or outline that represents the side view of the vase. -* Revolving: Rotating the sketch around an axis to create a 3D object. This +* Revolving: Rotating the sketch around an axis to create a 3D object. This step transforms the 2D profile into a 3D vase shape. -* Offset/Shelling: Removing material from the interior of the solid vase to +* Offset/Shelling: Removing material from the interior of the solid vase to create a hollow space, making it resemble a real vase more closely. -* Edge Filleting: Selecting specific edges of the vase for filleting, which +* Edge Filleting: Selecting specific edges of the vase for filleting, which involves rounding those edges. The edges are selected based on their position and type. .. NOTE 02: insert new example thumbnails above this line - + .. TODO: Copy this block to add your example details here .. _examples-{name-of-your-example}: @@ -564,15 +564,15 @@ selecting edges by position range and type for the application of fillets .. dropdown:: info - TODO: add more information about your example + TODO: add more information about your example - .. dropdown:: |Builder| Reference Implementation (Builder Mode) + .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/boxes_on_faces.py :start-after: [Code] :end-before: [End] - .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) + .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/boxes_on_faces_algebra.py :start-after: [Code]