Implement subtractive features

[dcowden]

Issue by adam-urbanczyk
Monday May 21, 2018 at 10:28 GMT
Originally opened as dcowden/cadquery#269

---

For now only additive features are implemented. If we need to make a subtractive feature two additional calls are needed (combine=False and an explicit cut op)

obj = cq.Workplane('XY').circle(dia_out).circle(dia_in).extrude(tube_h)
groove= obj.faces('<Z').workplane(offset=-3.0).circle(dia_out).\
    circle(dia_out-groove_depth).extrude(groove_h,combine=False)

result = obj.cut(groove)

What would be nice:

result = cq.Workplane('XY').circle(dia_out).circle(dia_in).extrude(tube_h).\
    faces('<Z').workplane(offset=-3.0).circle(dia_out).\
    circle(dia_out-groove_depth).extrude(groove_h,subtract=True)

[dcowden]

Comment by dcowden
Monday May 21, 2018 at 13:12 GMT

---

cutBlind, cutThruAll perform cuts using a sketch or wires, and avoids the extra step.

[dcowden]

Comment by adam-urbanczyk
Tuesday May 29, 2018 at 17:59 GMT

---

Would you mind having the optional subtract kw arg? Also for other ops like revolve, loft or sweep?

[dcowden]

Comment by dcowden
Tuesday May 29, 2018 at 19:00 GMT

---

I definitely wouldn't mind, wouldnt hurt anything.

My main reservation is that we've come 'under fire' recently for the use of kw args-- novice users complain that they are hard to figure out and generally not obvious that they are there. IE, i think novice users would most likely never know it's an option.

That's not an argument against the new argument, as much as that we generally have to figure out how to make the functions more self-describing. But i have no idea how to do that, because a lot of our operations do have lots of choices

[pavpen]

If I may add an opinion, I also find that adding extra keyword arguments to modify the operation of a function are harder to read, document, and, often, also test.

From a design standpoint it mixes the parameters for an operation (such as extrude, which needs to know, e.g., what wire to extrude, and how far to extrude it) with parameters for modifying an operation (such as taking an arbitrary operation that produces a solid, and subtracting the solid from, rather than adding it to, the existing workplane solid).

I think the code is cleaner, and more maintainable, and easier to read and document, if these two concerns are separated. There are several ways to do this. E.g.:

• Have separate method names for additive and for subtractive operations. (This may follow the existing pattern of cutBlind and cutThruAll for subtraction vs. extrude for addition.)
• Have a separate method that configures the modifications of the following operation in the fluent sequence. E.g.:

result = cq.Workplane('XY').circle(dia_out).circle(dia_in).extrude(tube_h).\
    subtractNext().faces('<Z').workplane(offset=-3.0).circle(dia_out).\
    circle(dia_out-groove_depth).extrude(groove_h)

Although, this looks less readable to me than the code you're trying to replace:

obj = cq.Workplane('XY').circle(dia_out).circle(dia_in).extrude(tube_h)
groove= obj.faces('<Z').workplane(offset=-3.0).circle(dia_out).\
    circle(dia_out-groove_depth).extrude(groove_h,combine=False)

result = obj.cut(groove)

In the latter code it's easier to tell there's a subtraction, and what is being subtracting from what. In the fluent code, you have to stare at each part of the expression to notice there's a subtraction somewhere in the sequence, and, then, you have to figure out which part of the sequence is constructing the minuend and which is constructing the subtrahend.

I think one of the common ways to create blocks in fluent APIs is to use lambdas, which in Python would look something like:

result = cq.Workplane('XY').circle(dia_out).circle(dia_in).extrude(tube_h).\
    subtract(
        lambda workplane: \
            workplane.faces('<Z').workplane(offset=-3.0).circle(dia_out).\
                circle(dia_out-groove_depth).extrude(groove_h)
    )

This takes more lines than the original code, but is not than bad on readability.

[adam-urbanczyk]

Thanks for the discussion, but -100 on the subtractNext idea. This looks unreadable, complicates things an makes cq.Workplane even more stateful.

I don't agree with the statement the keyword arguments are somehow sub-optimal. I'm a user of unrelated packages like Pandas and Seaborn and their API feels very ergonomic and natural. Note that w already have the combine keyword so the idea could be to extend accepted values and allow something like:

result = (
    cq.Workplane()
    .circle(dia_out).circle(dia_in)
    .extrude(tube_h).
    .faces('<Z').workplane(offset=-3.0)
    .circle(dia_out).circle(dia_out-groove_depth)
    .extrude(groove_h, combine="cut")
)

This fits nicely in the current CQ API and will not require a lot of code changes.

[Jojain]

Even though I think it is less obvious for the new comer to have the reverse operation available as a parameter of an extrusion operation I like the idea of adding combine="cut" to all protusion (or matter building) methods as it would make it very coherent through all the code base.

If we agree on this solution here are two concerns :

• Some methods are getting more and more possibles arguments cf untilNextFace and untilLastFace for extrude and cutblind #782 and the source code become less and less clear, however there is a possibility of splitting API methods into hierarchical calls likes it's done in extrude with _extrude. This could be discussed and standardized ?
• Are we going to deprecate methods like cutBlind and cutThruAll ? My opinion is that we should remove them in the long run as it would make the codebase more coherent.

[alikureishy]

I'm a new user, so this comment is certainly not authoritative, but I do have a concern. I find the combine="cut" option a slippery slope to go down, because the original parameter is a boolean type (combine=True/False). I understand it is common to have different value types for a given parameter, but in the case where the value types are semantically different, it could make the API harder to follow/remember.

[adam-urbanczyk]

They wouldn't be semantically different - they'd specify how the result is combined with the base solid.

[adam-urbanczyk]

Solved in #954