Any lessons learned about selector design?

[xpe]

Context: I went back and reviewed some of the "early days" writings you did about your motivations. Existing CAD kernels and layers on top of them have many usability problems. For example, while Python's CadQuery appears easy at the beginning, this perceived ease-of-use falls apart when using selectors.

For example, in CadQuery, something as conceptually simple as "select the inner circular edge of this hole" seems difficult -- not just for me -- but for many, based on some internet searching. I got something to work but it feels very brittle. Here is a code sample that offer as a counter example of good API design:

# CadQuery, not Fornjot!
# `s` so far is a rectangular prism
s = (
    s.faces("<Z")
    .workplane()
    .pushPoints(hole_points)
    .hole(hole_diameter, hole_depth)
    .edges("%CIRCLE and >>Z[2]")
    .fillet(hole_fillet_radius)
)

Specifics: Have you considered writing down (even for only 5 minutes) any thinking you've done about selectors? I'm talking about selecting edges, faces, and so on. Key design criteria might include:

• supporting composability as much as possible
• supporting absolute selectors
• supporting relative selectors

What else is important? I'm relatively new to the fundamentals of the fundamental abstractions of BREP.

P.S. I've used some libraries / tools that handle selectors elegantly. It seems like much could be learned by thinking about the lessons learned of CSS, though I don't hold up its API as world-class.

[hannobraun]

I have thoughts, but few lessons learned, unfortunately. When I did those early-day writings, a lot of that stuff seemed to be just around the corner. But as it turns out, everyone's right when they say that CAD kernels are hard. I spent most of my effort since then figuring out how to represent shapes in a way that is robust and makes it easy to manipulate them (and, frankly, going down the wrong direction for extended lengths of time, more than once).

I've made lots of progress in that regard, but that is basically still the core of what I'm doing. But as that work progresses, and the complexity of models that are practical to express slowly increases, I'm starting to butt up against selectors again.

Basically, the way it works now, you can only select something by knowing exactly what you're selecting, i.e. you need a Handle to the object.

• In some cases, when you create an object directly, you can just store the handle you get back and use that later.
• There are also some selector-like ways to get Handles you don't yet have (for example), allowing you to do things like cycle.half_edges().nth(2), the result of which is a Handle that you then can pass to an operation.
• There's an open issue on an incremental improvement to that technique.
• There's another issue about labeling objects for debug purposes, but I've since realized, that same concept can apply to selectors. The basic idea is, you say at some point "the second line segment in that sketch is called x", and that label is carried forward through any operations applied, so later on you can say "select the vertices that bound the top edge of the face swept from x".
• I've also come to realize, that there probably isn't one approach to rule them all. For example geometric selectors, either global ("give me top-most face") or relative ("give me the top half-edge of this face") can't be avoided.

Based on past experience, I suppose the implementation will go something like this:

1. Make incremental improvements to existing selector infrastructure.
2. Add new selector features where there's a concrete use case to motivate them.
3. Keep repeating this until it grows into a huge mess.
4. Wrangle with that mess until a unified selector design emerges from that experience.
5. Implement that unified selector design. It won't work well.
6. Go through 10 more iterations of the design, each of which will work a bit better than the one before.
7. Done! (This item is theoretical. I don't think there's a single thing in Fornjot that won't be changed again 😄)

I will also look into existing designs along the way, but my experience has been that it is almost never possibly to cleanly apply them to a non-trivial system like Fornjot. But stuff like that serves as inspiration, which always comes in handy on step 4 of that process I outlined.

[xpe]

Thanks for sharing. You linked some nice detailed discussions! 👍

I know what you meant w.r.t. steps 3, 4, 5. 👹 It seems to me there is a sort of a "meta optimization" tuning parameter; namely; how much of a mess to tolerate before recognizing the current iteration's design isn't sufficient.

I think of step 7 as something akin to an asymptote -- you get closer to "done" over time. Also, as user uptake improves, the (cost - benefit) of a breaking change decreases. Meaning quite often, at some point, a breaking change doesn't seem worth it. This to me seems to explain why many libraries and languages sort of run their course... to a point at which their design decisions are mostly fully realized and they have to accept who they are now, warts and all. :)

Back to the particulars ... I just noticed that CadQuery has tagging (perhaps similar to Fornjot's Handle) ... which is a useful concept:

The Workplane.tag() method can be used to tag a particular object in the chain with a string, so that it can be referred to later in the chain.

This expands my very rough taxonomy of selectors to be something like a two dimensional grid:

• maybe the X axis: one kind of choice: absolute selectors versus relative selectors
• maybe the Y axis for another kind of choice ... where to "root" the selector "chain" (if that makes sense)
  • classes of things (such as edges or faces)
  • named things (perhaps via something like handles/tagging)

[hannobraun]

I know what you meant w.r.t. steps 3, 4, 5. 👹 It seems to me there is a sort of a "meta optimization" tuning parameter; namely; how much of a mess to tolerate before recognizing the current iteration's design isn't sufficient.

It's not just about tolerating the mess. It's also about knowing what a better design even is. To me, that's often not clear from the beginning, and I won't get there by just sitting and thinking. Wading through the mess is often the only solution 😄

(Check out #1589, if you like a rabbit hole.)

I think of step 7 as something akin to an asymptote -- you get closer to "done" over time. Also, as user uptake improves, the (cost - benefit) of a breaking change decreases. Meaning quite often, at some point, a breaking change doesn't seem worth it. This to me seems to explain why many libraries and languages sort of run their course... to a point at which their design decisions are mostly fully realized and they have to accept who they are now, warts and all. :)

I agree. I wonder if and when Fornjot will calcify like that. It's hard to imagine at this point 😄

Back to the particulars ... I just noticed that CadQuery has tagging (perhaps similar to Fornjot's Handle) ... which is a useful concept:

[...]

Yeah, that sounds similar to what you can currently do with Handle.

This expands my very rough taxonomy of selectors to be something like a two dimensional grid:

• maybe the X axis: one kind of choice: absolute selectors versus relative selectors
• maybe the Y axis for another kind of choice ... where to "root" the selector "chain" (if that makes sense)
  • classes of things (such as edges or faces)
  • named things (perhaps via something like handles/tagging)

Interesting! Something to keep in mind for the eventual unification of all selector approaches (once they exist).

[xpe]

A quick update as I've learned and thought 'bout it more:

• absolute selectors versus relative selectors
• kinds (i.e. wires, faces, bodies, edges)
• named/tagged things
• geometric selectors... (a) proximity to a point: near vs far; (b) adjacency to an item: e.g. touching
• property-based selectors: e.g. close matches to items with similar properties (length, radius, etc)
• (possibly) stack-based selection along the lines of CadQuery ... though I see this as a higher level selector API, not really necessary for a kernel *

But all of this is hand waving until types are specified. :)

* figuring out the minimal set of things for a kernel seems wise, while keeping an eye to ergonomic APIs that build on top. Which makes me realize I probably don't really fully understand the minimum core responsibilities of a 3D kernel. Much to learn...

[hannobraun]

figuring out the minimal set of things for a kernel seems wise, while keeping an eye to ergonomic APIs that build on top. Which makes me realize I probably don't really fully understand the minimum core responsibilities of a 3D kernel. Much to learn...

I don't know, I wouldn't think too much about stuff like that. The project can be whatever we decide it to be, and if that turns confusing, we can call it something else than a kernel 😄

It's all going to depend on what users need, and what resources there are to implement.