The following sections provide quick reference to the JSCAD application programming interface (API), the heart of making designs.
Note: Default values and notes are highlighted in bold fonts.
The follow defaults are used when creating rounded shapes. In many cases, the ‘resolution’ can be supplied as an option to functions.
2D Primitives | 3D Primitives |
---|---|
const rectangle = square(); /* center: [0,0], size: [1,1] */ | const cube1 = cube(); /* center: [0,0,0], size: [1,1,1] */ |
const rectangle = square({center: [1,2], size: [1, 2]}); | const cube1 = cube({center: [1, 2, 3], size: [1, 2, 3]}); |
const rectangle = square({round: true}); /* center: [0,0], radius: [1,1], roundradius: 0.2, resolution: 32 */ | const cube1 = cube({round: true}); /* center: [0,0,0], radius: [1,1,1] roundradius: 0.2, resolution: 12 */ |
const rectangle = square({center: [1,2], radius: [1, 2],rounded: true, fn:32}); | const cube1 = cube({center: [0, 0, 0], radius: 2, round: true, fn: 32}); |
const circle1 = circle(); /* center: [0,0], r: [1,1], resolution: 32 */ | const sphere1 = sphere(); /* center: [0,0,0], r: 1, fn: 12 */ |
const circle1 = circle({center: [1,2], r: 3, resolution: 72}); | const sphere1 = sphere({center: [1, 2, 3], r: 4, fn: 36}); |
const cylinder1 = cylinder(); | |
const cylinder = CSG.cylinder({start: [1, 2, 3], end: [4, 5, 6], radiusStart: 7, radiusEnd: 8, resolution: 72}); | |
const cylinder = CSG.roundedCylinder(); /* start: [0,-1,0], end: [0,1,0], radius: 1, resolution: 12 */ | |
const cylinder = CSG.roundedCylinder({start: [10,11,12], end: [13,14,15], radius: 16, resolution: 6}); | |
const ellipse = CAG.ellipse({center: [5,5], radius: [10,20],resolution: 72}); | const cylinder = cylinder({r1: 10, r2: 20, fn: 16}); |
const cag = CAG.fromPoints([ [0,0],[5,0],[3,5],[0,5] ]); /* polygon with 3+ points */ | const csg = CSG.fromPolygons([polygon, …]); |
const cag = CAG.fromSides([side,…]); /* polygon with 1+ sides */ |
2D Transformations | 3D Transformations |
---|---|
2Dshape = 2Dshape.translate([-2, -2]); | 3Dshape = 3Dshape.translate([1,2,3]); |
2Dshape = 2Dshape.rotateZ(20); | 3Dshape = 3Dshape.rotateX(90); |
3Dshape = 3Dshape.rotateY(-180); | |
3Dshape = 3Dshape.rotateZ(45); | |
2Dshape = 2Dshape.rotate(center, axis, degrees); | 3Dshape = 3Dshape.rotate(center, axis, degrees); |
2Dshape = 2Dshape.rotateEulerAngles(alpha, beta, gamma, position); | 3Dshape = 3Dshape.rotateEulerAngles(alpha, beta, gamma, position); |
2Dshape = 2Dshape.scale([0.7, 0.9]); | 3Dshape = 3Dshape.scale([1,2,3]); |
2Dshape = 2Dshape.center([true,true]); /* center X & Y axis */ | 3Dshape = 3Dshape.center([true,true,true]); /* center X & Y & Z axis */ |
2Dshape = 2Dshape.mirroredX(); | 3Dshape = 3Dshape.mirroredX(); |
2Dshape = 2Dshape.mirroredY(); | 3Dshape = 3Dshape.mirroredY(); |
3Dshape = 3Dshape.mirroredZ(); | |
2Dshape = 2Dshape.mirrored(plane); | 3Dshape = 3Dshape.mirrored(plane); |
2Dshape = 2Dshape.transform(matrix); | 3Dshape = 3Dshape.transform(matrix); |
/* not supported yet */ | 3Dshape = 3Dshape.setColor(r,g,b); /* a = 1.0 */ |
3Dshape = 3Dshape.setColor(r,g,b,a); | |
3Dshape = 3Dshape.setColor([r,g,b]); /* a = 1.0 */ | |
3Dshape = 3Dshape.setColor([r,g,b,a]); | |
2Dshape = 2Dshape.expand(0.2, 8); /* radius, resolution */ | 3Dshape = 3Dshape.expand(0.2, 8); /* radius, resolution */ |
2Dshape = 2Dshape.contract(0.2, 8); /* radius, resolution */ | 3Dshape = 3Dshape.contract(0.2, 8); /* radius, resolution */ |
Note: Shape transformations can be chained together. Example:
var 3Dshape = CSG.cube().rotate(45).translate([20,0,10]).setColor(1,0.5,0.3);
2D Operations | 3D Operations |
---|---|
2Dshape = union(2DshapeA, 2DshapeB) | 3Dshape = union(3DshapeA, 3DshapeB) |
2Dshape = difference(2DshapeA, 2DshapeB) | 3Dshape = difference(3DshapeA, 3DshapeB) |
2Dshape = intersection(2DshapeA, 2DshapeB) | 3Dshape = intersection(3DshapeA, 3DshapeB) |
3Dshape = 3DshapeA.inverse(3DshapeB) /* inverse solid and empty space */ |
Note: The previous object oriented API is still supported but will be decommissioned soon.
2D to Path Conversions |
---|
var Path2DArray = 2Dshape.getOutlinePaths(); |
2D to 3D Extrusions |
---|
3DShape = 2Dshape.extrude(); /* offset: [0,0,1], twistangle: 0, twiststeps: 12 */ |
3DShape = 2Dshape.extrude({offset: [0,0,50], twistangle: 360, twiststeps: 100}); |
3DShape = 2Dshape.rotateExtrude({offset: [0,0,50], twistangle: 360, twiststeps: 100}); /* angle: 360, resolution: 12 */ |
3Dshape = 2Dpath.rectangularExtrude(3, 4, 16, true); /* w, h, resolution, round ends */ |
3D to 2D Conversions |
---|
tbw |
These functions ease the transition from the OpenSCAD (proprietary script) to OpenJSCAD (JavaScript and objects).
2D Solid |
---|
var 2Dshape = circle(radius); |
var 2Dshape = circle(d); /* diameter */ |
var 2Dshape = square(size,center); |
var 2Dshape = square([width,height],center); |
var 2Dshape = polygon([points]); |
var 2Dshape = polygon([points],[paths]); |
Note: The OpenSCAD text() function is not supported.
3D Solid |
---|
var 3Dshape = torus(); /* ri = 1, ro = 4, fni: 16, fno: 32, roti: 0 */ |
var 3Dshape = torus({ ri: 1.5, ro: 3, fni: 4 }); |
var 3Dshape = torus({ ri: 1.5, ro: 3, fni:4, fno:4, roti:45 }); |
var path = vector_char(10,-10, 'A'); /* X axis, Y axis, character */ | |
var array_of_paths = vector_text(10,-10, 'Letters'); /* X axis, Y axis, string of characters */ |
A design can have parameters by declaring a special function; getParameterDefinitions().
In applications and browsers, these parameters are presented to users, allowing users to interactively change designs.
This function must return an array of parameter definitions, as show below.
function getParameterDefinitions() { return [ { name: 'length', type: 'int', initial: 150, caption: 'Length?' }, { name: 'width', type: 'int', initial: 100, caption: 'Width?' }, ]; }
The parameters are evaluated and values are passed into the main function. Be sure to declare the main function properly.
function main(params) { var l = params.length; var w = params.width; ... }
The parameters are defined as input fields on a single HTML5 form, i.e. the list of parameters. For more information on HTML5 input fields, see some examples at W3 Schools.
Note: Browsers are NOT the same and will treat unsupported parameter types as TEXT.
Type | Example | Returned Value |
---|---|---|
checkbox | {name: 'bigorsmall', type: 'checkbox', checked: true, caption: 'Big?'} | if checked true, else false |
checkbox | {name: 'bigorsmall', type: 'checkbox', checked: true, initial: 20, caption: 'Big?'} | if checked 20, else false |
color | { name: 'color', type: 'color', initial: '#FFB431', caption: 'Color?' } | “#rrggbb”, use html2rgb() to convert |
date | {name: 'birthday', type: 'date', caption: 'Birthday?'} | “YYYY-MM-DD” |
{name: 'address', type: 'email', caption: 'Email Address?'} | string value | |
float | {name: 'angle', type: 'number', initial: 2.5, step: 0.5, caption: 'Angle?'} | float value |
int | {name: 'age', type: 'int', initial: 20, caption: 'Age?'} | integer value |
number | {name: 'angle', type: 'number', initial: 2.5, step: 0.5, caption: 'Angle?'} | float value |
password | {name: 'password', type: 'password', caption: 'Secret?'} | string value |
slider | {name: 'count', type: 'slider', min: 2, max: 10, caption: 'How many?'} | float value |
text | {name: 'name', type: 'text', caption: 'Name?'} | string value |
url | {name: 'webpage', type: 'url', caption: 'Web page URL?'} | string value |
group | { name: 'balloon', type: 'group', caption: 'Balloons' } | none, only displayed |
The parameters accept additional restrictions and assistance. These include 'initial', 'max', 'maxLength', 'min', 'pattern', 'placeholder', 'size', and 'step'.
There is one more special parameter type called 'choice', which defines a list of choices for selection.
function getParameterDefinitions () { return [ { name: 'rounded', type: 'choice', caption: 'Rounded edges', values: [0, 1], captions: ['No', 'Yes (slow!)'], initial: 0 } ]; }
The list of captions are those shown in the HTML form, i.e. pull down list. The list of values define a value for each caption. And, the choosen value passed into the main() function.