Merge branch 'gumyr:dev' into jernArcFix1

.github/workflows/test.yml

@@ -12,7 +12,7 @@ jobs:
           "3.10",
           #"3.11"
           ]
-        os: [macos-latest, ubuntu-latest, windows-latest]
+        os: [macos-13, ubuntu-latest, windows-latest]
 
     runs-on: ${{ matrix.os }}
     steps:

docs/assemblies.rst

@@ -157,3 +157,96 @@ adds the following attributes to :class:`~topology.Shape`:
     Any iterator can be assigned to the ``children`` attribute but subsequently the children
     are stored as immutable ``tuple`` objects.  To add a child to an existing :class:`~topology.Compound`
     object, the ``children`` attribute will have to be reassigned.
+
+    .. _pack:
+
+******
+pack
+******
+
+The  :meth:`pack.pack` function arranges objects in a compact, non-overlapping layout within a square(ish) 2D area. It is designed to minimize the space between objects while ensuring that no two objects overlap.
+
+.. py:module:: pack
+
+
+.. autofunction:: pack
+
+
+
+Detailed Description
+---------------------
+
+The ``pack`` function uses a bin-packing algorithm to efficiently place objects within a 2D plane, ensuring that there is no overlap and that the space between objects is minimized. This is particularly useful in scenarios where spatial efficiency is crucial, such as layout design and object arrangement in constrained spaces.
+
+The function begins by calculating the bounding boxes for each object, including the specified padding. It then uses a helper function ``_pack2d`` to determine the optimal positions for each object within the 2D plane. The positions are then translated back to the original objects, ensuring that they are arranged without overlapping.
+
+Usage Note
+----------
+
+The ``align_z`` parameter is especially useful when creating print-plates for 3D printing. By aligning the bottoms of the shapes to the same XY plane, you ensure that the objects are perfectly positioned for slicing software, which will no longer need to perform this alignment for you. This can streamline the process and improve the accuracy of the print setup.
+
+Example Usage
+-------------
+
+.. code:: python
+
+    # [import]
+    from build123d import *
+    from ocp_vscode import *
+
+
+    # [initial space]
+    b1 = Box(100, 100, 100, align=(Align.CENTER, Align.CENTER, Align.MIN))
+    b2 = Box(54, 54, 54, align=(Align.CENTER, Align.CENTER, Align.MAX), mode=Mode.SUBTRACT)
+    b3 = Box(34, 34, 34, align=(Align.MIN, Align.MIN, Align.CENTER), mode=Mode.SUBTRACT)
+    b4 = Box(24, 24, 24, align=(Align.MAX, Align.MAX, Align.CENTER), mode=Mode.SUBTRACT)
+
+
+
+.. image:: assets/pack_demo_initial_state.svg
+    :align: center
+
+
+.. code:: python
+
+    # [pack 2D]
+
+    xy_pack = pack(
+        [b1, b2, b3, b4],
+        padding=5,
+        align_z=False
+    )
+
+
+.. image:: assets/pack_demo_packed_xy.svg
+    :align: center
+
+
+.. code:: python
+
+    # [Pack and align_z]
+
+    z_pack = pack(
+        [b1, b2, b3, b4],
+        padding=5,
+        align_z=True
+    )
+
+.. image:: assets/pack_demo_packed_z.svg
+    :align: center
+
+
+Tip
+---
+
+If you place the arranged objects into a ``Compound``, you can easily determine their bounding box and check whether the objects fit on your print bed.
+
+
+.. code:: python
+
+    # [bounding box]
+    print(Compound(xy_pack).bounding_box())
+    # bbox: 0.0 <= x <= 159.0, 0.0 <= y <= 129.0, -54.0 <= z <= 100.0
+    
+    print(Compound(z_pack).bounding_box())
+    # bbox: 0.0 <= x <= 159.0, 0.0 <= y <= 129.0, 0.0 <= z <= 100.0

docs/assets/ttt/ttt-ppp0101.py

@@ -34,9 +34,14 @@
     extrude(amount=80, mode=Mode.INTERSECT)
     # fillet does not work right, mode intersect is safer
 
