OpenJSCAD.org: Discussion: updates and breaking changes to the API(s)

Please read this, even if it is a bit lengthy, as it contains information about future BREAKING CHANGES to OpenJSCAD, and the reasons behind it.

The current sitation:

• currently there are two APIs that you can use for modeling :
  • the functional, somewhat openscad-like API : ie sphere(), circle() , rotate_extrude() , translate([0,1,20], shape1), cube({round: true}) etc
  • the (somewhat) ‘object oriented’ CSG.xxx api : ie CSG.sphere(), CSG.circle(), CSG.roundedCube() etc
• both apis are
  • semi overlapping : CSG.sphere => sphere , etc
  • the functional api has more features, for example most extrusions are only in the functional api,
  • and often incoherent: not all extrusion parameters have the same ordering etc, some CSG.xxx api parts are attached to objects (Polygon3D.solidFromSlices()etc) which make them harder to use

Issues:

• it is harder to know which one to use and when : instead of having one clear API we end up with two half baked ones
• it doubles the mental load : ie you should not be using NEW with a lot of the functions , yet a lot of people (me included haha) use them in an wrong way : ie new CSG.cube() is wrong since it is not a constructor, just a function (so …the same as the functional API, just less clear)
• the CSG.XXX api make it much more complicated to add new features and expand the capabilities of openjscad
• the CSG.xxx api muddies the difference between ‘internal’ code (that should not be used directly) and code targeted at end users (all of us 😃
• clarity vs concision : a part of the current APIs sometimes relies on argument positions which is a lot less clear than passing configuration objects ie cube({size: 10, rounded: true}) is a lot more explicit then cube(10, true) , even if a bit more verbose

What we are doing (as in the core maintainers)

• we have been doing a LOT of restructure cleanup and documentation work inside both csg.js and the badly named scad-api
  • to clearly seperate the ‘core’ features from the more user facing ‘api’
  • to make it clear what the actual set of features at our disposal is
  • preparing to merge the two APIs & their repos : to have a single , simple logical place for all API related things
• it has also become clear in the process that we will HAVE TO MAKE SOME BREAKING CHANGES
• we will be doing the best we can to make the transition as ‘soft’ as possible, by first soft-deprecating some parts of the api (you will get a warning in the console that you should switch to specific replacements in the API) while introducing new ones

Parts of the code that will change (a lot more will be added ):

• rectangular_extrude => flip parameter ordering to match other extrusions
• rotate() / translate() /scale() (functional variants): will likely return arrays if provided with arrays : ie no more explicit union of shapes when passing arrays!!
• solidFromSlices() : remove from polygon3 prototype, and make it a “root level” function like rotate() / scale() etc ie solidFromSlices(polygon, options)
• lieFlat(), overCutInsideCorners() same as the above ie overCutInsideCorners(cag, 2)
• area(), volume() etc same as the above ie const areaOfMyShape = area(areaOfMyShape)
• we are still brainstorming it , but some of the Math utilities will be simplified and simple arrays will be favored for things like vectors (this is still work in progress)
• some of the shape creation APIs might change a bit (work in progress)

Consequences:

• some of the current scripts that you have written MIGHT break at some point in the future
• the scad-api will be deprecated and integrated into csg.js in one shape or another
• we will be strongly encouraging the functional api over the one using the object prototypes
  • the CSG.xxx will thus be the most strongly reduced part
  • we will make sure that the functional API becomes cleaner and clearer
• we will NOT be clinging to either the Openscad or the original CSG.js heritage for some of the functions, and always favor clarity
• we will also NOT break things often 😃 As the aim is not to make things worse for everybody , but to make them more pleasant to use in the long run and more forward facing
• we will NOT be breaking things overnight, and the new api and documentation will be ready BEFORE we deprecate anything

Discussion :

• we are of course open to discussing the details of these changes, so if you have questions/ and/or feedback it is very welcome
• please keep the discussion focused : this is NOT about adding new features, it is about how to use the current set of features.

cc @z3dev 😃