jscad-scad-api

This packages provides a OpenSCAD-like API. See OpenSCAD User Manual

This allows OpenSCAD designs to be ported to JSCAD, and gives OpenSCAD designers a slightly easier learning experience. However, OpenSCAD designs still need to be converted to JSCAD (and JavaScript).

Usage

This package can be used by any JSCAD design by importing the required functions.

import {circle, rotate_extrude, linear_extrude, translate} from "jscad-scad-api"

export const main = (params) => {
  let s1 = circle()
  let s2 = translate({v: [3, 3]}, s1)

  let s3 = rotate_extrude({fn: 8, angle: -270}, s2)

  return [s1, s2, s3]
}

Implementation Notes

OpenSCAD is based on some bazzare non-procedural language, while JSCAD is 100% JavaScript. A lot of language constructs are the same but there will be some pain, and learning required.

This package doesn't try to reproduce OpenSCAD, but does provide most of the functionality found in OpenSCAD. The main difference is that the 'named' parameters are required. This shouldn't be hard but OpenSCAD designs may need some changes. For example, OpenSCAD translate([1,2,3]) needs to be changed to translate(v=[1,2,3])

2D Objects

| Shape | Parameters | Notes | | ------- | ------------- | ----------- | | circle | r, d | | | polygon | points, paths | | | square | size, center | | | text | | UNSUPPORTED |

NOTE: JSCAD also supports arc, ellipse, line, roundedRectangle, star, and triangle.

3D Objects

| Shape | Parameters | Notes | | ---------- | ------------------------------- | ----------- | | cube | size, center | | | sphere | r, d | | | cylinder | h, r, r1, r2, d, d1, d2, center | | | polyhedron | points, faces | | | surface | | UNSUPPORTED |

NOTE: JSCAD also supports cylinderElliptic, ellipsoid, geodesicSphere, roundedCuboid, and torus.

Transforms

| Function | Parameters | Notes | | -------------- | ----------------- | ----------- | | color | c | | | rotate | a, v | | | translate | v | | | mirror | v | | | multmatrix | m | | | scale | v | | | resize | newsize, auto | | | offset | r, delta, chamfer | | | minkowski | | | | hull | | |

NOTE: JSCAD also supports align and center.

Measurements

No such thing in OpenSCAD.

NOTE: JSCAD supports measurements of area, bounding box, bounding sphere, center, center of mass, dimensions, and volume.

Dimension Changes 2D/3D

| Function | Parameters | Notes | | -------------- | --------------------------------------- | ----------- | | projection | cut | | | linear_extrude | height, v, center, twist, slices, scale | | | rotate_extrude | angle | |

NOTE: JSCAD also supports extrudeHelical and extrudeRectangular.

Boolean Combinations

| Function | Parameters | Notes | | ------------ | ---------- | ----- | | union | | | | difference | | | | intersection | | |

NOTE: JSCAD also supports scission.

Mathematical Functions

• cos
• sin
• tan
• acos
• asin
• atan
• atan2
• abs
• ceil
• concat
• cross
• exp
• floor
• ln
• len
• log
• lookup
• max
• min
• norm
• pow
• rands
• round
• sign
• sqrt

String Functions

| Function | Parameters | Notes | | -------- | ---------- | ----- | | str | ...values | | | chr | number | | | ord | string | |

String Functions

| Function | Parameters | Notes | | -------- | ---------- | ----- | | str | ...values | | | chr | number | | | ord | string | |

Type Test Functions

| Function | Parameters | Notes | | --------- | ---------- | ----- | | is_undef | value | | | is_bool | value | | | is_num | value | | | is_string | value | | | is_list | value | |

Language Features

| Function | Parameters | Notes | | ----------- | ---------- | ----- | | assert | ...values | | | echo | ...values | | | search | | UNSUPPORTED | | version | | | | version_num | | |

If you don't see a function above then it's not supported, or the JavaScript language may have the same construct.

