Suggestion for V3 API

[hjfreyer]

I happened to see this wiki page and I thought I'd offer my unsolicited opinion: https://github.com/jscad/OpenJSCAD.org/wiki/JSCAD-V3

I really like jscad, but I often find the APIs surprising, particularly with respect to how operations affect groups of geometries I pass to them.

For instance, I'm modeling a table right now, and I have an array of two legs and a plate that they'll connect to. I just ran this:

[legs, plate] = align({modes: ['none', 'center', 'none'], grouped: true}, [legs, plate]);

However, this didn't work. With console.log, I saw that the align operation had converted my argument with structure [[leg1, leg2], plate] into a flat array: [leg1, leg2, plate]. I run into this kind of confusion all the time.

My advice would be to consistently treat arrays of geometries as single objects, or perhaps introduce a first-class "group" type. For instance, centerX([a, b, c]) shouldn't center each object individually. If I wanted that behavior, I'd write [a, b, c].map(x => centerX(x)). Some operations may still want to recurse over the structure (e.g. intersect([a, [b, c]], d) should go in and intersect d with each item in the first argument), but it shouldn't disrupt the structure I provided.

Thanks for the great library! Hope this helps.

[z3dev]

@hjfreyer nice suggestions. thanks.

The suggestion to 'align' based on the structure of the array seems reasonable, but probably requires another 'option'. Feel free to submit some API changes. We are working on V3 now, and have already broken a few of the APIs.

The reason for the flattening of objects is to treat the parameters in a consistent manner. For example...

let results = align({}, circle())
results = align({}, circle(), square())
results = align({}, ...contents)
results = align({}, [a, b, c])

Yeah. It probably doesn't make sense for lots of people, nor all the time, but at least it's consistent throughout the functions of JSCAD. No surprises. All input is flattened.

[z3dev]

@hjfreyer V3 recently had a major change to the APIs in general.

I think that @platypii could add a few comments on the changes here.