Advanced selectors

[adam-urbanczyk]

Placeholder issue to discuss about extending selectors

• selectors on tags
• selectors based on history
• selectors for topology traversal

[michaelgale]

I'll kick things off with a few notes about how I'm going to refactor my own CQ-Kit Selector classes to make them more general purpose and to arrange them into a more logical taxonomy about what they do.

1. Selection by Geometric Property

HasCoordinateSelector(coordinate, min_points=1)
HasXCoordinateSelector(HasCoordinateSelector)
HasYCoordinateSelector(HasCoordinateSelector)
HasZCoordinateSelector(HasCoordinateSelector)

• returns objects which have any or all of the specified X,Y,Z coordinate. min_points means that the object must have at least this many of its vertices with the desired coordinate. For edges, this means either the start or end point if min_points=1 or both start and end points if min_points=2, etc.

LengthSelector(lengths, tolerance=DEFAULT_TOL)
EdgeLengthSelector(LengthSelector)
WireLengthSelector(LengthSelector)
RadiusSelector(LengthSelector)
DiameterSelector(LengthSelector)

• returns edges or wires satisfying one or more length criteria

AreaSelector(areas, tolerance=DEFAULT_TOL)

• returns faces or wires with an area (centre of mass) criteria

EdgeCountSelector(counts)

• returns solids, shells, faces or wires with specified number of edges <=, ==, >=

VertexCountSelector(counts)

• returns solids, shells, faces or wires with specified number of vertices <=, ==, >=

Criteria for these selectors can be a single value, string constraint (e.g. "<=5.3"), or list of values/strings (e.g. [4.0, "<2.5", 7.5])

2. Selection by Orientation

VerticalSelector(with_heights=None, tolerance=DEFAULT_TOL)
VerticalEdgeSelector(VerticalSelector)
VerticalWireSelector(VerticalSelector)
VerticalFaceSelector(VerticalSelector)

• returns objects standing "up" i.e. "almost and exactly" |Z with optional height criteria (convenience by saving one step of logical AND with LengthSelector)

FlatSelector(at_heights=None, tolerance=DEFAULT_TOL)
FlatEdgeSelector(FlatSelector)
FlatWireSelector(FlatSelector)
FlatFaceSelector(FlatSelector)

• returns objects lying "flat", i.e. close enough to planar with XY plane and optionally at particular height(s)

For criteria with a default value of None, the Selector acts as a trivial transparent pass through filter, e.g. vertical edges of any length. Criteria can also be specified with any combo of single value, string constraint, or list.

3. Selection by Association

SharedVerticesWithObjectSelector(min_points=1, tolerance=DEFAULT_TOL)
SharedVerticesWithEdgeSelector(SharedVerticesWithObjectSelector)
SharedVerticesWithWireSelector(SharedVerticesWithObjectSelector)
SharedVerticesWithFaceSelector(SharedVerticesWithObjectSelector)

• returns any objects which have min_points vertices shared by another object
  e.g. SharedVerticesWithWireSelector returns any objects which have a vertex on
  a specified Wire. This is analogous to a "connected with" selector.

SharedVerticesWithCornerSelector(corners, tolerance=DEFAULT_TOL)

• returns any objects which have one or more vertices shared by the specified corner(s) of another object. Corners are specified as a string "<X >Y" or "<X >Y >Z" etc. or list of same. The corners represent the vertex that best represents a "top left' or "bottom right tallest" etc. definition based on their distance from the centre of mass.

NearObjectSelector(num_to_find=1, tolerance=DEFAULT_TOL)
NearVertexSelector(NearObjectSelector) (like the current NearestToPointSelector)

• returns up to num_to_find object(s) closest to specified object within tolerance

SameLengthAsObjectSelector()
SameHeightAsObjectSelector()
SameAreaAsObjectSelector()
SameEdgeCountAsObjectSelector()
SameVertexCountAsObjectSelector()

FaceOuterVerticesSelector(face)
FaceOuterEdgesSelector(face)
FaceOuterWireSelector(face)

VerticesInsideFaceSelector(face)
EdgesInsideFaceSelector(face)
WiresInsideFaceSelector(face, min_edges=3)

General Notes

• Some selectors listed above might be overly redundant and could be automatically determined by type inference. e.g. a VerticalSelector could be smart enough to determine if any edge, wire, or face is "vertical". But the explicit versions do help with readability when building complex composite selectors.
• Taking the string syntax selector further, it could evolve into a full "SQL" like query grammar, e.g. "length=any(2.0, 5.0, ">8") closest to point(1,2,1)" or "length=2.0 and Z<10.0"
• If we introduce a TagSelector, then using the existing boolean/arithmetic operations will extend selection by this property too. Although I am not sure how it will work.

[michaelgale]

As an imagined example, the following code selects flat faces at height 3.2mm with an area > 100 and from these candidate faces, pick closed inside wires with 4 edges and from these wires selects edges with common vertices with lengths not less than 1.0 and do not extend above 3.2 mm.

fs = AreaSelector(">100") & FlatFaceSelector(at_height=3.2)
faces = solid.faces(fs).vals()
for face in faces:
    wires = solid.wires(WiresInsideFaceSelector(face, min_edges=4)).vals()
    for wire in wires:
        es = SharedVerticesWithWireSelector(wire)
        es -= EdgeLengthSelector("<1.0")
        es -= HasZCoordinateSelector(">3.2")
        solid = solid.edges(es).fillet(0.1)

Another nice thing with selectors is being able to consolidate the filtered objects and then performing an operation once (like filleting) instead of repeatedly:

