OpenJSCAD Quick Reference

This is a V1 outdated documentation and deprecated see https://github.com/jscad/OpenJSCAD.org/issues/783.

The page provides a quick reference to OpenJSCAD and CSG library functions.

OpenJSCAD User Guide

CSG and CAG User Guide

Note: Default values and notes are highlighted in bold fonts.

General Usage

OpenJSCAD Functions	JavaScript Statements
function main(parameters) { ...; return var; } /* required */	var name = my_box( {attribute: 1, ...} ); /* call a function */
function getParameterDefinitions() {return [ definition... ]; } /* optional */	function my_box( param ) { ...; return shape; } /* create a function */
OpenJsCad.log("message"); /* display message and time stamp */	console.log("message"); /* display message */
include...	for (index = 0; index < array.length; index--;) { ... };

Note: Messages are displayed in the Javascript console in browsers.

Note: If not provided, the default resolution is used when creating rounded shapes.

 * CSG.defaultResolution2D: 32
 * CSG.defaultResolution3D: 12

Primitive Shapes

2D Primitives	3D Primitives
var rectangle = CAG.rectangle(); /* center: [0,0], radius: [1,1] */	var cube = CSG.cube(); /* center: [0,0,0], radius: [1,1,1] */
var rectangle = CAG.rectangle({center: [1,2], radius: [1, 2]});	var cube = CSG.cube({center: [1, 2, 3], radius: [1, 2, 3]});
var rectangle = CAG.roundedRectangle(); /* center: [0,0], radius: [1,1], roundradius: 0.2, resolution: 32 */	var cube = CSG.roundedCube(); /* center: [0,0,0], radius: [1,1,1] roundradius: 0.2, resolution: 12 */
var rectangle = CAG.roundedRectangle({center: [1,2], radius: [1, 2], roundradius: 1, resolution:32});	var cube = CSG.roundedCube({center: [0, 0, 0], radius: [3,3,3], roundradius: 0.5, resolution: 32});
var circle = CAG.circle(); /* center: [0,0], radius: [1,1], resolution: 32 */	var sphere = CSG.sphere(); /* center: [0,0,0], radius: 1, resolution: 12 */
var circle = CAG.circle({center: [1,2], radius: 3, resolution: 72});	var sphere = CSG.sphere({center: [1, 2, 3], radius: 4, resolution: 36});
	var cylinder = CSG.cylinder(); /* start: [0, -1, 0], end: [0, 1, 0], radius: 1, resolution: 32 */
	var cylinder = CSG.cylinder({start: [1, 2, 3], end: [4, 5, 6], radiusStart: 7, radiusEnd: 8, resolution: 72});
	var cylinder = CSG.roundedCylinder(); /* start: [0,-1,0], end: [0,1,0], radius: 1, resolution: 12 */
	var cylinder = CSG.roundedCylinder({start: [10,11,12], end: [13,14,15], radius: 16, resolution: 6});
var ellipse = CAG.ellipse({center: [5,5], radius: [10,20],resolution: 72});	var cylinder = CSG.cylinderElliptic({start: [0,-10,0],end: [0,10,0],radiusStart: [10,5],radiusEnd: [5,2.5],resolution: 16});
var cag = CAG.fromPoints([ [0,0],[5,0],[3,5],[0,5] ]); /* polygon with 3+ points */	var csg = CSG.fromPolygons([polygon, ...]);
var cag = CAG.fromSides([side,...]); /* polygon with 1+ sides */

Shape Transformations

Shape transformations always return a new shape, leaving the original shape unchanged. The original shape can be changed by reassigning the original, like this.

var a = cube();
a = a.rotateX(45);

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);	2Dshape = 2Dshape.rotate(center, axis, degrees);
2Dshape = 2Dshape.rotateEulerAngles(alpha, beta, gamma, position);	2Dshape = 2Dshape.rotateEulerAngles(alpha, beta, gamma, position);
2Dshape = 2Dshape.scale([0.7, 0.9]);	3Dshape = 3Dshape.scale([1,2,3]);
2Dshape = 2Dshape.center(); /* center X & Y axis */	3Dshape = 3Dshape.center(); /* center X & Y & Z axis */
2Dshape = 2Dshape.center('x');	3Dshape = 3Dshape.center('x','z');
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 */

Shape transformations can be chained together. For example:

var 3Dshape = CSG.cube().rotate(45).translate([20,0,10]).setColor(1,0.5,0.3);

Shape Operations

Shape operations always return a new shape, leaving the original shape unchanged. The original shape can be changed by reassigning the original, like this.

var a = cube();
a = a.intersect(sphere());

2D Operations	3D Operations
2Dshape = 2DshapeA.union(2DshapeB);	3Dshape = 3DshapeA.union(3DshapeB);
2Dshape = 2DshapeA.subtract(2DshapeB)	3Dshape = 3DshapeA.subtract(3DshapeB);
2Dshape = 2DshapeA.intersect(2DshapeB);	3Dshape = 3DshapeA.intersect(3DshapeB);
	3Dshape = 3DshapeA.inverse(3DshapeB); /* inverse solid and empty space */

Dimension Conversions

2D to Path Conversions
var Path2DArray = 2Dshape.getOutlinePaths();

2D to 3D Conversions
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

OpenSCAD-like Functions

These functions ease the transition of designs from OpenSCAD (Lisp-like) to OpenJSCAD (JavaScript and objects).

2D Primitives	3D Primitives
var shape = circle(); /* r: 1, center: false, fn: 32 */	var shape = sphere(radius);
var shape = circle({r: 2,center: false, fn: 16});	var shape = sphere(d); /* diameter */
var shape = square(); /* [1,1], center: false */	var shape = cube(size,center);
var shape = square(5); /* same as square([5,5]) */	var shape = cube(size,center);
var shape = square( [4,5],{center: true} );	var shape = cube([width,height],center);
	var shape = cylinder(h,r,center);
	var shape = cylinder(h,r1,r2,center);
var shape = polygon( [[0,3],[3,3],[3,0]] );	polyhedron(points,triangles,convexity)
var shape = polygon([points],[paths]);	polyhedron(points,triangles,convexity)

Text

2D Shape
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 */

Note: The text() function as known in OpenSCAD is not supported.

Interactive Parameters

A design can have interactive parameters by declaring a special function; getParameterDefinitions().

Usage

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

Parameter Types

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"
email	{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

Note: The parameters accept additional restrictions and assistance. These include 'initial', 'max', 'maxLength', 'min', 'pattern', 'placeholder', 'size', and 'step'.