• jscad-scad-api
  • .circle ⇒ Geom2
  • .color ⇒ Object | Array
  • .cube ⇒ Geom3
  • .cylinder ⇒ Geom3
  • .difference ⇒ Object
  • .assert
  • .echo
  • .version
  • .version_num
  • .forAction ⇒
  • .hull ⇒ Object
  • .intersection ⇒ Object
  • .linear_extrude ⇒ Geom3
  • .minkowski ⇒ Object
  • .mirror ⇒ Object | Array
  • .multimatrix ⇒ Object | Array
  • .offset ⇒ Object | Array
  • .polygon ⇒ Geom2
  • .polyhedron ⇒ Geom3
  • .resize ⇒ Object
  • .rotate_extrude ⇒ Geom3
  • .rotate ⇒ Object | Array
  • .scale ⇒ Object | Array
  • .sphere ⇒ Geom3
  • .square ⇒ Geom2
  • .str
  • .is_undef ⇒ Boolean
  • .vector_char ⇒ Object
  • .vector_text ⇒ Array
  • .translate ⇒ Object | Array
  • .union ⇒ Object

jscad-scad-api.circle ⇒ Geom2

Creates a circle at the origin.

If used, $fa, $fs and $fn must be named parameters.

Kind: static constant of jscad-scad-api
Returns: Geom2 - new 2D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.r] | Float | 1 | radius of the circle | | [options.d] | Float | 0 | if provided, diameter of the circle where d = r * 2 |

Example

let circle1 = circle({r: 10})
let circle2 = circle({d: 20})
let circle3 = circle({r: 15, $fa: 12, $fs: 2})
let circle4 = circle({r: 10, $fn: 6})

jscad-scad-api.color ⇒ Object | Array

Displays the elements using the specified RGB color.

The color is specfified using RGBA values from 0 to 1. The alpha value defaults to 1.0 (opaque) if not specified.

The color can also be defined by name (case insensitive).

Kind: static constant of jscad-scad-api
Returns: Object | Array - the colored element, or a list of colored elements

| Param | Type | Description | | --- | --- | --- | | color | Object | either an array or a hex string of color values | | ...elements | Object | the elements to color |

Example

let color1 = color([1,0,0,1], sphere())
let color2 = color("red", sphere())

jscad-scad-api.cube ⇒ Geom3

Creates a cube.

When center is true, the cube is centered on the origin.

Kind: static constant of jscad-scad-api
Returns: Geom3 - new 3D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.size] | Float | [1,1,1] | size of each side (X, Y, Z), or a single size | | [options.center] | Boolean | false | wether to center the cube/cuboid or not |

Example

let cube1 = cube({size: 10})
let cube2 = cube({size: [5, 10, 20]})
let cube2 = cube({size: [5, 5, 3], center: true})

jscad-scad-api.cylinder ⇒ Geom3

Creates a cylinder centered vertically about the Z axis.

When center is true, it is also centered vertically along the Z axis.

If used, $fa, $fs and $fn must be named parameters.

Kind: static constant of jscad-scad-api
Returns: Geom3 - new 3D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.h] | Float | 1 | height of the cylinder | | [options.r1] | Float | 1 | radius of the top of the cylinder | | [options.r2] | Float | 1 | radius of the bottom of the cylinder | | [options.r] | Float | 0 | if provided, r = r1 = r2 | | [options.d] | Float | 0 | if provided, diameter of the cylinder, d = r1 * 2 = r2 * 2 | | [options.d1] | Float | 0 | if provided, diameter of the top of the cylinder, d1 = r1 * 2 | | [options.d2] | Float | 0 | if provided, diameter of the bottom of the cylinder, d2 = r2 * 2 | | [options.center] | Boolean | false | wether to center the cylinder about Z axis or not |

Example

let cylinder1 = cylinder({r: 10})
let cylinder2 = cylinder({d: 20})
let cylinder3 = cylinder({h: 10, r1: 10, r2: 5})
let cylinder4 = cylinder({h: 10, d1: 20, d2: 10})
let cylinder5 = cylinder({h: 10, r1: 10, r2: 0, $fn: 32})

jscad-scad-api.difference ⇒ Object

Subtracts all elements from the first element (logical AND NOT).

NOTE: The given elements should be of the same type, i.e. 2D or 3D elements.

Kind: static constant of jscad-scad-api
Returns: Object - the difference of the elements

| Param | Type | Description | | --- | --- | --- | | ...elements | Object | the elements to subtract from the first |

Example

let newshape = difference(sphere(), cube())

jscad-scad-api.assert