fs = AreaSelector(">100") & FlatFaceSelector(at_height=3.2)
faces = solid.faces(fs).vals()
es = None
for face in faces:
    wires = solid.wires(WiresInsideFaceSelector(face, min_edges=4)).vals()
    for wire in wires:
        vs = SharedVerticesWithWireSelector(wire)
        if es is None:
            es = vs
        else:
            es += vs
es -= EdgeLengthSelector("<1.0")
es -= HasZCoordinateSelector(">3.2")
solid = solid.edges(es).fillet(0.1)       

[michaelgale]

I forgot one more category from above:

4. Selection by Position

BoxSelector(pos, size)
RotatedBoxSelector(pos, size, z_angle)
BoxSelectorArray(box_selector, pts)

[michaelgale]

I'm on a role! ONE MORE THING: I often find it is convenient to "add" selectors to consolidate objects for selection. Often this involves something like bs = bs + BoxSelector() or more conveniently bs += BoxSelector().

Basically, I want to be able to this:

bs = NullSelector()
for pt in pts:
    bs += BoxSelector(pt, (1, 1, 1))
solid = solid.edges(bs).fillet(0.1)

but instead I have to do this:

bs = None
for pt in pts:
    if bs is None:
        bs = BoxSelector(pt, (1, 1, 1))
    else:
        bs = bs + BoxSelector(pt, (1, 1, 1))

Therefore, I would propose that the Selector class implement the __iadd__(self, other) and __isub__(self, other) dunder methods and a new NullSelector derived class be added to act as placeholder empty Selector which does nothing.

[marcus7070]

Out of these two ideas:

1. Taking the string syntax selector further, it could evolve into a full "SQL" like query grammar, e.g. "length=any(2.0, 5.0, ">8") closest to point(1,2,1)" or "length=2.0 and Z<10.0"

2. Therefore, I would propose that the Selector class implement the __iadd__(self, other) and __isub__(self, other) dunder methods and a new NullSelector derived class be added to act as placeholder empty Selector which does nothing.

I strongly prefer the second.

If we introduce a TagSelector, then using the existing boolean/arithmetic operations will extend selection by this property too.

I don't think this will be possible with the current implementation of tags. Tags refer to cadquery.CQ objects, selectors operate on cadquery.Shape objects. I do not think selectors should operate on anything but Shapes, or else we are going to wind up with a lot of type-checking and convoluted code.

But perhaps the cadquery.CQ.tag method could be extended to also set a cadquery.Shape._tag attribute? This would get complicated though. The thing I like about tags right now is that they are so simple; it is the CQ object in the parent chain. If we start tagging Shapes, then are the tags propagated to subsequent shapes? If a shape is split in half, do both halves get the tag? If a shape is transformed (rotate, offset, etc.), does the tag selector return the original or a transformed version?

I don't mean to be negative. If we can implement TagSelector in such a way that it is easy to understand (from a user perspective), I think that would be useful and an improvement over the current tagging method.

[adam-urbanczyk]

Indeed currently tags are orthogonal to selectors. To be slightly more flexible I'd propose to keep track of tags via the ctx object:

class CQContext(object):
       
     pendingWires : List[Wire]
     pendingEdges : List[Edge]
     tags : Dict[str, Workplane]

this way it would be easier to implement something like .faces('>Z',tag=('first_tag','second_tag')). My understanding of the design intent is that tags point ot a place on the CQ stack and if a e.g. split occurs then a new stack level is created. So I'd conclude that tags should not be propagated .

To actually implement TagSelector(Selector) class the evaluation mechanism of selectors would need to change. Now first an input list of entities (based on a tag) is created and then it is filtered. It is not clear to me what would be a logical evolution of this approach when using tags in the filtering step as well. Proposals are more than welcome!

[michaelgale]

I think it would be helpful if someone could craft an example of how using tags might be used, preferably with imaginary source code. I'm sure they can be helpful, its just that I can't get my head around how I would integrate them into a CAD workflow.

[dcowden]

@michaelgale I'll do that!

[dcowden]

@michaelgale I published a walkthrough in this google doc

I used Solidworks to do the pictures, so that i could write code that doesnt work ( yet! ).

The walk through illustrates use of projecting geometry onto planes, operation tagging/naming, and selecting by operation and by createdBy selectors. I was purposely not all that precise about the stynax-- i used a couple of different example styles.

This object is still very simple-- just boxes and circles. Projecting and re-using geometry becomes VERY important when models get complicated, because you lose the ability to re-calculate where things should be.

[marcus7070]

I said:

I do not think selectors should operate on anything but Shapes, or else we are going to wind up with a lot of type-checking and convoluted code.

Thinking about this a bit more, I've changed my mind. For selectors to access information such as tags or feature/operation history, they should operate on a cadquery.CQ object.

There is information contained in the CQ objects that would be useful for selection methods. Particularly for an OperationSelector, where I can see logical combinations like operation Foo and operation Bar, Foo not Bar, Foo intersect Bar, etc. being very useful.

Selectors would need to accept a CQ object as input and output a new CQ object (so that they can be chained together). That sounds like a big change, but it's actually just moving some logic around. Basically move the _collectProperty method over to the Selector base class, which would allow selectors such as TagSelector or OperationSelector to skip it and do something different.

[richardwa]

How about selection by Boolean operation? It seems natural that when I am adding in some extrusion would want to fillet the connection, like Union-Round.

I was able to monkey-patch a POC using "BRepAlgoAPI_BooleanOperation.SectionEdges", this is natively in OCP.