Shape iterator improvements

[adam-urbanczyk]

Closes #1231 and #565

• adds an __iter__ method to Shape (specialized for Wire)
• ancestors iterator
• siblings iterator
• ancestors/siblings for workplane
• tests
• docs

[codecov]

Codecov Report

Merging #1376 (8429428) into master (e8d7447) will increase coverage by 0.06%.
Report is 4 commits behind head on master.
The diff coverage is 97.67%.

❗ Current head 8429428 differs from pull request most recent head 952722f. Consider uploading reports for the commit 952722f to get more accurate results

@@            Coverage Diff             @@
##           master    #1376      +/-   ##
==========================================
+ Coverage   94.13%   94.19%   +0.06%     
==========================================
  Files          27       27              
  Lines        5678     5740      +62     
  Branches      962      983      +21     
==========================================
+ Hits         5345     5407      +62     
  Misses        199      199              
  Partials      134      134              

Files Changed	Coverage Δ
cadquery/cq.py	92.32% <92.00%> (+0.08%)	⬆️
cadquery/occ_impl/exporters/dxf.py	97.41% <100.00%> (+0.19%)	⬆️
cadquery/occ_impl/shapes.py	93.07% <100.00%> (+0.22%)	⬆️
cadquery/sketch.py	95.85% <100.00%> (ø)

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

📢 Have feedback on the report? Share it here.

[adam-urbanczyk]

@jmwright @lorenzncode this is becoming quite big, so could you take a look and share what you think?

Initially I thought that ancestors should somehow become selectors, but the semantics of it would be super confusing (e.g. Faces('ancestors') would return something else than faces). I'm also not sure if the naming of the methods is optimal.

Current API looks like this

import cadquery as cq

w = cq.Workplane().box(1,1,1)

r0 = w.faces('>Z').edges('>X').ancestors('Face') #2 faces
r1 = w.faces('>Z').siblings('Edge') #4 faces
r2 = w.faces('>Z').siblings('Edge',2) # 1 face

Last, but not least, I think I improved _collectProperty - no more direct hashCode calls. This should the last source of flaky tests.

[lorenzncode]

Last, but not least, I think I improved _collectProperty - no more direct hashCode calls. This should the last source of flaky tests.

Excellent, that's good news.

I started playing around with this. Perhaps change siblings to eliminate the kind parameter or make it optional? Say I am selecting edges:

import cadquery as cq

w = cq.Workplane().box(1,1,1)

r0 = w.faces('>Z').edges('>X').siblings('Shell') # empty - invalid kind
r1 = w.faces('>Z').edges('>X').siblings('Face')  # empty - invalid kind
r2 = w.faces('>Z').edges('>X').siblings('Edge')  # empty - invalid kind
r3 = w.faces('>Z').edges('>X').siblings('Vertex')  # 4 edges

I think any kind other than 'Vertex' is invalid because the kind should be of inferior type. Automatically set kind based on the object type for ease of use?
Shell->Face
Face->Edge
Edge->Vertex

[jmwright]

I spent some time with this PR and can't find any issues. Everything seems to work as expected.

import cadquery as cq

s = cq.Workplane("XY")

# The points that the spline will pass through
sPnts = [
    (2.75, 1.5),
    (2.5, 1.75),
    (2.0, 1.5),
    (1.5, 1.0),
    (1.0, 1.25),
    (0.5, 1.0),
    (0, 1.0),
]

# 2.  Generate our plate with the spline feature and make sure it is a
#     closed entity
r = s.lineTo(3.0, 0).lineTo(3.0, 1.0).spline(sPnts, includeCurrent=True).close()

# 3.  Extrude to turn the wire into a plate
w = r.extrude(0.5)

# r3 = w.faces('>Z').edges('>X').siblings('Vertex')
r3 = w.faces('>Z').edges('>X').ancestors('Face')

show_object(w)

for r in r3.all():
    debug(r)

[adam-urbanczyk]

I started playing around with this. Perhaps change siblings to eliminate the kind parameter or make it optional? Say I am selecting edges:

import cadquery as cq

w = cq.Workplane().box(1,1,1)

r0 = w.faces('>Z').edges('>X').siblings('Shell') # empty - invalid kind
r1 = w.faces('>Z').edges('>X').siblings('Face')  # empty - invalid kind
r2 = w.faces('>Z').edges('>X').siblings('Edge')  # empty - invalid kind
r3 = w.faces('>Z').edges('>X').siblings('Vertex')  # 4 edges

I think any kind other than 'Vertex' is invalid because the kind should be of inferior type. Automatically set kind based on the object type for ease of use? Shell->Face Face->Edge Edge->Vertex

I was thinking about this, but it is not obvious that you always want connectivity via the -1 level. As as user you should consciously choose based on what you want.

[jmwright]

Looks good, thanks @adam-urbanczyk !

[lorenzncode]

It looks like the iterator improvements and new selectors will be useful features! Thanks @adam-urbanczyk!

Currently siblings supports a single level value. I don't have a real use case in mind for this but was thinking about whether it would be useful to allow multiple levels to be returned in a single call. Say I want levels 1,2 or (2,3,4 excluding 1). Perhaps a future enhancement if there was a real need.