-    with BuildSketch(Plane.YZ) as s2:
-        Trapezoid(18, 8, 180 - 60, align=(Align.CENTER, Align.MIN))
-    extrude(amount=80, both=True, mode=Mode.SUBTRACT)
-
-show(p)
+    with BuildSketch(Plane.YZ) as s4:
+        with BuildLine() as bl:
+            l1 = Line((0, 0), (18 / 2, 0))
+            l2 = PolarLine(l1 @ 1, 8, 60, length_mode=LengthMode.VERTICAL)
+            l3 = Line(l2 @ 1, (0, 8))
+            mirror(about=Plane.YZ)
+        make_face()
+    extrude(amount=115/2, both=True, mode=Mode.SUBTRACT)
+
+show_object(p)
 print(f"\npart mass = {p.part.volume*densa:0.2f}")

docs/cheat_sheet.rst

@@ -247,6 +247,8 @@ Cheat Sheet
     +----------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
     | :class:`~build_enums.PositionMode`     | LENGTH, PARAMETER                                                                                                                       |
     +----------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
+    | :class:`~build_enums.PrecisionMode`    | LEAST, AVERAGE, GREATEST, SESSION                                                                                                       |
+    +----------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
     | :class:`~build_enums.Select`           | ALL, LAST                                                                                                                               |
     +----------------------------------------+-----------------------------------------------------------------------------------------------------------------------------------------+
     | :class:`~build_enums.Side`             | BOTH, LEFT, RIGHT                                                                                                                       |

docs/conf.py

@@ -103,7 +103,7 @@
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
 # so a file named "default.css" will overwrite the builtin "default.css".
-# html_static_path = ["_static"]
+html_static_path = ["_static"]
 
 # -- Options for hoverxref -------------------------------------------------
 hoverxref_role_types = {

docs/examples_1.rst

@@ -363,6 +363,7 @@ YouTube channel. There are two key features:
         :start-after: [Code]
         :end-before: [End]
 
+
 .. _multi_sketch_loft:
 
 Multi-Sketch Loft

docs/external.rst

@@ -14,19 +14,44 @@ Editors & Viewers
 ocp-vscode
 ==========
 
+A viewer for OCP based Code-CAD (CadQuery, build123d) integrated into
+VS Code.
+
 See: `ocp-vscode <https://github.com/bernhard-42/vscode-ocp-cad-viewer>`_
 (formerly known as cq_vscode)
 
-Watch John Degenstein create three build123d designs being created in realtime with Visual 
+Watch John Degenstein create three build123d designs in realtime with Visual
 Studio Code and the ocp-vscode viewer in a timed event from the TooTallToby 2023 Leadership 
 Challenge: 
 `build123d May 2023 TooTallToby Leaderboard Challenge <https://www.youtube.com/watch?v=fH8aW27jEiw>`_
 
 cq-editor
 =========
 
+GUI editor based on PyQT.
+
 See: `cq-editor <https://github.com/jdegenstein/jmwright-CQ-Editor>`_
 
+yet-another-cad-viewer
+======================
+
+A CAD viewer capable of displaying OCP models (CadQuery/Build123d) in a
+web browser. Mainly intended for deployment of finished models as a static
+website. It also works for developing models with hot reloading, though
+this feature may not be as mature as in ocp-vscode.
+
+See: `yet-another-cad-viewer <https://github.com/yeicor-3d/yet-another-cad-viewer>`_
+
+PartCAD VS Code extension
+=========================
+
+A wrapper around ``ocp-vscode`` (see above) which requires build123d scripts to be
+packaged using ``PartCAD`` (see below). While it requires the overhead of maintaining
+the package, it provides some convenience features (such as UI controls to export models)
+as well as functional features (such as UI controls to pass parameters into build123d scripts
+and AI-based generative design tools).
+
+It's also the most convenient tool to create new packages and parts. More PDM and PLM features are expected to arrive soon.
 
 **************
 Part Libraries
@@ -38,17 +63,88 @@ bd_warehouse
 On-demand generation of parametric parts that seamlessly integrate into
 build123d projects.
 
+Parts available include:
+
+    * fastener - Nuts, Screws, Washers and custom holes
+    * flange - Standardized parametric flanges
+    * pipe - Standardized parametric pipes
+    * thread - Parametric helical threads (Iso, Acme, Plastic, etc.)
+
 See: `bd_warehouse <https://bd-warehouse.readthedocs.io/en/latest/index.html>`_
 
+Superellipses & Superellipsoids
+===============================
+
+Superellipses are a more sophisticated alternative to rounded
+rectangles, with smoothly changing curvature. They are flexible
+shapes that can be adjusted by changing the "exponent" to get a
+result that varies between rectangular and elliptical, or from
+square, through squircle, to circle, and beyond...
+
+Superellipses can be found:
+
+  * in typefaces such as Melior, Eurostyle, and Computer Modern
+  * as the shape of airliner windows, tables, plates
+  * clipping the outline of iOS app icons
+
+They were named and popularized in the 1950s-1960s by the Danish
+mathematician and poet Piet Hein, who used them in the winning
+design for the Sergels Torg roundabout in Stockholm.
+
+See: `Superellipses & Superellipsoids <https://github.com/fanf2/kbd/blob/model-b/keybird42/superellipse.py>`_
+
+Public PartCAD repository
+=========================
+
+See `partcad.org <https://partcad.org/repository>`_ for all the models packaged and published
+using ``PartCAD`` (see below). This repository contains individual parts,
+as well as large assemblies created using those parts. See
+`the OpenVMP robot <https://partcad.org/repository/package/robotics/multimodal/openvmp/robots/don1>`_
+as an example of an assembly
 
 *****
 Tools
 *****
 
+blendquery
+==========
+
+CadQuery and build123d integration for Blender.
+
+See: `blendquery <https://github.com/uki-dev/blendquery>`_
+
+nething
+=======
+
+3D generative AI for CAD modeling. Now everyone is an engineer. Make your ideas real.
+
+See: `nething <https://nething.xyz/>`_
+
+Listen to the following podcast which discusses **nething** in detail:
+`The Next Byte Podcast <https://pod.link/wevolver/episode/74b11c1ff2bfc977adc96e5c7b4cd162>`_
+
 ocp-freecad-cam
 ===============
 
 CAM for CadQuery and Build123d by leveraging FreeCAD library. Visualizes in CQ-Editor 
 and ocp-cad-viewer. Spiritual successor of `cq-cam <https://github.com/voneiden/cq-cam>`_
 
-See: `ocp-freecad-cam <https://github.com/voneiden/ocp-freecad-cam>`_
+See: `ocp-freecad-cam <https://github.com/voneiden/ocp-freecad-cam>`_
+
+PartCAD
+=======
+
+A package manager for CAD models. Build123d is the most supported Code-CAD framework,
+but CadQuery and OpenSCAD are also supported. It can be used by build123d designs
+`to import parts <https://partcad.readthedocs.io/en/latest/use_cases.html#python-build123d>`_
+from PartCAD repositories, and to
+`publish build123d designs <https://partcad.readthedocs.io/en/latest/use_cases.html#publish-packages>`_
+to be consumed by others.
+
+dl4to4ocp
+=========
+
+Library that helps perform `topology optimization <https://en.wikipedia.org/wiki/Topology_optimization>`_ on
+your `OCP <https://github.com/CadQuery/OCP>`_-based CAD
+models (`CadQuery <https://github.com/CadQuery/cadquery>`_/`Build123d <https://github.com/gumyr/build123d>`_/...) using
+the `dl4to <https://github.com/dl4to/dl4to>`_ library.

docs/import_export.rst

@@ -54,6 +54,19 @@ structure make it a versatile choice for sharing designs, drawings, and models
 across various CAD platforms, facilitating seamless collaboration in engineering 
 and architectural projects.
 
+glTF
+----
+
+The glTF (GL Transmission Format) is a royalty-free specification for the efficient 
+transmission and loading of 3D models and scenes by applications. Developed by the 
+Khronos Group, glTF is designed as a compact, interoperable format that enables the 
+quick display of assets across various platforms and devices. glTF supports a rich 
+feature set, including detailed meshes, materials, textures, skeletal animations, 
+and more, facilitating complex 3D visualizations. It streamlines the process of 
+sharing and deploying 3D content in web applications, game engines, and other 
+visualization tools, making it the "JPEG of 3D." glTF's versatility and efficiency 
+have led to its widespread adoption in the 3D content industry.
+
 STL
 ---
 
@@ -186,14 +199,18 @@ ExportSVG
 3D Exporters
 ============
 
+.. py:module:: exporters3d
+
+.. autofunction:: export_brep
+   :noindex:
 
-.. automethod:: topology.Shape.export_brep
+.. autofunction:: export_gltf
    :noindex:
 
-.. automethod:: topology.Shape.export_step
+.. autofunction:: export_step
    :noindex:
 
-.. automethod:: topology.Shape.export_stl
+.. autofunction:: export_stl
    :noindex:
 
 3D Mesh Export
@@ -233,6 +250,11 @@ For example:
 
 .. autoclass:: mesher.Mesher
 
+.. note::
+
+    If you need to align multiple components for 3D printing, you can use the  :ref:`pack() <pack>` function to arrange the objects side by side and align them on the same plane. This ensures that your components are well-organized and ready for the printing process.
+
+
 2D Importers
 ============
 .. py:module:: importers

docs/index.rst

@@ -39,14 +39,14 @@ wide variety of popular CAD tools such as FreeCAD and SolidWorks.
 Build123d could be considered as an evolution of
 `CadQuery <https://cadquery.readthedocs.io/en/latest/index.html>`_ where the
 somewhat restrictive Fluent API (method chaining) is replaced with stateful
-context managers - e.g. `with` blocks - thus enabling the full python toolbox:
+context managers - i.e. `with` blocks - thus enabling the full python toolbox:
 for loops, references to objects, object sorting and filtering, etc.
 
 ########
 Overview
 ########
 
-build123d uses the standard python context manager - e.g. the ``with`` statement often used when
+build123d uses the standard python context manager - i.e. the ``with`` statement often used when
 working with files - as a builder of the object under construction. Once the object is complete
 it can be extracted from the builders and used in other ways: for example exported as a STEP
 file or used in an Assembly.  There are three builders available:
@@ -81,8 +81,10 @@ As an example, consider the design of a tea cup:
     :start-after: [Code]
     :end-before: [End]
 
-.. image:: tea_cup.png
-  :align: center
+.. raw:: html
+
+    <script type="module" src="https://unpkg.com/@google/model-viewer/dist/model-viewer.min.js"></script>
+    <model-viewer poster="_images/tea_cup.png" src="_static/tea_cup.glb" alt="A tea cup modelled in build123d" auto-rotate camera-controls style="width: 100%; height: 50vh;"></model-viewer>
 
 .. note::
 

docs/introductory_examples.rst

@@ -16,8 +16,8 @@ They are organized from simple to complex, so working through them in order is t
             - in *ocp_vscode* simply use e.g. ``show(ex15)`` to the end of your design to view parts, sketches and curves. `show_all()` can be used to automatically show all objects with their variable names as labels.
             - in *CQ-editor* add e.g. ``show_object(ex15.part)``, ``show_object(ex15.sketch)`` or ``show_object(ex15.line)`` to the end of your design to view parts, sketches or lines.
 
-       3. If you want to save your resulting object as an STL from *builder mode*, you can use e.g. ``ex15.part.export_stl("file.stl")``.
-       4. If you want to save your resulting object as an STL from *algebra mode*, you can use e.g. ``ex15.export_stl("file.stl")``
+       3. If you want to save your resulting object as an STL from *builder mode*, you can use e.g. ``export_stl(ex15.part, "file.stl")``.
+       4. If you want to save your resulting object as an STL from *algebra mode*, you can use e.g. ``export_stl(ex15, "file.stl")``
        5. build123d also supports exporting to multiple other file formats including STEP, see here for further information: `Import/Export Formats <https://build123d.readthedocs.io/en/latest/import_export.html>`_
 
 .. contents:: List of Examples