User Tools

Anatomy of a Design

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

Parameter Passing

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.

Passing Options

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.

Passing Vectors

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


As designs grow in complexity, the need for smaller, reusable parts becomes apparent. This is the time to consider using a “project”.

Projects are simple directories, containing several files (parts) of the design. For example, a project for a RC car design would have various parts. And the reusable parts can be separated out.

  • …/rc-car
    • chassis.js
    • body.js
    • tire.js
    • index.js

The 'index' within the project is the entry point of the project. The main function of this piece is to create each of the pieces, move the pieces into position, and return the complete design. And by convention, exports the main function.

const chassis = require('./chassis')
const body = require('./body')
const tire = require('./tire')
const main = (params) => {
  const partA = chassis(params)
  const partB = body(params)
  const tires = [
  return [partA, partB, tires]
module.exports = { main }

Design Parameters

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;

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

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.