V1 -> V2 migration guide

[hrgdavor]

V1 is not officially supported (unless new developers come along to do so) but here is a list of sites running v1 instance

https://3d.hrg.hr/jscad/V1/ with support for remote url
and a # remote url example example
https://3d.hrg.hr/jscad/V1/#https://gitlab.com/johnwebbcole/jscad-utils/raw/master/dist/examples/snap.jscad

other sites:

• https://openjscad.surge.sh/
• https://openjscad.com/
• http://openjscad.azurewebsites.net/

automatic conversion

Thanks to @apla there is a script on gihub gists that can convert most v1 code to v2
https://gist.github.com/apla/90edff2e4993f3e3592f8795c2050cc5

manual conversion

inital setup

V2 can be run as nodejs script, and the reason is that it now requires you to import modeling functions from jscad package, they are no longely magically available in your script. You can start by pasting this snippet on top:

const jscad = require('@jscad/modeling')
const { connectors, geometry, geometries, maths, primitives, text, utils, booleans, expansions, extrusions, hulls, measurements, transforms, colors } = jscad
const { cuboid, sphere, cylinder, circle, star,cylinderElliptic, polyhedron, roundedRectangle, rectangle } = primitives
const { translate, scale, center } = transforms
const { union, subtract, intersect } = booleans
const { path2, geom2, geom3, poly2, poly3 } = geometries
const { slice, extrudeFromSlices, extrudeLinear, extrudeRectangular, extrudeRotate, project } = extrusions
const { mat4, line2, line3, vec2, vec3, vec4 } = maths

// to make this conversion to V2 easier, some functions are not importd, but implemented as compat layer

// rotate in V2 uses radinas instad of degrees
const rotate = (angles,...parts)=>transforms.rotate(angles.map(utils.degToRad), ...parts)
// in V2 cube is ony for actual cubes with all of the sides same size
const cube = (params)=>cuboid(params)
// change in parameter names for cylinder
const cylinder = ({h,r})=>primitives.cylinder({radius:r, height:h})
// difference is  subtract in V2
const difference = subtract

It may look like overkill, but do it like this for the begininngi, and later on you can choose to remove what you do not use. to find where is each function placed use https://openjscad.xyz/docs/ as reference.

Also add this snippet to bottom of your script

module.exports = {main}

or this one if you use getParameterDefinitions

module.exports = {main,getParameterDefinitions}

try your script

drag and drop your script file to https://openjscad.xyz/ and enable reload so each time you save the script it will be re-evaluated. Instead of using editor provided in the browser it might be even better to use your own editor of choice and test the script this way.

Your script will likely fail because there are some changes intarnally in V2 that make it incompattible with V1. That said the differences are not that big and you should be able to quickly adapt.

debugging the errors

When you run your script for the first time you may get an error that is part of jscad core, and gui will not show tha stack trace

open dev console in your browser (F12) and look for the full error

NOTICE: line numbers will be off by 2 42->40 79->77 ...

CENTER - likely the largest issue in converting to V2

You will have less work to do while converting to V2 if you use V1 first and convert your script to always use center: true. V2 centers primitives by default.

This change in V1->V2 is harderst as it affects the positions of geometries. Other changes are more syntactical or changes in parameter names.

Once you have center:true in your V1 script everywhere you must remove them all from the scrpt because V2 expects a vec3 (array of 3 coordinates). The default for center in V2 is center:[0,0,0] and instead of changing your code to use that, you can just remove yout center: true

translate, rotate and functional syntax

This is bit of tedious work to change things from