Assert that the result is true.

If not then an error with the given message is thrown, and processing stops.

Kind: static constant of jscad-scad-api

jscad-scad-api.echo

Echo (print) the contents to the console, which is useful for debugging code.

Kind: static constant of jscad-scad-api
See: str()

jscad-scad-api.version

Return the version as a vector of three numbers.

Kind: static constant of jscad-scad-api

jscad-scad-api.version_num

Return the version as a number, e.g. 20240401.

Kind: static constant of jscad-scad-api

jscad-scad-api.forAction ⇒

Evaluate each value in a set of vectors, or each name in the attributes, applying it to the given function.

This is bascially a replacement for the SCAD for-loop.

Kind: static constant of jscad-scad-api
Returns: Array of new geometry, i.e. what every is produced from the given function.

| Param | Type | Description | | --- | --- | --- | | where | Object | each attribute has a list of values | | function | function | (call-back) of which to execution for each value |

jscad-scad-api.hull ⇒ Object

Create a convex hull around the given elements.

NOTE: The given elements should be of the same type, i.e. 2D or 3D elements.

Kind: static constant of jscad-scad-api
Returns: Object - the convex hall of the elements

| Param | Type | Description | | --- | --- | --- | | ...elements | Object | the elements to hull |

Example

let hulled = hull(square(), circle())

jscad-scad-api.intersection ⇒ Object

Creates the intersection all elements (logical AND). Only the area which is common or shared by all children is retained.

NOTE: The given elements should be of the same type, i.e. 2D or 3D elements.

Kind: static constant of jscad-scad-api
Returns: Object - the intersection of the elements

| Param | Type | Description | | --- | --- | --- | | ...elements | Object | the elements to intersect |

Example

let newshape = intersection(sphere(), cube())

jscad-scad-api.linear_extrude ⇒ Geom3

Generate a 3D shape by extruding a 2D object about the Z-axis.

Kind: static constant of jscad-scad-api
Returns: Geom3 - new extruded shape

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | options for extruding | | [options.height] | Float | 100 | height of the extruded shape | | [options.slices] | Integer | 8 | number of intermediary steps | | [options.twist] | Integer | 0 | angle in which to twist the extusion about the Z-axis | | [options.scale] | Integer | 0.0 | scale to acheive for the final the shape | | [options.center] | Boolean | false | whether to center the final 3D shape |

Example

let shape1 = linear_extrude({height: 10}, square())

jscad-scad-api.minkowski ⇒ Object

Compute the Minkowski sum of two 3D geometries.

NOTE: The given elements should be of the same type, i.e. 2D or 3D elements.

Kind: static constant of jscad-scad-api
Returns: Object - the minkowski sum of the elements

| Param | Type | Description | | --- | --- | --- | | ...elements | Object | the elements to sum |

Example

let newshape = minkowski(cube(), sphere())

jscad-scad-api.mirror ⇒ Object | Array

Transforms the object into a mirror of the original, as if it were the mirror image seen through a plane intersecting the origin.

Kind: static constant of jscad-scad-api
Returns: Object | Array - the mirrored object, or a list of mirrored objects

| Param | Type | Description | | --- | --- | --- | | options | Object | options for mirror | | options.v | Float | Array | the perpendicular, normal vector of the plane passing through the origin | | ...objects | Object | the objects to mirror |

Example

let mirrored1 = mirror({v: [1, 0, 0]}, cube()) // mirror about the X axis

jscad-scad-api.multimatrix ⇒ Object | Array

Transforms the object using the given affine transformation matrix.

The fourth row of the matrix is forced to [0,0,0,1] and can be omitted.

Kind: static constant of jscad-scad-api
Returns: Object | Array - the transformed object, or a list of transformed objects

| Param | Type | Description | | --- | --- | --- | | options | Object | options for multmatrix | | options.m | Array | affine transformation matrix, where the matrix is 4×3 or 4x4 array | | ...objects | Object | the objects to transform |

Example

const c = cube()
const m = multimatrix([
    [cos(angle), -sin(angle), 0, 10],
    [sin(angle),  cos(angle), 0, 20],
    [         0,           0, 1, 30],
    [         0,           0, 0,  1]
  ], c)

jscad-scad-api.offset ⇒ Object | Array

