From aba24c0ed5470512411e65402e48ec624ce1c07c Mon Sep 17 00:00:00 2001 From: Jojain <50221409+Jojain@users.noreply.github.com> Date: Sun, 31 Oct 2021 01:24:52 +0200 Subject: [PATCH] Added docs for new extrude capabilities (#894) * Added docs for new extrude capabilities Added examples for extrude and cutblind until extrusion parameter Updated weird leftover text in Example page * added note on relative axis coords for Workplane.revolve * added mixed extrude cutblind example --- cadquery/cq.py | 8 ++- doc/examples.rst | 131 ++++++++++++++++++++++++++++++++++++++++++++--- doc/roadmap.rst | 3 -- 3 files changed, 131 insertions(+), 11 deletions(-) diff --git a/cadquery/cq.py b/cadquery/cq.py index 6fb54c98..5d782350 100644 --- a/cadquery/cq.py +++ b/cadquery/cq.py @@ -2993,7 +2993,7 @@ class Workplane(object): to the normal of the plane. The string "next" extrudes until the next face orthogonal to the wire normal. "last" extrudes to the last face. If a object of type Face is passed then the extrusion will extend until this face. - :param boolean combine: True to combine the resulting solid with parent solids if found. + :param boolean combine: True to combine the resulting solid with parent solids if found. (Cannot be set to False when `until` is not set as a float) :param boolean clean: call :py:meth:`clean` afterwards to have a clean shape :param boolean both: extrude in both directions symmetrically :param float taper: angle for optional tapered extrusion @@ -3070,6 +3070,12 @@ class Workplane(object): * if combine is False, the new value is pushed onto the stack. * if combine is true, the value is combined with the context solid if it exists, and the resulting solid becomes the new context solid. + + .. note:: + Keep in mind that `axisStart` and `axisEnd` are defined relative to the current Workplane center position. + So if for example you want to revolve a circle centered at (10,0,0) around the Y axis, be sure to either :py:meth:`move` (or :py:meth:`moveTo`) + the current Workplane position or specify `axisStart` and `axisEnd` with the correct vector position. + In this example (0,0,0), (0,1,0) as axis coords would fail. """ # Make sure we account for users specifying angles larger than 360 degrees angleDegrees %= 360.0 diff --git a/doc/examples.rst b/doc/examples.rst index 0046c575..1d6a692c 100644 --- a/doc/examples.rst +++ b/doc/examples.rst @@ -13,20 +13,19 @@ They are organized from simple to complex, so working through them in order is t Each example lists the API elements used in the example for easy reference. Items introduced in the example are marked with a **!** -.. note:: - You may want to work through these examples by pasting the text into a code editor in a CadQuery . - If you do, make sure to take these steps so that they work: - - 1. paste the content into the build() method, properly indented, and - 2. add the line 'return result' at the end. The samples below are autogenerated, but they use a different - syntax than the models on the website need to be. .. note:: We strongly recommend installing `CQ-editor `_, so that you can work along with these examples interactively. See :ref:`installation` for more info. + If you do, make sure to take these steps so that they work: + + 1. import cadquery as cq + 2. add the line ``show_object(result)`` at the end. The samples below are autogenerated, but they use a different + syntax than the models on the website need to be. + .. warning:: * You have to have an svg capable browser to view these! @@ -622,6 +621,124 @@ and a circular section. * :py:meth:`Workplane.circle` * :py:meth:`Workplane.rect` +Extruding until a given face +-------------------------------------------- + +Sometimes you will want to extrude a wire until a given face that can be not planar or where you +might not know easily the distance you have to extrude to. In such cases you can use `next`, `last` +or even give a :class:`~cadquery.Face` object for the `until` argument of +:meth:`~cadquery.Workplane.extrude`. + + +.. cadquery:: + + result = (cq.Workplane(origin = (20,0,0)) + .circle(2) + .revolve(180, (-20,0,0),(-20,-1,0)) + .center(-20,0) + .workplane() + .rect(20,4) + .extrude("next") + ) + +The same behaviour is available with :meth:`~cadquery.Workplane.cutBlind` and as you can see it is +also possible to work on several :class:`~cadquery.Wire` objects at a time (the +same is true for :meth:`~cadquery.Workplane.extrude`). + +.. cadquery:: + + skycrappers_locations = [(-16,1),(-8,0),(7,0.2),(17,-1.2)] + angles = iter([15,0,-8,10]) + skycrappers = (cq.Workplane() + .pushPoints(skycrappers_locations) + .eachpoint(lambda loc: (cq.Workplane() + .rect(5,16) + .workplane(offset=10) + .ellipse(3,8) + .workplane(offset=10) + .slot2D(20,5, 90) + .loft() + .rotateAboutCenter((0,0,1),next(angles)) + .val().located(loc) + ) + ) + ) + + result = (skycrappers + .transformed((0,-90,0)) + .moveTo(15,0) + .rect(3,3, forConstruction=True) + .vertices() + .circle(1) + .cutBlind("last") + ) + +Here is a typical situation where extruding and cuting until a given surface is very handy. It allows us to extrude or cut until a curved surface without overlapping issues. + +.. cadquery:: + + import cadquery as cq + + sphere = cq.Workplane().sphere(5) + base = (cq.Workplane(origin=(0,0,-2)) + .box(12,12,10) + .cut(sphere) + .edges("|Z") + .fillet(2) + ) + sphere_face = base.faces(">>X[2] and (not |Z) and (not |Y)").val() + base = (base + .faces("X") + .workplane(centerOption="CenterOfMass") + .move(0,4) + .slot2D(10,2,90) + .cutBlind(sphere_face) + .workplane(offset=10) + .move(0,2) + .circle(0.9) + .extrude("next") + ) + + result = spherical_joint + +.. warning:: + + If the wire you want to extrude cannot be fully projected on the target surface, the result will + be unpredictable. Furthermore the algorithm in charge of finding the candidates faces do it's + search by counting all the faces intersected by a line created from your wire center along your + extrusion direction. So make sure your wire can be projected on your target face to avoid + unexpected behaviour. + +.. topic:: Api References + + .. hlist:: + :columns: 3 + + * :py:meth:`Workplane.cutBlind` **!** + * :py:meth:`Workplane.rect` + * :py:meth:`Workplane.ellipse` + * :py:meth:`Workplane.workplane` + * :py:meth:`Workplane.slot2D` + * :py:meth:`Workplane.loft` + * :py:meth:`Workplane.rotateAboutCenter` + * :py:meth:`Workplane.transformed` + * :py:meth:`Workplane.moveTo` + * :py:meth:`Workplane.circle` + + Making Counter-bored and Counter-sunk Holes ---------------------------------------------- diff --git a/doc/roadmap.rst b/doc/roadmap.rst index a1bc6cc2..7a57187a 100644 --- a/doc/roadmap.rst +++ b/doc/roadmap.rst @@ -83,6 +83,3 @@ primitive creation * cone * torus * wedge - -extrude/cut up to surface - allow a cut or extrude to terminate at another surface, rather than either through all or a fixed distance