diff --git a/docs/assets/card_box.svg b/docs/assets/card_box.svg new file mode 100644 index 0000000..8e0cd51 --- /dev/null +++ b/docs/assets/card_box.svg @@ -0,0 +1,125 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + \ No newline at end of file diff --git a/docs/objects.rst b/docs/objects.rst index 1860c54..3995098 100644 --- a/docs/objects.rst +++ b/docs/objects.rst @@ -363,6 +363,43 @@ Reference Wedge defined by lengths along multiple Axes +Custom Objects +-------------- + +All of the objects presented above were created using one of three base object classes: +:class:`~objects_curve.BaseLineObject` , :class:`~objects_sketch.BaseSketchObject` , and +:class:`~objects_part.BasePartObject` . Users can use these base object classes to +easily create custom objects that have all the functionality of the core objects. + +.. image:: assets/card_box.svg + :align: center + +Here is an example of a custom sketch object specially created as part of the design of +this playing card storage box (:download:`see the playing_cards.py example <../examples/playing_cards.py>`): + +.. literalinclude:: ../examples/playing_cards.py + :start-after: [Club] + :end-before: [Club] + +Here the new custom object class is called ``Club`` and it's a sub-class of +:class:`~objects_sketch.BaseSketchObject` . The ``__init__`` method contains all +of the parameters used to instantiate the custom object, specially a ``height``, +``rotation``, ``align``, and ``mode`` - your objects may contain a sub or super set of +these parameters but should always contain a ``mode`` parameter such that it +can be combined with a builder's object. + +Next is the creation of the object itself, in this case a sketch of the club suit. + +The final line calls the ``__init__`` method of the super class - i.e. +:class:`~objects_sketch.BaseSketchObject` with its parameters. + +That's it, now the ``Club`` object can be used anywhere a :class:`~objects_sketch.Circle` +would be used - with either the Algebra or Builder API. + +.. image:: assets/buildline_example_6.svg + :align: center + + Reference ^^^^^^^^^ .. py:module:: objects_part diff --git a/examples/playing_cards.py b/examples/playing_cards.py index 3366c16..d80e848 100644 --- a/examples/playing_cards.py +++ b/examples/playing_cards.py @@ -28,6 +28,7 @@ from typing import Literal from build123d import * +# [Club] class Club(BaseSketchObject): def __init__( self, @@ -36,7 +37,7 @@ class Club(BaseSketchObject): align: tuple[Align, Align] = (Align.CENTER, Align.CENTER), mode: Mode = Mode.ADD, ): - with BuildSketch(mode=Mode.PRIVATE) as club: + with BuildSketch() as club: with BuildLine(): l0 = Line((0, -188), (76, -188)) b0 = Bezier(l0 @ 1, (61, -185), (33, -173), (17, -81)) @@ -49,6 +50,9 @@ class Club(BaseSketchObject): super().__init__(obj=club.sketch, rotation=rotation, align=align, mode=mode) +# [Club] + + class Spade(BaseSketchObject): def __init__( self, @@ -57,7 +61,7 @@ class Spade(BaseSketchObject): align: tuple[Align, Align] = (Align.CENTER, Align.CENTER), mode: Mode = Mode.ADD, ): - with BuildSketch(mode=Mode.PRIVATE) as spade: + with BuildSketch() as spade: with BuildLine(): b0 = Bezier((0, 198), (6, 190), (41, 127), (112, 61)) b1 = Bezier(b0 @ 1, (242, -72), (114, -168), (11, -105)) @@ -77,7 +81,7 @@ class Heart(BaseSketchObject): align: tuple[Align, Align] = (Align.CENTER, Align.CENTER), mode: Mode = Mode.ADD, ): - with BuildSketch(mode=Mode.PRIVATE) as heart: + with BuildSketch() as heart: with BuildLine(): b1 = Bezier((0, 146), (20, 169), (67, 198), (97, 198)) b2 = Bezier(b1 @ 1, (125, 198), (151, 186), (168, 167)) @@ -98,7 +102,7 @@ class Diamond(BaseSketchObject): align: tuple[Align, Align] = (Align.CENTER, Align.CENTER), mode: Mode = Mode.ADD, ): - with BuildSketch(mode=Mode.PRIVATE) as diamond: + with BuildSketch() as diamond: with BuildLine(): Bezier((135, 0), (94, 69), (47, 134), (0, 198)) mirror(about=Plane.XZ) @@ -152,6 +156,16 @@ with BuildPart() as lid_builder: Club(card_length / 5) extrude(amount=-wall, mode=Mode.SUBTRACT) +box = Compound.make_compound( + [box_builder.part, lid_builder.part.moved(Location((0, 0, (wall + deck) / 2)))] +) +box.export_svg( + "../docs/assets/card_box.svg", + (70, -50, 120), + (0, 0, 1), + svg_opts={"pixel_scale": 5, "show_axes": False, "show_hidden": False}, +) + class PlayingCard(Compound): """PlayingCard diff --git a/src/build123d/__init__.py b/src/build123d/__init__.py index fa908ef..82be558 100644 --- a/src/build123d/__init__.py +++ b/src/build123d/__init__.py @@ -49,6 +49,7 @@ __all__ = [ "BuildPart", "BuildSketch", # 1D Curve Objects + "BaseLineObject", "Bezier", "CenterArc", "EllipticalCenterArc",