diff --git a/docs/OpenSCAD.rst b/docs/OpenSCAD.rst index 899cee9..3c64382 100644 --- a/docs/OpenSCAD.rst +++ b/docs/OpenSCAD.rst @@ -124,7 +124,7 @@ build123d of a piece of angle iron: **build123d Approach** -.. code-block:: python +.. code-block:: build123d # Builder mode with BuildPart() as angle_iron: @@ -135,7 +135,7 @@ build123d of a piece of angle iron: fillet(angle_iron.edges().filter_by(lambda e: e.is_interior), 5 * MM) -.. code-block:: python +.. code-block:: build123d # Algebra mode profile = Rectangle(3 * CM, 4 * MM, align=Align.MIN) diff --git a/docs/advantages.rst b/docs/advantages.rst index 51a6ac0..15f2b7e 100644 --- a/docs/advantages.rst +++ b/docs/advantages.rst @@ -20,7 +20,7 @@ python context manager. ... ) -.. code-block:: python +.. code-block:: build123d # build123d API with BuildPart() as pillow_block: @@ -43,7 +43,7 @@ Each object and operation is now a class instantiation that interacts with the active context implicitly for the user. These instantiations can be assigned to an instance variable as with standard python programming for direct use. -.. code-block:: python +.. code-block:: build123d with BuildSketch() as plan: r = Rectangle(width, height) @@ -62,7 +62,7 @@ with tangents equal to the tangents of l5 and l6 at their end and beginning resp Being able to extract information from existing features allows the user to "snap" new features to these points without knowing their numeric values. -.. code-block:: python +.. code-block:: build123d with BuildLine() as outline: ... @@ -81,6 +81,7 @@ by the last operation and fillets them. Such a selection would be quite difficul otherwise. .. literalinclude:: ../examples/intersecting_pipes.py + :language: build123d :lines: 30, 39-49 @@ -104,7 +105,7 @@ sorting which opens up the full functionality of python lists. To aid the user, common operations have been optimized as shown here along with a fully custom selection: -.. code-block:: python +.. code-block:: build123d top = rail.faces().filter_by(Axis.Z)[-1] ... diff --git a/docs/algebra_performance.rst b/docs/algebra_performance.rst index 3ec9a20..12784c3 100644 --- a/docs/algebra_performance.rst +++ b/docs/algebra_performance.rst @@ -7,7 +7,7 @@ Creating lots of Shapes in a loop means for every step ``fuse`` and ``clean`` wi In an example like the below, both functions get slower and slower the more objects are already fused. Overall it takes on an M1 Mac 4.76 sec. -.. code-block:: python +.. code-block:: build123d diam = 80 holes = Sketch() @@ -22,7 +22,7 @@ already fused. Overall it takes on an M1 Mac 4.76 sec. One way to avoid it is to use lazy evaluation for the algebra operations. Just collect all objects and then call ``fuse`` (``+``) once with all objects and ``clean`` once. Overall it takes 0.19 sec. -.. code-block:: python +.. code-block:: build123d r = Rectangle(2, 2) holes = [ @@ -36,7 +36,7 @@ then call ``fuse`` (``+``) once with all objects and ``clean`` once. Overall it Another way to leverage the vectorized algebra operations is to add a list comprehension of objects to an empty ``Part``, ``Sketch`` or ``Curve``: -.. code-block:: python +.. code-block:: build123d polygons = Sketch() + [ loc * RegularPolygon(radius=5, side_count=5) diff --git a/docs/assemblies.rst b/docs/assemblies.rst index 8889c28..4fe1ada 100644 --- a/docs/assemblies.rst +++ b/docs/assemblies.rst @@ -22,6 +22,7 @@ Here we'll assign labels to all of the components that will be part of the box assembly: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Add labels] :end-before: [Create assembly] @@ -36,6 +37,7 @@ Creation of the assembly is done by simply creating a :class:`~topology.Compound appropriate ``parent`` and ``children`` attributes as shown here: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Create assembly] :end-before: [Display assembly] @@ -43,6 +45,7 @@ To display the topology of an assembly :class:`~topology.Compound`, the :meth:`~ method can be used as follows: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Display assembly] :end-before: [Add to the assembly by assigning the parent attribute of an object] @@ -59,6 +62,7 @@ which results in: To add to an assembly :class:`~topology.Compound` one can change either ``children`` or ``parent`` attributes. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Add to the assembly by assigning the parent attribute of an object] :end-before: [Check that the components in the assembly don't intersect] @@ -180,7 +184,7 @@ Compare this to assembly3_volume which only results in the volume of the top lev assembly2 = Compound(label='Assembly2', children=[assembly1, Box(1, 1, 1)]) assembly3 = Compound(label='Assembly3', children=[assembly2, Box(1, 1, 1)]) total_volume = sum(part.volume for part in assembly3.solids()) # 3 - assembly3_volume = assembly3.volume # 1 + assembly3_volume = assembly3.volume # 1 ****** pack @@ -269,6 +273,6 @@ If you place the arranged objects into a ``Compound``, you can easily determine # [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 diff --git a/docs/build123d_lexer.py b/docs/build123d_lexer.py new file mode 100644 index 0000000..f01e58f --- /dev/null +++ b/docs/build123d_lexer.py @@ -0,0 +1,75 @@ +import inspect +import enum +import sys +import os +from pygments.lexers.python import PythonLexer +from pygments.token import Name +from sphinx.highlighting import lexers + +sys.path.insert(0, os.path.abspath(os.path.join(os.path.dirname(__file__), "../src"))) +import build123d + + +class Build123dLexer(PythonLexer): + """ + Python lexer extended with Build123d-specific highlighting. + Dynamically pulls symbols from build123d.__all__. + """ + + EXTRA_SYMBOLS = set(getattr(build123d, "__all__", [])) + + EXTRA_CLASSES = { + n for n in EXTRA_SYMBOLS + if n[0].isupper() + } + + EXTRA_CONSTANTS = { + n for n in EXTRA_SYMBOLS + if n.isupper() and not callable(getattr(build123d, n, None)) + } + + EXTRA_ENUMS = { + n for n in EXTRA_SYMBOLS + if inspect.isclass(getattr(build123d, n, None)) and issubclass(getattr(build123d, n), enum.Enum) + } + + EXTRA_FUNCTIONS = EXTRA_SYMBOLS - EXTRA_CLASSES - EXTRA_CONSTANTS - EXTRA_ENUMS + + def get_tokens_unprocessed(self, text): + """ + Yield tokens, highlighting Build123d symbols, including chained accesses. + """ + + dot_chain = False + for index, token, value in super().get_tokens_unprocessed(text): + if value == ".": + dot_chain = True + yield index, token, value + continue + + if dot_chain: + # In a chain, don't use top-level categories + if value[0].isupper(): + yield index, Name.Class, value + elif value.isupper(): + yield index, Name.Constant, value + else: + yield index, Name.Function, value + dot_chain = False + continue + + # Top-level classification from __all__ + if value in self.EXTRA_CLASSES: + yield index, Name.Class, value + elif value in self.EXTRA_FUNCTIONS: + yield index, Name.Function, value + elif value in self.EXTRA_CONSTANTS: + yield index, Name.Constant, value + elif value in self.EXTRA_ENUMS: + yield index, Name.Builtin, value + else: + yield index, token, value + +def setup(app): + lexers["build123d"] = Build123dLexer() + return {"version": "0.1"} \ No newline at end of file diff --git a/docs/build_line.rst b/docs/build_line.rst index 70c7f2a..f2f0f93 100644 --- a/docs/build_line.rst +++ b/docs/build_line.rst @@ -15,6 +15,7 @@ Basic Functionality The following is a simple BuildLine example: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 1] :end-before: [Ex. 1] @@ -50,6 +51,7 @@ point ``(0,0)`` and ``(2,0)``. This can be improved upon by specifying constraints that lock the arc to those two end points, as follows: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 2] :end-before: [Ex. 2] @@ -63,6 +65,7 @@ This example can be improved on further by calculating the mid-point of the arc as follows: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 3] :end-before: [Ex. 3] @@ -73,6 +76,7 @@ To make the design even more parametric, the height of the arc can be calculated from ``l1`` as follows: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 4] :end-before: [Ex. 4] @@ -87,6 +91,7 @@ The other operator that is commonly used within BuildLine is ``%`` the tangent a operator. Here is another example: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 5] :end-before: [Ex. 5] @@ -124,6 +129,7 @@ Here is an example of using BuildLine to create an object that otherwise might b difficult to create: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 6] :end-before: [Ex. 6] @@ -155,6 +161,7 @@ The other primary reasons to use BuildLine is to create paths for BuildPart define a path: .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 7] :end-before: [Ex. 7] @@ -184,6 +191,7 @@ to global coordinates. Sometimes it's convenient to work on another plane, espec creating paths for BuildPart ``Sweep`` operations. .. literalinclude:: objects_1d.py + :language: build123d :start-after: [Ex. 8] :end-before: [Ex. 8] diff --git a/docs/build_part.rst b/docs/build_part.rst index 6ea9d11..d5206c8 100644 --- a/docs/build_part.rst +++ b/docs/build_part.rst @@ -15,6 +15,7 @@ Basic Functionality The following is a simple BuildPart example: .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 2] :end-before: [Ex. 2] @@ -52,6 +53,7 @@ This tea cup example uses implicit parameters - note the :func:`~operations_gene operation on the last line: .. literalinclude:: ../examples/tea_cup.py + :language: build123d :start-after: [Code] :end-before: [End] :emphasize-lines: 52 diff --git a/docs/build_sketch.rst b/docs/build_sketch.rst index 803dcb7..76ed6f7 100644 --- a/docs/build_sketch.rst +++ b/docs/build_sketch.rst @@ -16,6 +16,7 @@ Basic Functionality The following is a simple BuildSketch example: .. literalinclude:: objects_2d.py + :language: build123d :start-after: [Ex. 13] :end-before: [Ex. 13] @@ -61,6 +62,7 @@ As an example, let's build the following simple control box with a display on an Here is the code: .. literalinclude:: objects_2d.py + :language: build123d :start-after: [Ex. 14] :end-before: [Ex. 14] :emphasize-lines: 14-25 @@ -88,14 +90,14 @@ on ``Plane.XY`` which one can see by looking at the ``sketch_local`` property of sketch. For example, to display the local version of the ``display`` sketch from above, one would use: -.. code-block:: python +.. code-block:: build123d show_object(display.sketch_local, name="sketch on Plane.XY") while the sketches as applied to their target workplanes is accessible through the ``sketch`` property, as follows: -.. code-block:: python +.. code-block:: build123d show_object(display.sketch, name="sketch on target workplane(s)") @@ -106,7 +108,7 @@ that the new Face may not be oriented as expected. To reorient the Face manually to ``Plane.XY`` one can use the :meth:`~geometry.to_local_coords` method as follows: -.. code-block:: python +.. code-block:: build123d reoriented_face = plane.to_local_coords(face) diff --git a/docs/conf.py b/docs/conf.py index 5ba9cea..ff46e9f 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -49,6 +49,7 @@ extensions = [ "sphinx_design", "sphinx_copybutton", "hoverxref.extension", + "build123d_lexer" ] # Napoleon settings @@ -99,6 +100,7 @@ exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"] # # html_theme = "alabaster" html_theme = "sphinx_rtd_theme" +pygments_style = "colorful" # 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, diff --git a/docs/debugging_logging.rst b/docs/debugging_logging.rst index 3e27acd..eb24d68 100644 --- a/docs/debugging_logging.rst +++ b/docs/debugging_logging.rst @@ -85,7 +85,7 @@ Sometimes the best debugging aid is just placing a print statement in your code. of the build123d classes are setup to provide useful information beyond their class and location in memory, as follows: -.. code-block:: python +.. code-block:: build123d plane = Plane.XY.offset(1) print(f"{plane=}") diff --git a/docs/examples_1.rst b/docs/examples_1.rst index 7da07de..32cc77d 100644 --- a/docs/examples_1.rst +++ b/docs/examples_1.rst @@ -164,6 +164,7 @@ modify it by replacing chimney with a BREP version. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/benchy.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -184,6 +185,7 @@ surface. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/bicycle_tire.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -204,12 +206,14 @@ The builder mode example also generates the SVG file `logo.svg`. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/build123d_logo.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/build123d_logo_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -228,6 +232,7 @@ using the `draft` operation to add appropriate draft angles for mold release. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/cast_bearing_unit.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -257,12 +262,14 @@ This example also demonstrates building complex lines that snap to existing feat .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/canadian_flag.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/canadian_flag_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -293,12 +300,14 @@ This example demonstrates placing holes around a part. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/circuit_board.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/circuit_board_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -313,12 +322,14 @@ Clock Face .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/clock.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/clock_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -340,6 +351,7 @@ Fast Grid Holes .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/fast_grid_holes.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -367,12 +379,14 @@ Handle .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/handle.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/handle_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -388,12 +402,14 @@ Heat Exchanger .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/heat_exchanger.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/heat_exchanger_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -412,12 +428,14 @@ Key Cap .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/key_cap.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/key_cap_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -444,6 +462,7 @@ YouTube channel. There are two key features: .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/maker_coin.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -462,12 +481,14 @@ the top and bottom by type, and shelling. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/loft.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/loft_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -488,6 +509,7 @@ to aid 3D printing. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/pegboard_j_hook.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -495,6 +517,7 @@ to aid 3D printing. .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/pegboard_j_hook_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -521,6 +544,7 @@ embodying ideals of symmetry and balance. .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/platonic_solids.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -539,6 +563,7 @@ imported as code from an SVG file and modified to the code found here. .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/playing_cards.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -558,6 +583,7 @@ are used to position all of objects. .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/stud_wall.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -571,12 +597,14 @@ Tea Cup .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/tea_cup.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/tea_cup_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -610,6 +638,7 @@ Toy Truck .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/toy_truck.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -630,12 +659,14 @@ Vase .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/vase.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/vase_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] @@ -677,11 +708,13 @@ selecting edges by position range and type for the application of fillets .. dropdown:: |Builder| Reference Implementation (Builder Mode) .. literalinclude:: ../examples/boxes_on_faces.py + :language: build123d :start-after: [Code] :end-before: [End] .. dropdown:: |Algebra| Reference Implementation (Algebra Mode) .. literalinclude:: ../examples/boxes_on_faces_algebra.py + :language: build123d :start-after: [Code] :end-before: [End] diff --git a/docs/import_export.rst b/docs/import_export.rst index 73b26b2..53e935f 100644 --- a/docs/import_export.rst +++ b/docs/import_export.rst @@ -6,7 +6,7 @@ Methods and functions specific to exporting and importing build123d objects are For example: -.. code-block:: python +.. code-block:: build123d with BuildPart() as box_builder: Box(1, 1, 1) @@ -142,7 +142,7 @@ The shapes generated from the above steps are to be added as shapes in one of the exporters described below and written as either a DXF or SVG file as shown in this example: -.. code-block:: python +.. code-block:: build123d view_port_origin=(-100, -50, 30) visible, hidden = part.project_to_viewport(view_port_origin) @@ -222,7 +222,7 @@ more complex API than the simple Shape exporters. For example: -.. code-block:: python +.. code-block:: build123d # Create the shapes and assign attributes blue_shape = Solid.make_cone(20, 0, 50) @@ -276,7 +276,7 @@ Both 3MF and STL import (and export) are provided with the :class:`~mesher.Meshe For example: -.. code-block:: python +.. code-block:: build123d importer = Mesher() cone, cyl = importer.read("example.3mf") diff --git a/docs/index.rst b/docs/index.rst index 8c0c70e..6b23c03 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -51,8 +51,7 @@ expressive, algebraic modeling. It offers: * Operator-driven modeling (``obj += sub_obj``, ``Plane.XZ * Pos(X=5) * Rectangle(1, 1)``) for algebraic, readable, and composable design logic -The result is a framework that feels native to Python while providing the full power of -OpenCascade geometry underneath. +.. code-block:: build123d With build123d, intricate parametric models can be created in just a few lines of readable @@ -60,9 +59,10 @@ Python code—as demonstrated by the tea cup example below. .. dropdown:: Teacup Example - .. literalinclude:: ../examples/tea_cup.py - :start-after: [Code] - :end-before: [End] +.. literalinclude:: ../examples/tea_cup.py + :language: build123d + :start-after: [Code] + :end-before: [End] .. raw:: html diff --git a/docs/introductory_examples.rst b/docs/introductory_examples.rst index 1399a80..a887bb9 100644 --- a/docs/introductory_examples.rst +++ b/docs/introductory_examples.rst @@ -36,12 +36,14 @@ Just about the simplest possible example, a rectangular :class:`~objects_part.Bo * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 1] :end-before: [Ex. 1] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 1] :end-before: [Ex. 1] @@ -63,6 +65,7 @@ A rectangular box, but with a hole added. from the :class:`~objects_part.Box`. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 2] :end-before: [Ex. 2] @@ -73,6 +76,7 @@ A rectangular box, but with a hole added. from the :class:`~objects_part.Box`. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 2] :end-before: [Ex. 2] @@ -94,6 +98,7 @@ Build a prismatic solid using extrusion. and then use :class:`~build_part.BuildPart`'s :meth:`~operations_part.extrude` feature. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 3] :end-before: [Ex. 3] @@ -103,6 +108,7 @@ Build a prismatic solid using extrusion. :class:`~objects_sketch.Rectangle`` and then use the :meth:`~operations_part.extrude` operation for parts. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 3] :end-before: [Ex. 3] @@ -126,6 +132,7 @@ variables for the line segments, but it will be useful in a later example. from :class:`~build_line.BuildLine` into a closed Face. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 4] :end-before: [Ex. 4] @@ -138,6 +145,7 @@ variables for the line segments, but it will be useful in a later example. segments into a Face. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 4] :end-before: [Ex. 4] @@ -158,6 +166,7 @@ Note that to build a closed face it requires line segments that form a closed sh at one (or multiple) places. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 5] :end-before: [Ex. 5] @@ -168,6 +177,7 @@ Note that to build a closed face it requires line segments that form a closed sh (with :class:`geometry.Rot`) would rotate the object. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 5] :end-before: [Ex. 5] @@ -188,6 +198,7 @@ Sometimes you need to create a number of features at various You can use a list of points to construct multiple objects at once. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 6] :end-before: [Ex. 6] @@ -200,6 +211,7 @@ Sometimes you need to create a number of features at various is short for ``obj - obj1 - obj2 - ob3`` (and more efficient, see :ref:`algebra_performance`). .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 6] :end-before: [Ex. 6] @@ -218,6 +230,7 @@ Sometimes you need to create a number of features at various you would like. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 7] :end-before: [Ex. 7] @@ -227,6 +240,7 @@ Sometimes you need to create a number of features at various for each location via loops or list comprehensions. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 7] :end-before: [Ex. 7] @@ -247,12 +261,14 @@ create the final profile. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 8] :end-before: [Ex. 8] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 8] :end-before: [Ex. 8] @@ -273,12 +289,14 @@ edges, you could simply pass in ``ex9.edges()``. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 9] :end-before: [Ex. 9] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 9] :end-before: [Ex. 9] @@ -303,6 +321,7 @@ be the highest z-dimension group. makes use of :class:`~objects_part.Hole` which automatically cuts through the entire part. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 10] :end-before: [Ex. 10] @@ -314,6 +333,7 @@ be the highest z-dimension group. of :class:`~objects_part.Hole`. Different to the *context mode*, you have to add the ``depth`` of the whole. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 10] :end-before: [Ex. 10] @@ -339,6 +359,7 @@ be the highest z-dimension group. cut these from the parent. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 11] :end-before: [Ex. 11] @@ -355,6 +376,7 @@ be the highest z-dimension group. parent. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 11] :end-before: [Ex. 11] @@ -376,12 +398,14 @@ edge that needs a complex profile. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 12] :end-before: [Ex. 12] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 12] :end-before: [Ex. 12] @@ -401,6 +425,7 @@ Counter-sink and counter-bore holes are useful for creating recessed areas for f We use a face to establish a location for :class:`~build_common.Locations`. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 13] :end-before: [Ex. 13] @@ -410,6 +435,7 @@ Counter-sink and counter-bore holes are useful for creating recessed areas for f onto this plane. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 13] :end-before: [Ex. 13] @@ -417,7 +443,7 @@ Counter-sink and counter-bore holes are useful for creating recessed areas for f .. _ex 14: -14. Position on a line with '\@', '\%' and introduce Sweep +1. Position on a line with '\@', '\%' and introduce Sweep ------------------------------------------------------------ build123d includes a feature for finding the position along a line segment. This @@ -437,9 +463,10 @@ path, please see example 37 for a way to make this placement easier. The :meth:`~operations_generic.sweep` method takes any pending faces and sweeps them through the provided path (in this case the path is taken from the pending edges from ``ex14_ln``). - :meth:`~operations_part.revolve` requires a single connected wire. + :meth:`~operations_part.revolve` requires a single connected wire. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 14] :end-before: [Ex. 14] @@ -449,6 +476,7 @@ path, please see example 37 for a way to make this placement easier. path (in this case the path is taken from ``ex14_ln``). .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 14] :end-before: [Ex. 14] @@ -471,6 +499,7 @@ Additionally the '@' operator is used to simplify the line segment commands. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 15] :end-before: [Ex. 15] @@ -479,6 +508,7 @@ Additionally the '@' operator is used to simplify the line segment commands. Combine lines via the pattern ``Curve() + [l1, l2, l3, l4, l5]`` .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 15] :end-before: [Ex. 15] @@ -496,12 +526,14 @@ The ``Plane.offset()`` method shifts the plane in the normal direction (positive * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 16] :end-before: [Ex. 16] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 16] :end-before: [Ex. 16] @@ -520,12 +552,14 @@ Here we select the farthest face in the Y-direction and turn it into a :class:`~ * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 17] :end-before: [Ex. 17] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 17] :end-before: [Ex. 17] @@ -546,6 +580,7 @@ with a negative distance. We then use ``Mode.SUBTRACT`` to cut it out from the main body. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 18] :end-before: [Ex. 18] @@ -554,6 +589,7 @@ with a negative distance. We then use ``-=`` to cut it out from the main body. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 18] :end-before: [Ex. 18] @@ -578,6 +614,7 @@ this custom Axis. :class:`~build_common.Locations` then the part would be offset from the workplane by the vertex z-position. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 19] :end-before: [Ex. 19] @@ -588,6 +625,7 @@ this custom Axis. :class:`~geometry.Pos` then the part would be offset from the workplane by the vertex z-position. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 19] :end-before: [Ex. 19] @@ -606,12 +644,14 @@ negative x-direction. The resulting Plane is offset from the original position. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 20] :end-before: [Ex. 20] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 20] :end-before: [Ex. 20] @@ -630,12 +670,14 @@ positioning another cylinder perpendicular and halfway along the first. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 21] :end-before: [Ex. 21] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 21] :end-before: [Ex. 21] @@ -656,6 +698,7 @@ example. Use the :meth:`~geometry.Plane.rotated` method to rotate the workplane. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 22] :end-before: [Ex. 22] @@ -664,6 +707,7 @@ example. Use the operator ``*`` to relocate the plane (post-multiplication!). .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 22] :end-before: [Ex. 22] @@ -690,12 +734,14 @@ It is highly recommended to view your sketch before you attempt to call revolve. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 23] :end-before: [Ex. 23] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 23] :end-before: [Ex. 23] @@ -716,12 +762,14 @@ Loft can behave unexpectedly when the input faces are not parallel to each other * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 24] :end-before: [Ex. 24] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 24] :end-before: [Ex. 24] @@ -739,6 +787,7 @@ Loft can behave unexpectedly when the input faces are not parallel to each other BuildSketch faces can be transformed with a 2D :meth:`~operations_generic.offset`. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 25] :end-before: [Ex. 25] @@ -747,6 +796,7 @@ Loft can behave unexpectedly when the input faces are not parallel to each other Sketch faces can be transformed with a 2D :meth:`~operations_generic.offset`. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 25] :end-before: [Ex. 25] @@ -772,12 +822,14 @@ Note that self intersecting edges and/or faces can break both 2D and 3D offsets. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 26] :end-before: [Ex. 26] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 26] :end-before: [Ex. 26] @@ -796,12 +848,14 @@ a face and offset half the width of the box. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 27] :end-before: [Ex. 27] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 27] :end-before: [Ex. 27] @@ -820,6 +874,7 @@ a face and offset half the width of the box. use the faces of this object to cut holes in a sphere. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 28] :end-before: [Ex. 28] @@ -828,6 +883,7 @@ a face and offset half the width of the box. We create a triangular prism and then later use the faces of this object to cut holes in a sphere. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 28] :end-before: [Ex. 28] @@ -849,12 +905,14 @@ the bottle opening. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 29] :end-before: [Ex. 29] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 29] :end-before: [Ex. 29] @@ -874,12 +932,14 @@ create a closed line that is made into a face and extruded. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 30] :end-before: [Ex. 30] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 30] :end-before: [Ex. 30] @@ -899,12 +959,14 @@ rotates any "children" groups by default. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 31] :end-before: [Ex. 31] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 31] :end-before: [Ex. 31] @@ -927,12 +989,14 @@ separate calls to :meth:`~operations_part.extrude`. adding these faces until the for-loop. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 32] :end-before: [Ex. 32] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 32] :end-before: [Ex. 32] @@ -954,6 +1018,7 @@ progressively modify the size of each square. The function returns a :class:`~build_sketch.BuildSketch`. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 33] :end-before: [Ex. 33] @@ -962,6 +1027,7 @@ progressively modify the size of each square. The function returns a ``Sketch`` object. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 33] :end-before: [Ex. 33] @@ -983,6 +1049,7 @@ progressively modify the size of each square. the 2nd "World" text on the top of the "Hello" text. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 34] :end-before: [Ex. 34] @@ -993,6 +1060,7 @@ progressively modify the size of each square. the ``topf`` variable to select the same face and deboss (indented) the text "World". .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 34] :end-before: [Ex. 34] @@ -1012,6 +1080,7 @@ progressively modify the size of each square. arc for two instances of :class:`~objects_sketch.SlotArc`. .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 35] :end-before: [Ex. 35] @@ -1021,6 +1090,7 @@ progressively modify the size of each square. a :class:`~objects_curve.RadiusArc` to create an arc for two instances of :class:`~operations_sketch.SlotArc`. .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 35] :end-before: [Ex. 35] @@ -1041,11 +1111,13 @@ with ``Until.NEXT`` or ``Until.LAST``. * **Builder mode** .. literalinclude:: general_examples.py + :language: build123d :start-after: [Ex. 36] :end-before: [Ex. 36] * **Algebra mode** .. literalinclude:: general_examples_algebra.py + :language: build123d :start-after: [Ex. 36] :end-before: [Ex. 36] diff --git a/docs/joints.rst b/docs/joints.rst index 07cc623..3b117b0 100644 --- a/docs/joints.rst +++ b/docs/joints.rst @@ -46,14 +46,14 @@ A rigid joint positions two components relative to each another with no freedom and a ``joint_location`` which defines both the position and orientation of the joint (see :class:`~geometry.Location`) - as follows: -.. code-block:: python +.. code-block:: build123d RigidJoint(label="outlet", to_part=pipe, joint_location=path.location_at(1)) Once a joint is bound to a part this way, the :meth:`~topology.Joint.connect_to` method can be used to repositioning another part relative to ``self`` which stay fixed - as follows: -.. code-block:: python +.. code-block:: build123d pipe.joints["outlet"].connect_to(flange_outlet.joints["pipe"]) @@ -70,6 +70,7 @@ flanges are attached to the ends of a curved pipe: .. image:: assets/rigid_joints_pipe.png .. literalinclude:: rigid_joints_pipe.py + :language: build123d :emphasize-lines: 19-20, 23-24 Note how the locations of the joints are determined by the :meth:`~topology.Mixin1D.location_at` method @@ -132,6 +133,7 @@ Component moves along a single axis as with a sliding latch shown here: The code to generate these components follows: .. literalinclude:: slide_latch.py + :language: build123d :emphasize-lines: 30, 52, 55 .. image:: assets/joint-latch.png @@ -193,6 +195,7 @@ is found within a rod end as shown here: .. image:: assets/rod_end.png .. literalinclude:: rod_end.py + :language: build123d :emphasize-lines: 40-44,51,53 Note how limits are defined during the instantiation of the ball joint when ensures that the pin or bolt diff --git a/docs/key_concepts_algebra.rst b/docs/key_concepts_algebra.rst index 655b6c7..76f876a 100644 --- a/docs/key_concepts_algebra.rst +++ b/docs/key_concepts_algebra.rst @@ -12,26 +12,26 @@ Object arithmetic - Creating a box and a cylinder centered at ``(0, 0, 0)`` - .. code-block:: python + .. code-block:: build123d b = Box(1, 2, 3) c = Cylinder(0.2, 5) - Fusing a box and a cylinder - .. code-block:: python + .. code-block:: build123d r = Box(1, 2, 3) + Cylinder(0.2, 5) - Cutting a cylinder from a box - .. code-block:: python + .. code-block:: build123d r = Box(1, 2, 3) - Cylinder(0.2, 5) - Intersecting a box and a cylinder - .. code-block:: python + .. code-block:: build123d r = Box(1, 2, 3) & Cylinder(0.2, 5) @@ -54,7 +54,7 @@ The generic forms of object placement are: 1. Placement on ``plane`` or at ``location`` relative to XY plane: - .. code-block:: python + .. code-block:: build123d plane * alg_compound location * alg_compound @@ -62,7 +62,7 @@ The generic forms of object placement are: 2. Placement on the ``plane`` and then moved relative to the ``plane`` by ``location`` (the location is relative to the local coordinate system of the plane). - .. code-block:: python + .. code-block:: build123d plane * location * alg_compound @@ -73,7 +73,7 @@ Examples: - Box on the ``XY`` plane, centered at `(0, 0, 0)` (both forms are equivalent): - .. code-block:: python + .. code-block:: build123d Plane.XY * Box(1, 2, 3) @@ -84,7 +84,7 @@ Examples: - Box on the ``XY`` plane centered at `(0, 1, 0)` (all three are equivalent): - .. code-block:: python + .. code-block:: build123d Plane.XY * Pos(0, 1, 0) * Box(1, 2, 3) @@ -96,21 +96,21 @@ Examples: - Box on plane ``Plane.XZ``: - .. code-block:: python + .. code-block:: build123d Plane.XZ * Box(1, 2, 3) - Box on plane ``Plane.XZ`` with a location ``(X=1, Y=2, Z=3)`` relative to the ``XZ`` plane, i.e., using the x-, y- and z-axis of the ``XZ`` plane: - .. code-block:: python + .. code-block:: build123d Plane.XZ * Pos(1, 2, 3) * Box(1, 2, 3) - Box on plane ``Plane.XZ`` moved to ``(X=1, Y=2, Z=3)`` relative to this plane and rotated there by the angles `(X=0, Y=100, Z=45)` around ``Plane.XZ`` axes: - .. code-block:: python + .. code-block:: build123d Plane.XZ * Pos(1, 2, 3) * Rot(0, 100, 45) * Box(1, 2, 3) @@ -121,7 +121,7 @@ Examples: - Box on plane ``Plane.XZ`` rotated on this plane by the angles ``(X=0, Y=100, Z=45)`` (using the x-, y- and z-axis of the ``XZ`` plane) and then moved to ``(X=1, Y=2, Z=3)`` relative to the ``XZ`` plane: - .. code-block:: python + .. code-block:: build123d Plane.XZ * Rot(0, 100, 45) * Pos(0,1,2) * Box(1, 2, 3) @@ -131,7 +131,7 @@ Combing both concepts **Object arithmetic** and **Placement at locations** can be combined: - .. code-block:: python + .. code-block:: build123d b = Plane.XZ * Rot(X=30) * Box(1, 2, 3) + Plane.YZ * Pos(X=-1) * Cylinder(0.2, 5) diff --git a/docs/key_concepts_builder.rst b/docs/key_concepts_builder.rst index 20370f3..076882d 100644 --- a/docs/key_concepts_builder.rst +++ b/docs/key_concepts_builder.rst @@ -61,7 +61,7 @@ Example Workflow Here is an example of using a Builder to create a simple part: -.. code-block:: python +.. code-block:: build123d from build123d import * @@ -117,21 +117,21 @@ class for further processing. One can access the objects created by these builders by referencing the appropriate instance variable. For example: -.. code-block:: python +.. code-block:: build123d with BuildPart() as my_part: ... show_object(my_part.part) -.. code-block:: python +.. code-block:: build123d with BuildSketch() as my_sketch: ... show_object(my_sketch.sketch) -.. code-block:: python +.. code-block:: build123d with BuildLine() as my_line: ... @@ -144,7 +144,7 @@ Implicit Builder Instance Variables One might expect to have to reference a builder's instance variable when using objects or operations that impact that builder like this: -.. code-block:: python +.. code-block:: build123d with BuildPart() as part_builder: Box(part_builder, 10,10,10) @@ -153,7 +153,7 @@ Instead, build123d determines from the scope of the object or operation which builder it applies to thus eliminating the need for the user to provide this information - as follows: -.. code-block:: python +.. code-block:: build123d with BuildPart() as part_builder: Box(10,10,10) @@ -175,7 +175,7 @@ be generated on any plane which allows users to put a workplane where they are w and then work in local 2D coordinate space. -.. code-block:: python +.. code-block:: build123d with BuildPart(Plane.XY) as example: ... # a 3D-part @@ -199,7 +199,7 @@ One is not limited to a single workplane at a time. In the following example all faces of the first box are used to define workplanes which are then used to position rotated boxes. -.. code-block:: python +.. code-block:: build123d import build123d as bd @@ -223,7 +223,7 @@ When positioning objects or operations within a builder Location Contexts are us function in a very similar was to the builders in that they create a context where one or more locations are active within a scope. For example: -.. code-block:: python +.. code-block:: build123d with BuildPart(): with Locations((0,10),(0,-10)): @@ -244,7 +244,7 @@ its scope - much as the hour and minute indicator on an analogue clock. Also note that the locations are local to the current location(s) - i.e. ``Locations`` can be nested. It's easy for a user to retrieve the global locations: -.. code-block:: python +.. code-block:: build123d with Locations(Plane.XY, Plane.XZ): locs = GridLocations(1, 1, 2, 2) @@ -271,7 +271,7 @@ an iterable of objects is often required (often a ShapeList). Here is the definition of :meth:`~operations_generic.fillet` to help illustrate: -.. code-block:: python +.. code-block:: build123d def fillet( objects: Union[Union[Edge, Vertex], Iterable[Union[Edge, Vertex]]], @@ -281,7 +281,7 @@ Here is the definition of :meth:`~operations_generic.fillet` to help illustrate: To use this fillet operation, an edge or vertex or iterable of edges or vertices must be provided followed by a fillet radius with or without the keyword as follows: -.. code-block:: python +.. code-block:: build123d with BuildPart() as pipes: Box(10, 10, 10, rotation=(10, 20, 30)) @@ -297,7 +297,7 @@ Combination Modes Almost all objects or operations have a ``mode`` parameter which is defined by the ``Mode`` Enum class as follows: -.. code-block:: python +.. code-block:: build123d class Mode(Enum): ADD = auto() @@ -329,7 +329,7 @@ build123d stores points (to be specific ``Location`` (s)) internally to be used positions for the placement of new objects. By default, a single location will be created at the origin of the given workplane such that: -.. code-block:: python +.. code-block:: build123d with BuildPart() as pipes: Box(10, 10, 10, rotation=(10, 20, 30)) @@ -338,7 +338,7 @@ will create a single 10x10x10 box centered at (0,0,0) - by default objects are centered. One can create multiple objects by pushing points prior to creating objects as follows: -.. code-block:: python +.. code-block:: build123d with BuildPart() as pipes: with Locations((-10, -10, -10), (10, 10, 10)): @@ -370,7 +370,7 @@ Builder's Pending Objects When a builder exits, it will push the object created back to its parent if there was one. Here is an example: -.. code-block:: python +.. code-block:: build123d height, width, thickness, f_rad = 60, 80, 20, 10 diff --git a/docs/location_arithmetic.rst b/docs/location_arithmetic.rst index f26834e..d5c4b0e 100644 --- a/docs/location_arithmetic.rst +++ b/docs/location_arithmetic.rst @@ -9,7 +9,7 @@ Position a shape relative to the XY plane For the following use the helper function: -.. code-block:: python +.. code-block:: build123d def location_symbol(location: Location, scale: float = 1) -> Compound: return Compound.make_triad(axes_scale=scale).locate(location) @@ -22,7 +22,7 @@ For the following use the helper function: 1. **Positioning at a location** - .. code-block:: python + .. code-block:: build123d loc = Location((0.1, 0.2, 0.3), (10, 20, 30)) @@ -35,7 +35,7 @@ For the following use the helper function: 2) **Positioning on a plane** - .. code-block:: python + .. code-block:: build123d plane = Plane.XZ @@ -54,7 +54,7 @@ Relative positioning to a plane 1. **Position an object on a plane relative to the plane** - .. code-block:: python + .. code-block:: build123d loc = Location((0.1, 0.2, 0.3), (10, 20, 30)) @@ -77,7 +77,7 @@ Relative positioning to a plane 2. **Rotate an object on a plane relative to the plane** - .. code-block:: python + .. code-block:: build123d loc = Location((0.1, 0.2, 0.3), (10, 20, 30)) @@ -96,7 +96,7 @@ Relative positioning to a plane More general: - .. code-block:: python + .. code-block:: build123d loc = Location((0.1, 0.2, 0.3), (10, 20, 30)) @@ -114,7 +114,7 @@ Relative positioning to a plane 3. **Rotate and position an object relative to a location** - .. code-block:: python + .. code-block:: build123d loc = Location((0.1, 0.2, 0.3), (10, 20, 30)) @@ -133,7 +133,7 @@ Relative positioning to a plane 4. **Position and rotate an object relative to a location** - .. code-block:: python + .. code-block:: build123d loc = Location((0.1, 0.2, 0.3), (10, 20, 30)) diff --git a/docs/moving_objects.rst b/docs/moving_objects.rst index 088973c..b36dde4 100644 --- a/docs/moving_objects.rst +++ b/docs/moving_objects.rst @@ -22,7 +22,7 @@ construction process. The following tools are commonly used to specify locations Example: -.. code-block:: python +.. code-block:: build123d with Locations((10, 20, 30)): Box(5, 5, 5) @@ -42,7 +42,7 @@ an existing one. Example: -.. code-block:: python +.. code-block:: build123d rotated_box = Rotation(45, 0, 0) * box @@ -55,13 +55,13 @@ Position ^^^^^^^^ - **Absolute Position:** Set the position directly. -.. code-block:: python +.. code-block:: build123d shape.position = (x, y, z) - **Relative Position:** Adjust the position incrementally. -.. code-block:: python +.. code-block:: build123d shape.position += (x, y, z) shape.position -= (x, y, z) @@ -71,13 +71,13 @@ Orientation ^^^^^^^^^^^ - **Absolute Orientation:** Set the orientation directly. -.. code-block:: python +.. code-block:: build123d shape.orientation = (X, Y, Z) - **Relative Orientation:** Adjust the orientation incrementally. -.. code-block:: python +.. code-block:: build123d shape.orientation += (X, Y, Z) shape.orientation -= (X, Y, Z) @@ -86,25 +86,25 @@ Movement Methods ^^^^^^^^^^^^^^^^ - **Relative Move:** -.. code-block:: python +.. code-block:: build123d shape.move(Location) - **Relative Move of Copy:** -.. code-block:: python +.. code-block:: build123d relocated_shape = shape.moved(Location) - **Absolute Move:** -.. code-block:: python +.. code-block:: build123d shape.locate(Location) - **Absolute Move of Copy:** -.. code-block:: python +.. code-block:: build123d relocated_shape = shape.located(Location) @@ -119,12 +119,12 @@ Transformation a.k.a. Translation and Rotation - **Translation:** Move a shape relative to its current position. -.. code-block:: python +.. code-block:: build123d relocated_shape = shape.translate(x, y, z) - **Rotation:** Rotate a shape around a specified axis by a given angle. -.. code-block:: python +.. code-block:: build123d rotated_shape = shape.rotate(Axis, angle_in_degrees) diff --git a/docs/objects.rst b/docs/objects.rst index 26c1fe8..85204bf 100644 --- a/docs/objects.rst +++ b/docs/objects.rst @@ -7,7 +7,7 @@ For example, a :class:`~objects_part.Torus` is defined by a major and minor radi Builder mode, objects are positioned with ``Locations`` while in Algebra mode, objects are positioned with the ``*`` operator and shown in these examples: -.. code-block:: python +.. code-block:: build123d with BuildPart() as disk: with BuildSketch(): @@ -18,7 +18,7 @@ are positioned with the ``*`` operator and shown in these examples: Circle(d, mode=Mode.SUBTRACT) extrude(amount=c) -.. code-block:: python +.. code-block:: build123d sketch = Circle(a) - Pos(b, 0.0) * Rectangle(c, c) - Pos(0.0, b) * Circle(d) disk = extrude(sketch, c) @@ -36,7 +36,7 @@ right or left of each Axis. The following diagram shows how this alignment works For example: -.. code-block:: python +.. code-block:: build123d with BuildSketch(): Circle(1, align=(Align.MIN, Align.MIN)) @@ -49,7 +49,7 @@ In 3D the ``align`` parameter also contains a Z align value but otherwise works Note that the ``align`` will also accept a single ``Align`` value which will be used on all axes - as shown here: -.. code-block:: python +.. code-block:: build123d with BuildSketch(): Circle(1, align=Align.MIN) @@ -519,6 +519,7 @@ Here is an example of a custom sketch object specially created as part of the de this playing card storage box (:download:`see the playing_cards.py example <../examples/playing_cards.py>`): .. literalinclude:: ../examples/playing_cards.py + :language: build123d :start-after: [Club] :end-before: [Club] diff --git a/docs/operations.rst b/docs/operations.rst index e7532b6..8dedac9 100644 --- a/docs/operations.rst +++ b/docs/operations.rst @@ -6,14 +6,14 @@ Operations are functions that take objects as inputs and transform them into new Here are a couple ways to use :func:`~operations_part.extrude`, in Builder and Algebra mode: -.. code-block:: python +.. code-block:: build123d with BuildPart() as cylinder: with BuildSketch(): Circle(radius) extrude(amount=height) -.. code-block:: python +.. code-block:: build123d cylinder = extrude(Circle(radius), amount=height) diff --git a/docs/selectors.rst b/docs/selectors.rst index 189b367..ca41f9b 100644 --- a/docs/selectors.rst +++ b/docs/selectors.rst @@ -74,7 +74,7 @@ It is important to note that standard list methods such as `sorted` or `filtered be used to easily build complex selectors beyond what is available with the predefined sorts and filters. Here is an example of a custom filters: -.. code-block:: python +.. code-block:: build123d with BuildSketch() as din: ... @@ -88,7 +88,7 @@ The :meth:`~topology.ShapeList.filter_by` method can take lambda expressions as fluent chain of operations which enables integration of custom filters into a larger change of selectors as shown in this example: -.. code-block:: python +.. code-block:: build123d obj = Box(1, 1, 1) - Cylinder(0.2, 1) faces_with_holes = obj.faces().filter_by(lambda f: f.inner_wires()) diff --git a/docs/tech_drawing_tutorial.rst b/docs/tech_drawing_tutorial.rst index 227caab..b4f9db6 100644 --- a/docs/tech_drawing_tutorial.rst +++ b/docs/tech_drawing_tutorial.rst @@ -4,14 +4,14 @@ Technical Drawing Tutorial ########################## -This example demonstrates how to generate a standard technical drawing of a 3D part -using `build123d`. It creates orthographic and isometric views of a Nema 23 stepper +This example demonstrates how to generate a standard technical drawing of a 3D part +using `build123d`. It creates orthographic and isometric views of a Nema 23 stepper motor and exports the result as an SVG file suitable for printing or inspection. Overview -------- -A technical drawing represents a 3D object in 2D using a series of standardized views. +A technical drawing represents a 3D object in 2D using a series of standardized views. These include: - **Plan (Top View)** – as seen from directly above (Z-axis down) @@ -24,8 +24,8 @@ Each view is aligned to a position on the page and optionally scaled or annotate How It Works ------------ -The script uses the `project_to_viewport` method to project the 3D part geometry into 2D. -A helper function, `project_to_2d`, sets up the viewport (camera origin and up direction) +The script uses the `project_to_viewport` method to project the 3D part geometry into 2D. +A helper function, `project_to_2d`, sets up the viewport (camera origin and up direction) and places the result onto a virtual drawing sheet. The steps involved are: @@ -34,7 +34,7 @@ The steps involved are: 2. Define a `TechnicalDrawing` border and title block using A4 page size. 3. Generate each of the standard views and apply transformations to place them. 4. Add dimensions using `ExtensionLine` and labels using `Text`. -5. Export the drawing using `ExportSVG`, separating visible and hidden edges by layer +5. Export the drawing using `ExportSVG`, separating visible and hidden edges by layer and style. Result @@ -59,7 +59,7 @@ Code ---- .. literalinclude:: technical_drawing.py - :language: python + :language: build123d :start-after: [code] :end-before: [end] diff --git a/docs/tips.rst b/docs/tips.rst index ad5c299..2567088 100644 --- a/docs/tips.rst +++ b/docs/tips.rst @@ -92,7 +92,7 @@ consider a plate with four chamfered holes like this: When selecting edges to be chamfered one might first select the face that these edges belong to then select the edges as shown here: -.. code-block:: python +.. code-block:: build123d from build123d import * @@ -118,7 +118,7 @@ a common OpenCascade Python wrapper (`OCP `_) i interchange objects both from CadQuery to build123d and vice-versa by transferring the ``wrapped`` objects as follows (first from CadQuery to build123d): -.. code-block:: python +.. code-block:: build123d import build123d as b3d b3d_solid = b3d.Solid.make_box(1,1,1) @@ -129,7 +129,7 @@ objects as follows (first from CadQuery to build123d): Secondly, from build123d to CadQuery as follows: -.. code-block:: python +.. code-block:: build123d import build123d as b3d import cadquery as cq @@ -209,7 +209,7 @@ Why doesn't BuildSketch(Plane.XZ) work? When creating a sketch not on the default ``Plane.XY`` users may expect that they are drawing directly on the workplane / coordinate system provided. For example: -.. code-block:: python +.. code-block:: build123d with BuildSketch(Plane.XZ) as vertical_sketch: Rectangle(1, 1) @@ -229,7 +229,7 @@ Why does ``BuildSketch`` work this way? Consider an example where the user wants plane not aligned with any Axis, as follows (this is often done when creating a sketch on a ``Face`` of a 3D part but is simulated here by rotating a ``Plane``): -.. code-block:: python +.. code-block:: build123d with BuildSketch(Plane.YZ.rotated((123, 45, 6))) as custom_plane: Rectangle(1, 1, align=Align.MIN) @@ -251,7 +251,7 @@ Why is BuildLine not working as expected within the scope of BuildSketch? As described above, all sketching is done on a local ``Plane.XY``; however, the following is a common issue: -.. code-block:: python +.. code-block:: build123d with BuildSketch() as sketch: with BuildLine(Plane.XZ): diff --git a/docs/topology_selection.rst b/docs/topology_selection.rst index f1ef50e..694c75f 100644 --- a/docs/topology_selection.rst +++ b/docs/topology_selection.rst @@ -40,7 +40,7 @@ Overview Both shape objects and builder objects have access to selector methods to select all of a feature as long as they can contain the feature being selected. -.. code-block:: python +.. code-block:: build123d # In context with BuildSketch() as context: @@ -70,7 +70,7 @@ existed in the referenced object before the last operation, nor the modifying ob :class:`~build_enums.Select` as selector criteria is only valid for builder objects! - .. code-block:: python + .. code-block:: build123d # In context with BuildPart() as context: @@ -85,7 +85,7 @@ existed in the referenced object before the last operation, nor the modifying ob Create a simple part to demonstrate selectors. Select using the default criteria ``Select.ALL``. Specifying ``Select.ALL`` for the selector is not required. -.. code-block:: python +.. code-block:: build123d with BuildPart() as part: Box(5, 5, 1) @@ -107,7 +107,7 @@ Create a simple part to demonstrate selectors. Select using the default criteria Select features changed in the last operation with criteria ``Select.LAST``. -.. code-block:: python +.. code-block:: build123d with BuildPart() as part: Box(5, 5, 1) @@ -125,7 +125,7 @@ Select features changed in the last operation with criteria ``Select.LAST``. Select only new edges from the last operation with ``Select.NEW``. This option is only available for a ``ShapeList`` of edges! -.. code-block:: python +.. code-block:: build123d with BuildPart() as part: Box(5, 5, 1) @@ -142,7 +142,7 @@ This only returns new edges which are not reused from Box or Cylinder, in this c the objects `intersect`. But what happens if the objects don't intersect and all the edges are reused? -.. code-block:: python +.. code-block:: build123d with BuildPart() as part: Box(5, 5, 1, align=(Align.CENTER, Align.CENTER, Align.MAX)) @@ -164,7 +164,7 @@ only completely new edges created by the operation. Chamfer and fillet modify the current object, but do not have new edges via ``Select.NEW``. - .. code-block:: python + .. code-block:: build123d with BuildPart() as part: Box(5, 5, 1) @@ -187,7 +187,7 @@ another "combined" shape object and returns the edges new to the combined shape. ``new_edges`` is available both Algebra mode or Builder mode, but is necessary in Algebra Mode where ``Select.NEW`` is unavailable -.. code-block:: python +.. code-block:: build123d box = Box(5, 5, 1) circle = Cylinder(2, 5) @@ -200,7 +200,7 @@ Algebra Mode where ``Select.NEW`` is unavailable ``new_edges`` can also find edges created during a chamfer or fillet operation by comparing the object before the operation to the "combined" object. -.. code-block:: python +.. code-block:: build123d box = Box(5, 5, 1) circle = Cylinder(2, 5) @@ -263,7 +263,7 @@ Finally, the vertices can be captured with a list slice for the last 4 list item items are sorted from least to greatest ``X`` position. Remember, ``ShapeList`` is a subclass of ``list``, so any list slice can be used. -.. code-block:: python +.. code-block:: build123d part.vertices().sort_by(Axis.X)[-4:] @@ -320,7 +320,7 @@ group by ``SortBy.AREA``. The ``ShapeList`` of smallest faces is available from list index. Finally, a ``ShapeList`` has access to selectors, so calling |edges| will return a new list of all edges in the previous list. -.. code-block:: python +.. code-block:: build123d part.faces().group_by(SortBy.AREA)[0].edges()) @@ -368,7 +368,7 @@ might be with a list comprehension, however |filter_by| has the capability to ta lambda function as a filter condition on the entire list. In this case, the normal of each face can be checked against a vector direction and filtered accordingly. -.. code-block:: python +.. code-block:: build123d part.faces().filter_by(lambda f: f.normal_at() == Vector(0, 0, 1)) diff --git a/docs/topology_selection/filter_examples.rst b/docs/topology_selection/filter_examples.rst index f7233b8..0b0f3fc 100644 --- a/docs/topology_selection/filter_examples.rst +++ b/docs/topology_selection/filter_examples.rst @@ -18,11 +18,11 @@ operations, and are sometimes necessary e.g. before sorting or filtering by radi .. dropdown:: Setup .. literalinclude:: examples/filter_geomtype.py - :language: python + :language: build123d :lines: 3, 8-13 .. literalinclude:: examples/filter_geomtype.py - :language: python + :language: build123d :lines: 15 .. figure:: ../assets/topology_selection/filter_geomtype_line.png @@ -31,7 +31,7 @@ operations, and are sometimes necessary e.g. before sorting or filtering by radi | .. literalinclude:: examples/filter_geomtype.py - :language: python + :language: build123d :lines: 17 .. figure:: ../assets/topology_selection/filter_geomtype_cylinder.png @@ -52,11 +52,11 @@ circular edges selects the counterbore faces that meet the joint criteria. .. dropdown:: Setup .. literalinclude:: examples/filter_all_edges_circle.py - :language: python + :language: build123d :lines: 3, 8-41 .. literalinclude:: examples/filter_all_edges_circle.py - :language: python + :language: build123d :lines: 43-47 .. figure:: ../assets/topology_selection/filter_all_edges_circle.png @@ -74,14 +74,14 @@ Plane will select faces parallel to the plane. .. dropdown:: Setup - .. code-block:: python + .. code-block:: build123d from build123d import * with BuildPart() as part: Box(1, 1, 1) -.. code-block:: python +.. code-block:: build123d part.faces().filter_by(Axis.Z) part.faces().filter_by(Plane.XY) @@ -96,7 +96,7 @@ accomplish this with feature properties or methods. Here, we are looking for fac the dot product of face normal and either the axis direction or the plane normal is about to 0. The result is faces parallel to the axis or perpendicular to the plane. -.. code-block:: python +.. code-block:: build123d part.faces().filter_by(lambda f: abs(f.normal_at().dot(Axis.Z.direction) < 1e-6) part.faces().filter_by(lambda f: abs(f.normal_at().dot(Plane.XY.z_dir)) < 1e-6) @@ -122,11 +122,11 @@ and then filtering for the specific inner wire by radius. .. dropdown:: Setup .. literalinclude:: examples/filter_inner_wire_count.py - :language: python + :language: build123d :lines: 4, 9-16 .. literalinclude:: examples/filter_inner_wire_count.py - :language: python + :language: build123d :lines: 18-21 .. figure:: ../assets/topology_selection/filter_inner_wire_count.png @@ -140,7 +140,7 @@ axis and range. To do that we can filter for faces with 6 inner wires, sort for select the top face, and then filter for the circular edges of the inner wires. .. literalinclude:: examples/filter_inner_wire_count.py - :language: python + :language: build123d :lines: 25-32 .. figure:: ../assets/topology_selection/filter_inner_wire_count_linear.png @@ -163,11 +163,11 @@ any line edges. .. dropdown:: Setup .. literalinclude:: examples/filter_nested.py - :language: python + :language: build123d :lines: 4, 9-22 .. literalinclude:: examples/filter_nested.py - :language: python + :language: build123d :lines: 26-32 .. figure:: ../assets/topology_selection/filter_nested.png @@ -186,7 +186,7 @@ different fillets accordingly. Then the ``Face`` ``is_circular_*`` properties ar to highlight the resulting fillets. .. literalinclude:: examples/filter_shape_properties.py - :language: python + :language: build123d :lines: 3-4, 8-22 .. figure:: ../assets/topology_selection/filter_shape_properties.png diff --git a/docs/topology_selection/group_examples.rst b/docs/topology_selection/group_examples.rst index 3f0057b..d91de21 100644 --- a/docs/topology_selection/group_examples.rst +++ b/docs/topology_selection/group_examples.rst @@ -14,7 +14,7 @@ result knowing how many edges to expect. .. dropdown:: Setup .. literalinclude:: examples/group_axis.py - :language: python + :language: build123d :lines: 4, 9-17 .. figure:: ../assets/topology_selection/group_axis_without.png @@ -26,7 +26,7 @@ However, ``group_by`` can be used to first group all the edges by z-axis positio group again by length. In both cases, you can select the desired edges from the last group. .. literalinclude:: examples/group_axis.py - :language: python + :language: build123d :lines: 21-22 .. figure:: ../assets/topology_selection/group_axis_with.png @@ -46,11 +46,11 @@ with the largest hole. .. dropdown:: Setup .. literalinclude:: examples/group_hole_area.py - :language: python + :language: build123d :lines: 4, 9-17 .. literalinclude:: examples/group_hole_area.py - :language: python + :language: build123d :lines: 21-24 .. figure:: ../assets/topology_selection/group_hole_area.png @@ -72,11 +72,11 @@ then the desired groups are selected with the ``group`` method using the lengths .. dropdown:: Setup .. literalinclude:: examples/group_properties_with_keys.py - :language: python + :language: build123d :lines: 4, 9-26 .. literalinclude:: examples/group_properties_with_keys.py - :language: python + :language: build123d :lines: 30, 31 .. figure:: ../assets/topology_selection/group_length_key.png @@ -94,11 +94,11 @@ and then further specify only the edges the bearings and pins are installed from .. dropdown:: Adding holes .. literalinclude:: examples/group_properties_with_keys.py - :language: python + :language: build123d :lines: 35-43 .. literalinclude:: examples/group_properties_with_keys.py - :language: python + :language: build123d :lines: 47-50 .. figure:: ../assets/topology_selection/group_radius_key.png @@ -109,7 +109,7 @@ and then further specify only the edges the bearings and pins are installed from Note that ``group_by`` is not the only way to capture edges with a known property value! ``filter_by`` with a lambda expression can be used as well: -.. code-block:: python +.. code-block:: build123d radius_groups = part.edges().filter_by(GeomType.CIRCLE) bearing_edges = radius_groups.filter_by(lambda e: e.radius == 8) diff --git a/docs/topology_selection/sort_examples.rst b/docs/topology_selection/sort_examples.rst index a4779fc..ecdbf96 100644 --- a/docs/topology_selection/sort_examples.rst +++ b/docs/topology_selection/sort_examples.rst @@ -23,11 +23,11 @@ be used with``group_by``. .. dropdown:: Setup .. literalinclude:: examples/sort_sortby.py - :language: python + :language: build123d :lines: 3, 8-13 .. literalinclude:: examples/sort_sortby.py - :language: python + :language: build123d :lines: 19-22 .. figure:: ../assets/topology_selection/sort_sortby_length.png @@ -36,7 +36,7 @@ be used with``group_by``. | .. literalinclude:: examples/sort_sortby.py - :language: python + :language: build123d :lines: 24-27 .. figure:: ../assets/topology_selection/sort_sortby_distance.png @@ -57,11 +57,11 @@ the order is random. .. dropdown:: Setup .. literalinclude:: examples/sort_along_wire.py - :language: python + :language: build123d :lines: 3, 8-12 .. literalinclude:: examples/sort_along_wire.py - :language: python + :language: build123d :lines: 14-15 .. figure:: ../assets/topology_selection/sort_not_along_wire.png @@ -73,7 +73,7 @@ Vertices may be sorted along the wire they fall on to create order. Notice the f radii now increase in order. .. literalinclude:: examples/sort_along_wire.py - :language: python + :language: build123d :lines: 26-28 .. figure:: ../assets/topology_selection/sort_along_wire.png @@ -94,11 +94,11 @@ edge can be found sorting along y-axis. .. dropdown:: Setup .. literalinclude:: examples/sort_axis.py - :language: python + :language: build123d :lines: 4, 9-18 .. literalinclude:: examples/sort_axis.py - :language: python + :language: build123d :lines: 22-24 .. figure:: ../assets/topology_selection/sort_axis.png @@ -118,11 +118,11 @@ Here we are sorting the boxes by distance from the origin, using an empty ``Vert .. dropdown:: Setup .. literalinclude:: examples/sort_distance_from.py - :language: python + :language: build123d :lines: 2-5, 9-13 .. literalinclude:: examples/sort_distance_from.py - :language: python + :language: build123d :lines: 15-16 .. figure:: ../assets/topology_selection/sort_distance_from_origin.png @@ -135,7 +135,7 @@ property ``volume``, and getting the last (largest) box. Then, the boxes sorted their distance from the largest box. .. literalinclude:: examples/sort_distance_from.py - :language: python + :language: build123d :lines: 19-20 .. figure:: ../assets/topology_selection/sort_distance_from_largest.png diff --git a/docs/tttt.rst b/docs/tttt.rst index 8379142..1c1f75f 100644 --- a/docs/tttt.rst +++ b/docs/tttt.rst @@ -98,6 +98,7 @@ Party Pack 01-01 Bearing Bracket .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0101.py + :language: build123d .. _ttt-ppp0102: @@ -114,6 +115,7 @@ Party Pack 01-02 Post Cap .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0102.py + :language: build123d .. _ttt-ppp0103: @@ -129,6 +131,7 @@ Party Pack 01-03 C Clamp Base .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0103.py + :language: build123d .. _ttt-ppp0104: @@ -144,6 +147,7 @@ Party Pack 01-04 Angle Bracket .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0104.py + :language: build123d .. _ttt-ppp0105: @@ -159,6 +163,7 @@ Party Pack 01-05 Paste Sleeve .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0105.py + :language: build123d .. _ttt-ppp0106: @@ -174,6 +179,7 @@ Party Pack 01-06 Bearing Jig .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0106.py + :language: build123d .. _ttt-ppp0107: @@ -189,6 +195,7 @@ Party Pack 01-07 Flanged Hub .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0107.py + :language: build123d .. _ttt-ppp0108: @@ -204,6 +211,7 @@ Party Pack 01-08 Tie Plate .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0108.py + :language: build123d .. _ttt-ppp0109: @@ -219,6 +227,7 @@ Party Pack 01-09 Corner Tie .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0109.py + :language: build123d .. _ttt-ppp0110: @@ -234,6 +243,7 @@ Party Pack 01-10 Light Cap .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-ppp0110.py + :language: build123d .. _ttt-23-02-02-sm_hanger: @@ -249,6 +259,7 @@ Party Pack 01-10 Light Cap .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-23-02-02-sm_hanger.py + :language: build123d .. _ttt-23-t-24: @@ -265,6 +276,7 @@ Party Pack 01-10 Light Cap .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-23-t-24-curved_support.py + :language: build123d .. _ttt-24-spo-06: @@ -281,3 +293,4 @@ Party Pack 01-10 Light Cap .. dropdown:: Reference Implementation .. literalinclude:: assets/ttt/ttt-24-SPO-06-Buffer_Stand.py + :language: build123d diff --git a/docs/tutorial_design.rst b/docs/tutorial_design.rst index 3950399..f16afbc 100644 --- a/docs/tutorial_design.rst +++ b/docs/tutorial_design.rst @@ -4,8 +4,8 @@ Designing a Part in build123d ############################# -Designing a part with build123d involves a systematic approach that leverages the power -of 2D profiles, extrusions, and revolutions. Where possible, always work in the lowest +Designing a part with build123d involves a systematic approach that leverages the power +of 2D profiles, extrusions, and revolutions. Where possible, always work in the lowest possible dimension, 1D lines before 2D sketches before 3D parts. The following guide will get you started: @@ -18,8 +18,8 @@ get you started: Step 1. Examine the Part in All Three Orientations ************************************************** -Start by visualizing the part from the front, top, and side views. Identify any symmetries -in these orientations, as symmetries can simplify the design by reducing the number of +Start by visualizing the part from the front, top, and side views. Identify any symmetries +in these orientations, as symmetries can simplify the design by reducing the number of unique features you need to model. *In the following view of the bracket one can see two planes of symmetry @@ -31,8 +31,8 @@ so we'll only need to design one quarter of it.* Step 2. Identify Rotational Symmetries ************************************** -Look for structures that could be created through the rotation of a 2D shape. For instance, -cylindrical or spherical features are often the result of revolving a profile around an axis. +Look for structures that could be created through the rotation of a 2D shape. For instance, +cylindrical or spherical features are often the result of revolving a profile around an axis. Identify the axis of rotation and make a note of it. *There are no rotational structures in the example bracket.* @@ -40,17 +40,17 @@ Identify the axis of rotation and make a note of it. Step 3. Select a Convenient Origin ********************************** -Choose an origin point that minimizes the need to move or transform components later in the -design process. Ideally, the origin should be placed at a natural center of symmetry or a +Choose an origin point that minimizes the need to move or transform components later in the +design process. Ideally, the origin should be placed at a natural center of symmetry or a critical reference point on the part. -*The planes of symmetry for the bracket was identified in step 1, making it logical to -place the origin at the intersection of these planes on the bracket's front face. Additionally, -we'll define the coordinate system we'll be working in: Plane.XY (the default), where -the origin is set at the global (0,0,0) position. In this system, the x-axis aligns with -the front of the bracket, and the z-axis corresponds to its width. It’s important to note +*The planes of symmetry for the bracket was identified in step 1, making it logical to +place the origin at the intersection of these planes on the bracket's front face. Additionally, +we'll define the coordinate system we'll be working in: Plane.XY (the default), where +the origin is set at the global (0,0,0) position. In this system, the x-axis aligns with +the front of the bracket, and the z-axis corresponds to its width. It’s important to note that all coordinate systems/planes in build123d adhere to the* -`right-hand rule `_ *meaning the y-axis is +`right-hand rule `_ *meaning the y-axis is automatically determined by this convention.* .. image:: assets/bracket_with_origin.png @@ -58,18 +58,18 @@ automatically determined by this convention.* Step 4. Create 2D Profiles ************************** -Design the 2D profiles of your part in the appropriate orientation(s). These profiles are -the foundation of the part's geometry and can often represent cross-sections of the part. +Design the 2D profiles of your part in the appropriate orientation(s). These profiles are +the foundation of the part's geometry and can often represent cross-sections of the part. Mirror parts of profiles across any axes of symmetry identified earlier. *The 2D profile of the bracket is as follows:* .. image:: assets/bracket_sketch.png :align: center - + *The build123d code to generate this profile is as follows:* -.. code-block:: python +.. code-block:: build123d with BuildSketch() as sketch: with BuildLine() as profile: @@ -109,7 +109,7 @@ Use the resulting geometry as sub-parts if needed. *The next step in implementing our design in build123d is to convert the above sketch into a part by extruding it as shown in this code:* -.. code-block:: python +.. code-block:: build123d with BuildPart() as bracket: with BuildSketch() as sketch: @@ -156,7 +156,7 @@ ensure the correct edges have been modified. define these corners need to be isolated. The following code, placed to follow the previous code block, captures just these edges:* -.. code-block:: python +.. code-block:: build123d corners = bracket.edges().filter_by(Axis.X).group_by(Axis.Y)[-1] fillet(corners, fillet_radius) @@ -191,7 +191,7 @@ and functionality in the final assembly. *Our example has two circular holes and a slot that need to be created. First we'll create the two circular holes:* -.. code-block:: python +.. code-block:: build123d with Locations(bracket.faces().sort_by(Axis.X)[-1]): Hole(hole_diameter / 2) @@ -219,7 +219,7 @@ the two circular holes:* *Next the slot needs to be created in the bracket with will be done by sketching a slot on the front of the bracket and extruding the sketch through the part.* -.. code-block:: python +.. code-block:: build123d with BuildSketch(bracket.faces().sort_by(Axis.Y)[0]): SlotOverall(20 * MM, hole_diameter) @@ -262,7 +262,7 @@ or if variations of the part are needed. *The dimensions of the bracket are defined as follows:* -.. code-block:: python +.. code-block:: build123d thickness = 3 * MM width = 25 * MM @@ -285,7 +285,7 @@ These steps should guide you through a logical and efficient workflow in build12 *The entire code block for the bracket example is shown here:* -.. code-block:: python +.. code-block:: build123d from build123d import * from ocp_vscode import show_all diff --git a/docs/tutorial_joints.rst b/docs/tutorial_joints.rst index 47a4026..d7c7658 100644 --- a/docs/tutorial_joints.rst +++ b/docs/tutorial_joints.rst @@ -19,6 +19,7 @@ Before getting to the CAD operations, this selector script needs to import the b environment. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [import] :end-before: [Hinge Class] @@ -32,6 +33,7 @@ tutorial is the joints and not the CAD operations to create objects, this code i described in detail. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Hinge Class] :end-before: [Create the Joints] @@ -62,6 +64,7 @@ The first joint to add is a :class:`~topology.RigidJoint` that is used to fix th or lid. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Create the Joints] :end-before: [Hinge Axis] @@ -78,6 +81,7 @@ The second joint to add is either a :class:`~topology.RigidJoint` (on the inner (on the outer leaf) that describes the hinge axis. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Create the Joints] :end-before: [Fastener holes] :emphasize-lines: 10-24 @@ -96,6 +100,7 @@ The third set of joints to add are :class:`~topology.CylindricalJoint`'s that de screws used to attach the leaves move. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Fastener holes] :end-before: [End Fastener holes] @@ -115,6 +120,7 @@ Step 3d: Call Super To finish off, the base class for the Hinge class is initialized: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [End Fastener holes] :end-before: [Hinge Class] @@ -125,6 +131,7 @@ Now that the Hinge class is complete it can be used to instantiate the two hinge required to attach the box and lid together. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Create instances of the two leaves of the hinge] :end-before: [Create the box with a RigidJoint to mount the hinge] @@ -139,6 +146,7 @@ the joint used to attach the outer hinge leaf. :align: center .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Create the box with a RigidJoint to mount the hinge] :end-before: [Demonstrate that objects with Joints can be moved and the joints follow] :emphasize-lines: 13-16 @@ -157,6 +165,7 @@ having to recreate or modify :class:`~topology.Joint`'s. Here is the box is move property. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Demonstrate that objects with Joints can be moved and the joints follow] :end-before: [The lid with a RigidJoint for the hinge] @@ -170,6 +179,7 @@ Much like the box, the lid is created in a :class:`~build_part.BuildPart` contex :align: center .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [The lid with a RigidJoint for the hinge] :end-before: [A screw to attach the hinge to the box] :emphasize-lines: 6-9 @@ -191,6 +201,7 @@ screw. :align: center .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [A screw to attach the hinge to the box] :end-before: [End of screw creation] @@ -210,6 +221,7 @@ Step 7a: Hinge to Box To start, the outer hinge leaf will be connected to the box, as follows: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Connect Box to Outer Hinge] :end-before: [Connect Box to Outer Hinge] @@ -227,6 +239,7 @@ Next, the hinge inner leaf is connected to the hinge outer leaf which is attache box. .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Connect Hinge Leaves] :end-before: [Connect Hinge Leaves] @@ -243,6 +256,7 @@ Step 7c: Lid to Hinge Now the ``lid`` is connected to the ``hinge_inner``: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Connect Hinge to Lid] :end-before: [Connect Hinge to Lid] @@ -260,6 +274,7 @@ Step 7d: Screw to Hinge The last step in this example is to place a screw in one of the hinges: .. literalinclude:: tutorial_joints.py + :language: build123d :start-after: [Connect Screw to Hole] :end-before: [Connect Screw to Hole] diff --git a/docs/tutorial_lego.rst b/docs/tutorial_lego.rst index 0ac2ab4..fdd02de 100644 --- a/docs/tutorial_lego.rst +++ b/docs/tutorial_lego.rst @@ -21,6 +21,7 @@ The dimensions of the Lego block follow. A key parameter is ``pip_count``, the l of the Lego blocks in pips. This parameter must be at least 2. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 30,31, 34-47 ******************** @@ -31,6 +32,7 @@ The Lego block will be created by the ``BuildPart`` builder as it's a discrete t dimensional part; therefore, we'll instantiate a ``BuildPart`` with the name ``lego``. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49 ********************** @@ -43,6 +45,7 @@ object. As this sketch will be part of the lego part, we'll create a sketch bui in the context of the part builder as follows: .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-51 :emphasize-lines: 3 @@ -59,6 +62,7 @@ of the Lego block. The following step is going to refer to this rectangle, so it be assigned the identifier ``perimeter``. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53 :emphasize-lines: 5 @@ -76,6 +80,7 @@ hollowed out. This will be done with the ``Offset`` operation which is going to create a new object from ``perimeter``. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64 :emphasize-lines: 7-12 @@ -104,6 +109,7 @@ objects are in the scope of a location context (``GridLocations`` in this case) that defined multiple points, multiple rectangles are created. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64,69-73 :emphasize-lines: 13-17 @@ -125,6 +131,7 @@ To convert the internal grid to ridges, the center needs to be removed. This wil with another ``Rectangle``. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64,69-73,78-83 :emphasize-lines: 18-23 @@ -142,6 +149,7 @@ Lego blocks use a set of internal hollow cylinders that the pips push against to hold two blocks together. These will be created with ``Circle``. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64,69-73,78-83,88-93 :emphasize-lines: 24-29 @@ -162,6 +170,7 @@ Now that the sketch is complete it needs to be extruded into the three dimension wall object. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64,69-73,78-83,88-93,98-99 :emphasize-lines: 30-31 @@ -183,6 +192,7 @@ Now that the walls are complete, the top of the block needs to be added. Althoug could be done with another sketch, we'll add a box to the top of the walls. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64,69-73,78-83,88-93,98-99,110-118 :emphasize-lines: 32-40 @@ -211,6 +221,7 @@ The final step is to add the pips to the top of the Lego block. To do this we'll a new workplane on top of the block where we can position the pips. .. literalinclude:: ../examples/lego.py + :language: build123d :lines: 49-53,58-64,69-73,78-83,88-93,98-99,110-118,129-137 :emphasize-lines: 41-49 diff --git a/docs/tutorial_selectors.rst b/docs/tutorial_selectors.rst index ed974f1..f0ee8db 100644 --- a/docs/tutorial_selectors.rst +++ b/docs/tutorial_selectors.rst @@ -11,7 +11,7 @@ this part: .. note:: One can see any object in the following tutorial by using the ``ocp_vscode`` (or any other supported viewer) by using the ``show(object_to_be_viewed)`` command. - Alternatively, the ``show_all()`` command will display all objects that have been + Alternatively, the ``show_all()`` command will display all objects that have been assigned an identifier. ************* @@ -22,6 +22,7 @@ Before getting to the CAD operations, this selector script needs to import the b environment. .. literalinclude:: selector_example.py + :language: build123d :start-after: [Code] :end-before: [End] :lines: 1-2 @@ -34,6 +35,7 @@ To start off, the part will be based on a cylinder so we'll use the :class:`~obj of :class:`~build_part.BuildPart`: .. literalinclude:: selector_example.py + :language: build123d :start-after: [Code] :end-before: [End] :lines: 1-5 @@ -50,6 +52,7 @@ surfaces) , so we'll create a sketch centered on the top of the cylinder. To lo this sketch we'll use the cylinder's top Face as shown here: .. literalinclude:: selector_example.py + :language: build123d :start-after: [Code] :end-before: [End] :lines: 1-6 @@ -82,6 +85,7 @@ The object has a hexagonal hole in the top with a central cylinder which we'll d in the sketch. .. literalinclude:: selector_example.py + :language: build123d :start-after: [Code] :end-before: [End] :lines: 1-8 @@ -107,6 +111,7 @@ To create the hole we'll :func:`~operations_part.extrude` the sketch we just cre the :class:`~objects_part.Cylinder` and subtract it. .. literalinclude:: selector_example.py + :language: build123d :start-after: [Code] :end-before: [End] :lines: 1-9 @@ -128,6 +133,7 @@ Step 6: Fillet the top perimeter Edge The final step is to apply a fillet to the top perimeter. .. literalinclude:: selector_example.py + :language: build123d :start-after: [Code] :end-before: [End] :lines: 1-9,18-24,33-34 diff --git a/docs/tutorial_spitfire_wing_gordon.rst b/docs/tutorial_spitfire_wing_gordon.rst index 716f862..18dd1f2 100644 --- a/docs/tutorial_spitfire_wing_gordon.rst +++ b/docs/tutorial_spitfire_wing_gordon.rst @@ -34,6 +34,7 @@ We model a single wing (half‑span), with an elliptic leading and trailing edge These two edges act as the *guides* for the Gordon surface. .. literalinclude:: spitfire_wing_gordon.py + :language: build123d :start-after: [Code] :end-before: [AirfoilSizes] @@ -45,6 +46,7 @@ We intersect the guides with planes normal to the span to size the airfoil secti The resulting chord lengths define uniform scales for each airfoil curve. .. literalinclude:: spitfire_wing_gordon.py + :language: build123d :start-after: [AirfoilSizes] :end-before: [Airfoils] @@ -56,6 +58,7 @@ shifted so the leading edge fraction is aligned—then scale to the chord length from Step 2. .. literalinclude:: spitfire_wing_gordon.py + :language: build123d :start-after: [Airfoils] :end-before: [Profiles] @@ -68,6 +71,7 @@ profiles; the elliptic edges are the guides. We also add the wing tip section so the profile grid closes at the tip. .. literalinclude:: spitfire_wing_gordon.py + :language: build123d :start-after: [Profiles] :end-before: [Solid] @@ -82,6 +86,7 @@ Step 5 — Cap the root and create the solid We extract the closed root edge loop, make a planar cap, and form a solid shell. .. literalinclude:: spitfire_wing_gordon.py + :language: build123d :start-after: [Solid] :end-before: [End] @@ -102,5 +107,6 @@ Complete listing For convenience, here is the full script in one block: .. literalinclude:: spitfire_wing_gordon.py + :language: build123d :start-after: [Code] :end-before: [End] diff --git a/docs/tutorial_surface_heart_token.rst b/docs/tutorial_surface_heart_token.rst index 2c45f62..ac819ad 100644 --- a/docs/tutorial_surface_heart_token.rst +++ b/docs/tutorial_surface_heart_token.rst @@ -7,9 +7,9 @@ a heart‑shaped token from a small set of non‑planar faces. We’ll create non‑planar surfaces, mirror them, add side faces, and assemble a closed shell into a solid. -As described in the `topology_` section, a BREP model consists of vertices, edges, faces, -and other elements that define the boundary of an object. When creating objects with -non-planar faces, it is often more convenient to explicitly create the boundary faces of +As described in the `topology_` section, a BREP model consists of vertices, edges, faces, +and other elements that define the boundary of an object. When creating objects with +non-planar faces, it is often more convenient to explicitly create the boundary faces of the object. To illustrate this process, we will create the following game token: .. raw:: html @@ -22,13 +22,14 @@ Useful :class:`~topology.Face` creation methods include and :meth:`~topology.Face.make_surface_from_array_of_points`. See the :doc:`surface_modeling` overview for the full list. -In this case, we'll use the ``make_surface`` method, providing it with the edges that define +In this case, we'll use the ``make_surface`` method, providing it with the edges that define the perimeter of the surface and a central point on that surface. -To create the perimeter, we'll define the perimeter edges. Since the heart is +To create the perimeter, we'll define the perimeter edges. Since the heart is symmetric, we'll only create half of its surface here: .. literalinclude:: heart_token.py + :language: build123d :start-after: [Code] :end-before: [SurfaceEdges] @@ -42,12 +43,14 @@ of the heart and archs up off ``Plane.XY``. In preparation for creating the surface, we'll define a point on the surface: .. literalinclude:: heart_token.py + :language: build123d :start-after: [SurfaceEdges] :end-before: [SurfacePoint] We will then use this point to create a non-planar ``Face``: .. literalinclude:: heart_token.py + :language: build123d :start-after: [SurfacePoint] :end-before: [Surface] @@ -55,21 +58,23 @@ We will then use this point to create a non-planar ``Face``: :align: center :alt: token perimeter -Note that the surface was raised up by 0.5 using an Algebra expression with Pos. Also, -note that the ``-`` in front of ``Face`` simply flips the face normal so that the colored +Note that the surface was raised up by 0.5 using an Algebra expression with Pos. Also, +note that the ``-`` in front of ``Face`` simply flips the face normal so that the colored side is up, which isn't necessary but helps with viewing. -Now that one half of the top of the heart has been created, the remainder of the top +Now that one half of the top of the heart has been created, the remainder of the top and bottom can be created by mirroring: .. literalinclude:: heart_token.py + :language: build123d :start-after: [Surface] :end-before: [Surfaces] -The sides of the heart are going to be created by extruding the outside of the perimeter +The sides of the heart are going to be created by extruding the outside of the perimeter as follows: .. literalinclude:: heart_token.py + :language: build123d :start-after: [Surfaces] :end-before: [Sides] @@ -77,11 +82,12 @@ as follows: :align: center :alt: token sides -With the top, bottom, and sides, the complete boundary of the object is defined. We can -now put them together, first into a :class:`~topology.Shell` and then into a +With the top, bottom, and sides, the complete boundary of the object is defined. We can +now put them together, first into a :class:`~topology.Shell` and then into a :class:`~topology.Solid`: .. literalinclude:: heart_token.py + :language: build123d :start-after: [Sides] :end-before: [Solid] @@ -90,32 +96,33 @@ now put them together, first into a :class:`~topology.Shell` and then into a :alt: token heart solid .. note:: - When creating a Solid from a Shell, the Shell must be "water-tight," meaning it - should have no holes. For objects with complex Edges, it's best practice to reuse - Edges in adjoining Faces whenever possible to avoid slight mismatches that can + When creating a Solid from a Shell, the Shell must be "water-tight," meaning it + should have no holes. For objects with complex Edges, it's best practice to reuse + Edges in adjoining Faces whenever possible to avoid slight mismatches that can create openings. -Finally, we'll create the frame around the heart as a simple extrusion of a planar +Finally, we'll create the frame around the heart as a simple extrusion of a planar shape defined by the perimeter of the heart and merge all of the components together: .. literalinclude:: heart_token.py + :language: build123d :start-after: [Solid] :end-before: [End] -Note that an additional planar line is used to close ``l1`` and ``l3`` so a ``Face`` -can be created. The :func:`~operations_generic.offset` function defines the outside of +Note that an additional planar line is used to close ``l1`` and ``l3`` so a ``Face`` +can be created. The :func:`~operations_generic.offset` function defines the outside of the frame as a constant distance from the heart itself. Summary ------- -In this tutorial, we've explored surface modeling techniques to create a non-planar +In this tutorial, we've explored surface modeling techniques to create a non-planar heart-shaped object using build123d. By utilizing methods from the :class:`~topology.Face` -class, such as :meth:`~topology.Face.make_surface`, we constructed the perimeter and -central point of the surface. We then assembled the complete boundary of the object -by creating the top, bottom, and sides, and combined them into a :class:`~topology.Shell` -and eventually a :class:`~topology.Solid`. Finally, we added a frame around the heart -using the :func:`~operations_generic.offset` function to maintain a constant distance +class, such as :meth:`~topology.Face.make_surface`, we constructed the perimeter and +central point of the surface. We then assembled the complete boundary of the object +by creating the top, bottom, and sides, and combined them into a :class:`~topology.Shell` +and eventually a :class:`~topology.Solid`. Finally, we added a frame around the heart +using the :func:`~operations_generic.offset` function to maintain a constant distance from the heart. Next steps diff --git a/docs/tutorial_surface_modeling.rst b/docs/tutorial_surface_modeling.rst index 4d8fca0..afa7f82 100644 --- a/docs/tutorial_surface_modeling.rst +++ b/docs/tutorial_surface_modeling.rst @@ -3,28 +3,28 @@ Surface Modeling ################# -Surface modeling refers to the direct creation and manipulation of the skin of a 3D -object—its bounding faces—rather than starting from volumetric primitives or solid +Surface modeling refers to the direct creation and manipulation of the skin of a 3D +object—its bounding faces—rather than starting from volumetric primitives or solid operations. -Instead of defining a shape by extruding or revolving a 2D profile to fill a volume, -surface modeling focuses on building the individual curved or planar faces that together -define the outer boundary of a part. This approach allows for precise control of complex -freeform geometry such as aerodynamic surfaces, boat hulls, or organic transitions that +Instead of defining a shape by extruding or revolving a 2D profile to fill a volume, +surface modeling focuses on building the individual curved or planar faces that together +define the outer boundary of a part. This approach allows for precise control of complex +freeform geometry such as aerodynamic surfaces, boat hulls, or organic transitions that cannot easily be expressed with simple parametric solids. -In build123d, as in other CAD kernels based on BREP (Boundary Representation) modeling, -all solids are ultimately defined by their boundaries: a hierarchy of faces, edges, and -vertices. Each face represents a finite patch of a geometric surface (plane, cylinder, -Bézier patch, etc.) bounded by one or more edge loops or wires. When adjacent faces share -edges consistently and close into a continuous boundary, they form a manifold -:class:`~topology.Shell`—the watertight surface of a volume. If this shell is properly +In build123d, as in other CAD kernels based on BREP (Boundary Representation) modeling, +all solids are ultimately defined by their boundaries: a hierarchy of faces, edges, and +vertices. Each face represents a finite patch of a geometric surface (plane, cylinder, +Bézier patch, etc.) bounded by one or more edge loops or wires. When adjacent faces share +edges consistently and close into a continuous boundary, they form a manifold +:class:`~topology.Shell`—the watertight surface of a volume. If this shell is properly oriented and encloses a finite region of space, the model becomes a solid. -Surface modeling therefore operates at the most fundamental level of BREP construction. -Rather than relying on higher-level modeling operations to implicitly generate faces, -it allows you to construct and connect those faces explicitly. This provides a path to -build geometry that blends analytical and freeform shapes seamlessly, with full control +Surface modeling therefore operates at the most fundamental level of BREP construction. +Rather than relying on higher-level modeling operations to implicitly generate faces, +it allows you to construct and connect those faces explicitly. This provides a path to +build geometry that blends analytical and freeform shapes seamlessly, with full control over continuity, tangency, and curvature across boundaries. This section provides: