search

jscad / OpenJSCAD.org

JSCAD is an open source set of modular, browser and command line tools for creating parametric 2D and 3D designs with JavaScript code. It provides a quick, precise and reproducible method for generating 3D models, and is especially useful for 3D printing applications.
https://openjscad.xyz/
MIT License
2.58k stars 505 forks source link

Suggestion for V3 API #1249

Open hjfreyer opened 1 year ago

hjfreyer commented 1 year ago

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 commented 1 year ago

@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 commented 5 months ago

@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.