**This is an old revision of the document!**

In general, designs are written using the JavaScript language. Training and help about JavaScript can be found online.

Creating a new design starts by writing simple scripts which call functions to create and manipulate shapes. JSCAD executes the script, and renders the design for viewing.

A JSCAD script must have at least one function defined, the **main()** function, which must to return a shape.

function main() { return sphere() // a single shape }

Or an array of shapes.

function main() { const a = cube() const b = sphere() const c = cylinder() return [a,b,c] // an array of shapes }

In addition, functions can be created and called, i.e. normal JavaScript.

function a(options) { // passed from main() below var w = [] w.push( sphere() ) w.push( cube(options).translate([2,0,0]) ) return w } function main() { let list = a({radius: 10}) return list }

JSCAD designs can pass parameters from one function to another, just like in the example. This is because JSCAD designs are really JavaScript.

There are a few special parameters which are important to understand.

JSCAD tries to maintain a consistent and easy to use set of functions (API). Although most functions require specific options, most have defaults and do not need to be supplied. Every function has predefined defaults, even shapes (The defaults are shown along side of examples for each function.)

Options are passed as attributes of another object. In most cases, the options are assigned a value, and bracketed with ‘{…}’.

cylinder({start: [0,0,0], end: [0,0,10], r1: 1, r2: 2, fn: 50})

Why the strange syntax? There can be lots parameters, default parameters can be skipped, order is not important, etc. This provides a lot of flexibility when creating complex designs.

When 3D vectors are required, parameters can be passed as an array. If a scalar (single value) is passed for a parameter which expects a 3D vector, the scalar is used for the x, y and z values. In other words: radius: 1 will give radius: [1,1,1].

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 |

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

JSCAD designs can pass parameters from one function to another, just like in the example. This is because JSCAD designs are really JavaScript.

There are a few special parameters which are important to understand.

JSCAD tries to maintain a consistent and easy to use set of functions (API). Although most functions require specific options, most have defaults and do not need to be supplied. Every function has predefined defaults, even shapes (The defaults are shown along side of examples for each function.)

Options are passed as attributes of another object. In most cases, the options are assigned a value, and bracketed with ‘{…}’.

cylinder({start: [0,0,0], end: [0,0,10], r1: 1, r2: 2, fn: 50})

Why the strange syntax? There can be lots parameters, default parameters can be skipped, order is not important, etc. This provides a lot of flexibility when creating complex designs.

‘3D’ stands for three (3) dimensional. A 3D primitive is any shape that has three dimensions, which are often called width, depth, and height (or X, Y, Z.) 3D shapes have a known volume if closed.

The mathematical study of 3D shapes and dimensions is called solid geometry.

All rounded shapes have a `resolution`

option which controls tesselation. If `resolution`

is set to 8, then 8 polygons are used to create 360 degrees of revolution.

This allows each design to control the amount of detail present, but beware that calculations and rendering time will also increase. For example, the number of polygons increases quadratically with each increase of the `resolution`

for spheres.

EXAMPLE

If the `resolution`

option is omitted, the following resolution is used.

- CSG.defaultResolution3D = 12

OpenSCAD like functions support the `fn`

parameter, which is the same as `resolution`

.

A three dimensional shape created from six retangular faces, each at right angles to another, and opposite faces are equal. The **cube** is a special case of the a cuboid in which all six faces are squares.

*Learn about cuboids at MathIsFun.com*

Cubes can be created at a requested center. The radius specifies the size of the faces. Cubes with different radius for X, Y and Z axis can be specified by supplying an array of values.

Defaults:

- size : 1 or [1,1,1]
- center : [0,0,0]
- radius : 0
- round: false

cube({size: 1}) cube({size: [1,2,3]}) cube({size: 1, center: true}) // default center:false cube({size: 1, center: [false,false,false]}) // individual axis center true or false cube({size: [1,2,3], round: true})

Also, the CSG library functions can be used directly. *NOTE Deprecated in the V2 API*

CSG.cube({ center: [0, 0, 0], radius: [1, 1, 1] }) CSG.cube({ // define two opposite corners corner1: [4, 4, 4], corner2: [5, 4, 2] })

Rounded cubes are created by specifying a rounded radius for the corners and the sides.

CSG.roundedCube({ // rounded cube center: [0, 0, 0], radius: 1, roundradius: 0.9, resolution: 8, });

A three dimensional shape like a ball, where every point on the surface is the same distance from the center.

*Learn about spheres at MathIsFun.com*

Creates a sphere at the requested center. The radius argument determines the size of the sphere. The resolution option determines the number of segments to create in 360 degrees of rotation.

*Note: See the start of 3D Primitives for information about the resolution of three dimenional shapes.*

Defaults:

- radius : 1 or [1,1,1]
- center : [0,0,0]
- resolution : Resolution3D (12)

sphere(1); sphere({r: 2}); // Note: center:true is default (unlike other primitives, as OpenSCAD) sphere({r: 2, center: true}); // Note: OpenSCAD doesn't support center for sphere but we do sphere({r: 2, center: [false, false, true]}); // individual axis center sphere({r: 10, fn: 100 }); sphere({r: 10, fn: 100, type: 'geodesic'}); // geodesic approach (icosahedron further triangulated)

In case of ``type: 'geodesic'`` the fn tries to match the non-geodesic fn, yet, actually changes in steps of 6 (e.g. fn=6..11 is the same), fn = 1 reveals the base form: the icosahedron.

The CSG library functions can also be used. *NOTE Deprecated in the V2 API*

CSG.sphere({ center: [0, 0, 0], radius: 2, // must be scalar resolution: 128 });

A three dimensional shape with two flat ends that are circular or elliptical. The cylinder has the same cross-section from one end to the other.

*Learn about cylinders at MathIsFun.com*

The following show examples of creating cylinders. The radius specifies the size about the axis. The resolution option determines the number of segments to create in 360 degrees of rotation.

If necessary then additional options can be provide for start and end points of the axis. As well as start and end radius.

*Note: See the start of 3D Primitives for information about the resolution of three dimensional shapes.*

Defaults:

- radius : 1 or
- radiusStart : 1
- radiusEnd : 1

- axis :
- start : [0,0,-1], end : [0,0,1]

- resolution : Resolution3D (12)

*Note: A start or end radius of 0 creates a cone.*

cylinder({r: 1, h: 10}) cylinder({r: 1, h: 10, center: true}) // default: center:false cylinder({r: 1, h: 10, center: [true, true, false]}) cylinder({r: 1, h: 10, round: true}) cylinder({r1: 3, r2: 0, h: 10}) cylinder({start: [0,0,0], end: [0,0,10], r1: 1, r2: 2, fn: 50})

The CSG library functions can also be used. *NOTE: Deprecated in the V2 API*

CSG.cylinder({ start: [0, -1, 0], end: [0, 1, 0], radius: 1, // true cylinder resolution: 16 }); CSG.cylinder({ start: [0, -1, 0], end: [0, 1, 0], radiusStart: 1, // start- and end radius defined, partial cones radiusEnd: 2, resolution: 16 }); CSG.roundedCylinder({ // and its rounded version start: [0, -1, 0], end: [0, 1, 0], radius: 1, resolution: 16 });

A three dimensional shape made by revolving a small circle (inner) along the circumference a bigger circle (outer).

*Learn about torus at MathIsFun.com*

A torus is defined as such:

- Inner Circle
- ri = inner radius
- fni = inner resolution
- roti = inner rotation

- Outer Circle
- ro = outer radius
- fno = outer resolution

Defaults:

- ri : 1
- fni : 16
- roti : 0
- ro : 4
- fno : 32

torus() torus({ ri: 1.5, ro: 3 }) torus({ ri: 0.2 }) torus({ fni:4 }) // make inner circle fn = 4 => square torus({ fni:4,roti:45 }) // rotate inner circle, so flat is top/bottom torus({ fni:4,fno:4,roti:45 }) torus({ fni:4,fno:5,roti:45 })

A three dimensional shape where connecting faces create a solid. Each face is a three dimensional polygon (a flat shape with straight sides).

*Learn about polyhedrons at MathIsFun.com*

Create a polyhedron with a list of points and a list of triangles or polygons. The point list is all the vertexes of the shape, the triangle list is how the points relates to the surfaces of the polyhedron

polyhedron({ // openscad-like (e.g. pyramid) points: [ [10,10,0],[10,-10,0],[-10,-10,0],[-10,10,0], // the four points at base [0,0,10] ], // the apex point triangles: [ [0,1,4],[1,2,4],[2,3,4],[3,0,4], // each triangle side [1,0,3],[2,1,3] ] // two triangles for square base });

Additionally you can also define `polygons: [ [0,1,4,5], [..] ]` too, not just `triangles:`.

You can also create a polyhedron at a more low-level.

var polygons = []; polygons.push(new CSG.Polygon([ new CSG.Vertex(new CSG.Vector3D(-5,-5,0)), new CSG.Vertex(new CSG.Vector3D(2,2,5)), new CSG.Vertex(new CSG.Vector3D(3,3,15)) ]) ); // add more polygons and finally: solid = CSG.fromPolygons(polygons);

‘2D’ stands for two (2) dimensional. A 2D primitive is any shape that has two dimensions, which are width and length (or X and Y.) The 2D dimensional shapes have no thickness (Although, JSCAD shows a very thin shape.)

One way of thinking about 2D shapes is anything that lays flat on a piece of paper, such as drawing a circle or a square.

The mathematical study of 2D shapes and dimensions is called plane geometry.

All rounded shapes have a `resolution`

option which controls tesselation. If `resolution`

is set to 8, then 8 polygons are used to create 360 degrees of revolution.

This allows each design to control the amount of detail present, but beware that calculations and rendering time will also increase. For example, the number of polygons increases quickly with each increase of the `resolution`

for circles.

EXAMPLE

If the `resolution`

option is omitted, the following resolution is used.

- CSG.defaultResolution2D = 32

OpenSCAD like functions support the `fn`

parameter, which is the same as `resolution`

.

A two dimensional shape made with four straight sides where all interior angles are right angles (90°).

*Learn about rectangles at MathIsFun.com*

The following show examples of creating rectangles. The radius specifies the size. Rectangles with different radius for X and Y axis can be specified by supplying an array of values.

Defaults:

- radius : 1 or [1,1]
- center : [0,0]

square(5); // square 5 x 5 square([2,3]); // rectangle 2 x 3 square({size: [2,4], center: true}); // rectangle 2 x 4, centered on both X and Y axis

The CSG library functions can also be used. *NOTE: Deprecated in the V2 API*

CAG.rectangle({center: [0,0], radius: [5, 10]}); CAG.roundedRectangle({center: [0,0], radius: [10, 50], roundradius: 1, resolution: 4});

A two dimensional shape made by drawing a curve that is always the same distance from a center. All points are the same distance from the center.

*Learn about circles at MathIsFun.com*

The following show examples of creating circles. The radius specifies the size. The resolution option determines the number of segments to create in 360 degrees of rotation.

*Note: See the start of 2D Primitives for information about the resolution of two dimensional shapes.*

Defaults:

- radius : 1
- center : [0,0]
- resolution: defaultResolution2D (32)

let c1 = circle(1) let c2 = circle({r: 2, fn:5}) // fn = number of segments to approximate the circle let c3 = circle({r: 3, center: true})

The CSG library functions can also be used. *NOTE: Deprecated in the V2 API*

let c4 = CAG.circle({center: [0,0], radius: 3, resolution: 32})

A two dimensional shape with straight sides, and the shape is “closed” (all the sides connect up).

*Learn about polygons at MathIsFun.com*

The following show examples of creating polygons from a list of points.

Defaults:

- empty

let p1 = polygon([ [0,0],[3,0],[3,3] ]) let p2 = polygon({ points: [ [0,0],[3,0],[3,3] ] })

The CSG library functions can also be used. *NOTE: Deprecated in the V2 API*

let p3 = CAG.fromPoints([ [0,0],[5,0],[3,5],[0,5] ])