cube({size:[3,2,4]).translate([10,10,10])

to

translate([10,10,10], cube({size:[3,2,4]))

the same goes for other transforms

Some more complicated multiline examples (thanks @apla )

cube ({
    size: [yBearing.D*2, yBearing.D*2, outerShell*2],
    center: true
}).translate ([0, (swapPulleys ? -1 : 1)*.5*yBearing.D, (yBearing.D - blockHeight)/2 - blockHeight/2]),

becomes this:

translate ([0, (swapPulleys ? -1 : 1)*.5*yBearing.D, (yBearing.D - blockHeight)/2 - blockHeight/2],
  cube ({
      size: [yBearing.D*2, yBearing.D*2, outerShell*2],
      center: true
  }),
),

or

renderPulley (this.config.beltPulley, outerShell, true).translate ([
    (beltPulley.od + beltPulley.fr*2 - beltPulley.od)/2 - outerShell,
    (swapPulleys ? -2 : 0) * (beltPulley.od/2 + beltPulley.fr) + (swapPulleys ? -1 : 1) * pulleyShift,
    (yBearing.D + beltPulley.h)/2
])

becomes

translate ([
    (beltPulley.od + beltPulley.fr*2 - beltPulley.od)/2 - outerShell,
    (swapPulleys ? -2 : 0) * (beltPulley.od/2 + beltPulley.fr) + (swapPulleys ? -1 : 1) * pulleyShift,
    (yBearing.D + beltPulley.h)/2
  ],
  renderPulley (this.config.beltPulley, outerShell, true)
)

parameter names

keep the open in a tab 😄 https://openjscad.xyz/docs/module-modeling_primitives.html

some common changes are for single letter parameters

• h -> height
• r -> radius
• rotation now uses degrees instead of radians, use utils.degToRad

function name changes

keep the open in a tab 😄 https://openjscad.xyz/docs/module-modeling_primitives.html

• difference -> subtract
• cube -> cuboid, and cube is not only
• ->

[apla]

My old scad files full of things like this

            // for screws
            cube ({
                size: [yBearing.D*2, yBearing.D*2, outerShell*2],
                center: true
            }).translate ([0, (swapPulleys ? -1 : 1)*.5*yBearing.D, (yBearing.D - blockHeight)/2 - blockHeight/2]),

            // belt pulleys
            renderPulley (this.config.beltPulley, outerShell, true).translate ([
                (beltPulley.od + beltPulley.fr*2 - beltPulley.od)/2 - outerShell,
                (swapPulleys ? -2 : 0) * (beltPulley.od/2 + beltPulley.fr) + (swapPulleys ? -1 : 1) * pulleyShift,
                (yBearing.D + beltPulley.h)/2
            ])
 ...

After v2 conversion it will like

translate(mumbo-jumbo, cube somewhere very deep ),
translate(mumbo-jumbo2, renderPulley somewhere very deep ),

Total disappointment. Needs complete rewrite to make it understandable.

[hrgdavor]

Actually it does not have to be that much worse like you describe

cube ({
    size: [yBearing.D*2, yBearing.D*2, outerShell*2],
    center: true
}).translate ([0, (swapPulleys ? -1 : 1)*.5*yBearing.D, (yBearing.D - blockHeight)/2 - blockHeight/2]),

becomes this:

translate ([0, (swapPulleys ? -1 : 1)*.5*yBearing.D, (yBearing.D - blockHeight)/2 - blockHeight/2],
  cube ({
      size: [yBearing.D*2, yBearing.D*2, outerShell*2],
      center: true
  }),
),

or

renderPulley (this.config.beltPulley, outerShell, true).translate ([
    (beltPulley.od + beltPulley.fr*2 - beltPulley.od)/2 - outerShell,
    (swapPulleys ? -2 : 0) * (beltPulley.od/2 + beltPulley.fr) + (swapPulleys ? -1 : 1) * pulleyShift,
    (yBearing.D + beltPulley.h)/2
])

becomes

translate ([
    (beltPulley.od + beltPulley.fr*2 - beltPulley.od)/2 - outerShell,
    (swapPulleys ? -2 : 0) * (beltPulley.od/2 + beltPulley.fr) + (swapPulleys ? -1 : 1) * pulleyShift,
    (yBearing.D + beltPulley.h)/2
  ],
  renderPulley (this.config.beltPulley, outerShell, true)
)

If you refactor it like suggested here, the readability does not change that much. Hope this helps

[z3dev]

V1 CSG and CAG objects are no longer supported, instead V2 JSCAD has adopted a functional API. However there are some alternatives.

Example of Using Primitives

const acircle = CAG.circle({ center: [3, 5], radius: 15 })
const acylinder = CSG.cylinder({ radius: 10, resolution: 16 })

The V1 primitives are still available but have some changes in parameter names. (See 'Initial Setup' above on how to access the V2 primitives)

const acircle = circle({ center: [3, 5], radius: 15 })
const acylinder = cylinder({ radius: 10, segments: 16 }) // resolution has been renamed to segments

Creating and Using Objects
There is no limitation on the use of objects, but you will have to create the object definitions yourself. Even CSG / CAG objects can be created to simulate the old V1 objects.

EXAMPLE CODE

It's probably time to think about what's important in your designs. If your designs are always creating 'bolts' then an object that represents a 'bolt' is a better abstraction. There are many small part libraries that do exactly that.

Finally, there is a library available as part of the JSCAD Community, and this library includes object versions of the 2D and 3D geometries found in V2. See the jscad-object-api