Offset generates a new interior or exterior outline from an existing element.

There are two modes of operation; radial and offset. The radial method creates a new outline as if a circle of some radius is rotated around the exterior (r>0) or interior (r<0) original outline. The offset method creates a new outline whose sides are a fixed distance outer (delta > 0) or inner (delta < 0) from the original outline.

If used, $fa, $fs and $fn must be named parameters.

Kind: static constant of jscad-scad-api
Returns: Object | Array - the offset element, or a list of offset elements

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for centering | | [options.r] | Float | | the radius of the circle that is rotated about the outline | | [options.delta] | Boolean | 1 | the distance of the new outline from the original outline | | [options.chamfer] | Boolean | false | defines if edges should be chamfered (delta mode only) | | ...elements | Object | | the elements to offset |

Example

const o = offset({r: 10}, square(20))

jscad-scad-api.polygon ⇒ Geom2

Create a multiple sided shape from a list of coordinates (X, Y).

This includes irregular shapes with both concave and convex edges.

Construct a polygon either from arrays of paths and points, or just arrays of points nested paths (multiple paths) and flat paths are supported.

Kind: static constant of jscad-scad-api
Returns: Geom2 - new 2D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.paths] | Array | [] | paths of the polygon : either flat or nested array | | [options.points] | Array | [] | points of the polygon : either flat or nested array |

Example

let poly1 = polygon({points: [[10,11], [0,11], [5,20]]})
let poly2 = polygon({points: [[10,11], [0,11], [5,20]], paths: [[0, 1, 2]]})

jscad-scad-api.polyhedron ⇒ Geom3

Create a mulitple faceted polyhedron from a list of points and faces.

Each face is a list containing the indices of three or more points from the points. Faces may be defined in any order. Define enough faces to fully enclose the solid, with no overlap.

Kind: static constant of jscad-scad-api
Returns: Geom3 - new 3D geometry

| Param | Type | Description | | --- | --- | --- | | [options] | Object | options for construction | | [options.points] | Array | array of points (X, Y, Z) of which to construct the polyhedron | | [options.faces] | Array | array of faces, where each face contains three or more indices |

Example

