Location implementation and CQ typing

[adam-urbanczyk]

This is related to #118 and #247. I think it will be a solid basis for further extending of CQ.

• Wrap TopLoc_Location
• Annotate cq.py
• Rework eachpoint and related methods
• Update docs
• Do not add the origin of workplane to objects, handle in eachpoint and val. This makes using add more intuitive.

[adam-urbanczyk]

@jmwright @dcowden I did more or less finish annotating cq.py and it turns out that the code is not self-consistent anymore. CQ and Workplane classes are intermixed - sometimes CQ is assuming it is actually a Workplane. Although it is fixable, fixing it would break backward-compatibility. I think it would be best to just merge CQ and Workplane into one class (Workplane) and provide an alias 'CQ` for backward compatibility. Do you agree with such an approach?

The other thing I changed (for better I hope) is the eachpoint and related methods. They are now using the new Location class (which can represent rotations as well as translations). It has implications for people writing their own plugins (maybe it'd impact you @michaelgale ).

All in all I think it is worth it, although slightly breaking.

[codecov]

Codecov Report

Merging #380 into master will increase coverage by 0.10%.
The diff coverage is 94.69%.

@@            Coverage Diff             @@
##           master     #380      +/-   ##
==========================================
+ Coverage   93.31%   93.42%   +0.10%     
==========================================
  Files          19       19              
  Lines        4847     4925      +78     
  Branches      483      510      +27     
==========================================
+ Hits         4523     4601      +78     
+ Misses        210      204       -6     
- Partials      114      120       +6     

Impacted Files	Coverage Δ
cadquery/cq.py	87.45% <93.10%> (+0.04%)	⬆️
cadquery/occ_impl/geom.py	88.78% <97.91%> (+1.06%)	⬆️
cadquery/__init__.py	100.00% <100.00%> (ø)
cadquery/occ_impl/shapes.py	90.34% <100.00%> (+0.18%)	⬆️
cadquery/utils.py	100.00% <100.00%> (ø)
tests/test_cad_objects.py	98.97% <100.00%> (+0.02%)	⬆️
tests/test_cadquery.py	98.92% <100.00%> (+<0.01%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 56046ef...69a3936. Read the comment docs.

[jmwright]

...and it turns out that the code is not self-consistent anymore. CQ and Workplane classes are intermixed...

@adam-urbanczyk When you say "anymore", are you saying that the process of annotation caused this problem?

Although it is fixable, fixing it would break backward-compatibility. I think it would be best to just merge CQ and Workplane into one class (Workplane) and provide an alias 'CQ` for backward compatibility. Do you agree with such an approach?

Changing something so fundamental in the core of CQ makes me nervous. Are you saying the CQ alias prevent will prevent breakage of all existing scripts, or just some of them?

[adam-urbanczyk]

@jmwright I meant that somewhere along the way we ended up in the situation where methods of CQ call methods of Workplane. Probably at the beginning there was a nice design, but it was not enforced and a somewhat entangled situation materialized. We can either fix it (move methods around and break backward compatibility) or merge the two classes into one (which I did in this PR). Annotating+mypy check revealed the issue. I start to appreciate mypy more and more.

To be honest merging of CQ and Workplane did not feel fundamental at all - I deleted a couple of lines and merged the two __init__ methods. All tests just passed. I expect that all scripts will just work.

What did change is the way plugins need to be written - they need to accept Location instead of Vector. I could still add some logic inside eachpoint but I'd prefer to keep things clean. Take a look what changed in the tests.

[adam-urbanczyk]

To be more specific, here is an example of the entanglement I was referring to above:

cadquery/cadquery/cq.py

Line 169 in f522899

topCutBox = self.rect(maxDim, maxDim)._extrude(maxDim)

CQ.split calls self.rect which is not defined in the class CQ.

[jmwright]

I see now. It doesn't sound like as much of a breaking change as I expected. It would be nice to hear from someone who uses the plugin system about those changes.

[adam-urbanczyk]

Absolutely @jmwright , I'm curious though if such a person exists.

An alternative approach would be to add another method, say eachloc, and deprecate eachpoint while keeping the old implementation. I'm very much open for discussion but I also think that we need to start moving forward if there are good reasons to do so. Current approach for representing locations (translation based) is extremely limiting and does not facilitate solving of #118 in a nice way. I'd like to work on sketches and (simple) assemblies in the near future and having TopLoc_Location will be extremely handy in that context.

[jmwright]

I'm curious though if such a person exists.

Maybe not. I know that we have pointed some people to plugins over the years, but I don't know how many are using it. I do know that a couple of spots in our codebase were designed to test the plugin functionality.

cadquery/tests/test_cadquery.py

Line 118 in f9fe7b1

def testCubePlugin(self):

If the tests like that work, we're probably ok.

[michaelgale]

The changes to eachPoint etc. and the introduction of the Location class do not appear to impact my code built around CQ. I am curious about the Location class as a wrapper for TopLoc_Location--is this intended for use internally within the CQ API or does it have some benefits for user code as well? More broadly, the geom.py module has some good utility functions that I accidentally implemented myself since I only discovered its functionality later. Often I find that I need to do some quick (and often trivial and repetitive) computation on things like points and rectangles--it would be nice if these convenience geometry functions could be baked into geom.py. The number of times I type x + w/2, x - w/2 etc. or simply want to query coordinate min, max, mid, etc. is so numerous. It would be nice to quickly compute a point rotated by an offset angle or the bounds of a rectangle shifted by some offset (or rotated) etc. Just a thought.

[adam-urbanczyk]

@michaelgale I'd like to start using Location (TopLoc_Location wrapper) to represent location in future developments of CQ. It is used in the kernel to represent [relative] position (see e.g. Locate, Located, Move, Moved methods of TopoDD_Shape), so I think it is the right approach. First natural application would be to use it in assemblies. I'd like to start with implementing a container that maps well to the STEP exporter in OCCT and then add a constraint solver.

[adam-urbanczyk]

I think I'm happy with this PR. We can let it sink in for a couple of days, maybe some user of the plugin system will still show up here.

I'd still like to annotate the Shapes.py file as well. But I'll start another PR for that.

[jmwright]

+1 for merging on the 25th if there are no issues brought up by the community.

[adam-urbanczyk]

There seem to be no complaints, so I'd propose to move forward with this.

[jmwright]

@adam-urbanczyk I see there's now a merge conflict.

[adam-urbanczyk]

Resolved.

[jmwright]

Thanks for putting this together.

[adam-urbanczyk]

I think everything is fixed @jmwright

[jmwright]

Great, thanks for all the work you've put into this! Merging.

[maderero]

I see now. It doesn't sound like as much of a breaking change as I expected. It would be nice to hear from someone who uses the plugin system about those changes.

I'm a few weeks late, but I just want to report that while the changes did initially break my plugins, it did not take long to implement a fix once I took a look at the changes.

[adam-urbanczyk]

Good to hear @maderero ! Are you planning to share your code? It is always interesting to see what people are doing with CQ.

[maderero]

Good to hear @maderero ! Are you planning to share your code? It is always interesting to see what people are doing with CQ.

At some point I could share the plugins, which are essentially shortcuts to make common structural steel shapes .

Here's a sample of some wide-flange beams in the cq-editor window.

[adam-urbanczyk]

Cool @maderero , thanks for sharing! BTW: you might be interested in the importers.importDXF function.

[maderero]

I'm glad you like it, @adam-urbanczyk! I will keep that function in mind as well.