const polyhedron1 = polyhedron({
  points: [ [10,10,0], [10,-10,0], [-10,-10,0], [-10,10,0], // the four points at base
            [0,0,10] ],                                     // the apex point
  faces: [ [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
})

jscad-scad-api.resize ⇒ Object

Modifies the dimensions of the element to match the new size.

If auto resizing is enabled then each zero(0) size will be taken from the first non-zero size.

Kind: static constant of jscad-scad-api
Returns: Object - the resized element

| Param | Type | Description | | --- | --- | --- | | options | Object | options for resizing | | options.newsize | Float | Array | either single number or an array of numbers, specifying the new sizes | | [options.auto] | Array | an array of true / false values, specifying if autosizing should occur | | element | Object | the element to resize |

Example

let resized1 = resize({newsize=[5,5], square()) // resize 2D element
let resized2 = resize({newsize=[5,5,5], cube())
let resized3 = resize({newsize=[5,0,0], auto: [false, true, false], cube())

jscad-scad-api.rotate_extrude ⇒ Geom3

Rotational extrusion spins a 2D shape around the Z-axis to form a solid which has rotational symmetry.

If used, $fa, $fs and $fn must be named parameters.

Kind: static constant of jscad-scad-api
Returns: Geom3 - new 3D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.angle] | Float | 360 | number of degrees to sweep, starting at the positive X axis. The direction of the sweep is counterclockwise, hence a negative angle sweeps clockwise. |

Example

const e = rotate_extrude({convexity: 10}, translate([2, 0, 0], circle({r: 1})))

jscad-scad-api.rotate ⇒ Object | Array

Rotates the objects about the axis, or around an arbitrary axis.

When 'a' (angles) is an array, the 'v' (axis) argument is ignored. When 'a' (angles) is a number, the rotation is about the Z axis.

Kind: static constant of jscad-scad-api
Returns: Object | Array - the rotated object, or a list of rotated objects

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | options for centering | | options.a | Float | Array | | either single number or an array of numbers, specifying angles of rotation | | [options.v] | Array | [0,0,1] | a vector [X, Y, Z] that defines an arbitrary axis for rotation | | ...objects | Object | | the objects to rotate |

Example

let rotated1 = rotate({a: 45}, square()) // rotate 2D objects about the Z axis
let rotated2 = rotate({{a: [45, 180, -90]}, cube())
let rotated3 = rotate({{a: [45, 180, -90], v: [0, 1, 0]}, cube())

jscad-scad-api.scale ⇒ Object | Array

Scale the elements using the specified vector.

Kind: static constant of jscad-scad-api
Returns: Object | Array - the scaled element, or a list of scaled elements

| Param | Type | Description | | --- | --- | --- | | options | Object | options for centering | | options.v | Array | a vector that defines the factors of scale | | ...elements | Object | the elements to scale |

Example

let scaled1 = scale({v: [10, 2]}, square()) // scale 2D element
let scaled2 = scale({v: [10, 2, 3]}, sphere())

jscad-scad-api.sphere ⇒ Geom3

Creates a sphere at the origin.

If used, $fa, $fs and $fn must be named parameters.

Kind: static constant of jscad-scad-api
Returns: Geom3 - new 3D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.r] | Float | 1 | radius of the sphere | | [options.d] | Float | 0 | if provided, diameter of the sphere where d = r * 2 |

Example

let sphere1 = sphere({r: 10})
let sphere2 = sphere({d: 20})
let sphere3 = sphere({r: 15, $fa: 12, $fs: 2})
let sphere4 = sphere({r: 15, $fn: 32})

jscad-scad-api.square ⇒ Geom2

Creates a square or rectangle.

When center is true the square is centered on the origin.

Kind: static constant of jscad-scad-api
Returns: Geom2 - new 2D geometry

| Param | Type | Default | Description | | --- | --- | --- | --- | | [options] | Object | | options for construction | | [options.size] | Float | [1,1] | size of the square, either as array or scalar | | [options.center] | Boolean | false | wether to center the square/rectangle or not |

Example

let square1 = square({size: [x, y], center: true})
let square2 = square({size: x})

jscad-scad-api.str

Convert all arguments to strings and concatenated.

NOTE: Arguments are concatenated as given, no spaces added.

Kind: static constant of jscad-scad-api

jscad-scad-api.is_undef ⇒ Boolean

Determine if the give value is undefined.

Kind: static constant of jscad-scad-api
Returns: Boolean - true if the given value is null or undefined

| Param | Type | Description | | --- | --- | --- | | value | Any | value to test |

Example

if (is_undef(exploded)) ...

jscad-scad-api.vector_char ⇒ Object

Construct a with, segments tupple from a character

Kind: static constant of jscad-scad-api
Returns: Object - { width: X, segments: [...] }

| Param | Type | Description | | --- | --- | --- | | x | Float | x offset | | y | Float | y offset | | char | Float | character |

Example

let charData = vector_char(0, 12.2, 'b')

jscad-scad-api.vector_text ⇒ Array

Construct an array of with, segments tupple from a string

Kind: static constant of jscad-scad-api
Returns: Array - [{ width: X, segments: [...] }]

| Param | Type | Description | | --- | --- | --- | | x | Float | x offset | | y | Float | y offset | | string | Float | string |

Example

let stringData = vector_text(0, 12.2, 'b')

jscad-scad-api.translate ⇒ Object | Array

Translate the elements along the specified vector.

Kind: static constant of jscad-scad-api
Returns: Object | Array - the translated element, or a list of translated elements

| Param | Type | Default | Description | | --- | --- | --- | --- | | options | Object | | options for translating | | [options.v] | Array | [0,0,0] | a vector that defines the movement in position | | ...elements | Object | | the elements to translate |

Example

let moved1 = translate({v: [10, 2]}, square()) // translate 2D element
let moved2 = translate({v: [10, 2, 0]}, sphere())

jscad-scad-api.union ⇒ Object

Creates a union of all elements (logical OR). This is the sum of all elements.

NOTE: The given elements should be of the same type, i.e. 2D or 3D elements.

Kind: static constant of jscad-scad-api
Returns: Object - the union of the elements

| Param | Type | Description | | --- | --- | --- | | ...elements | Object | the elements to union |

Example

let newshape = union(sphere(), cube())