JSCAD Basics

Learn the fundamental concepts and syntax for creating 3D models with JSCAD.

Basic Code Structure

Every JSCAD file follows a simple structure with a main function that returns geometry.

// Import JSCAD functions
const { cube, sphere, cylinder } = require('@jscad/modeling').primitives
const { translate, rotate, scale } = require('@jscad/modeling').transforms
const { union, subtract, intersect } = require('@jscad/modeling').booleans

// Main function - this is what gets executed
function main() {
  // Your geometry code goes here
  return cube({size: 10})
}

// Export the main function
module.exports = { main }

Imports

Import the functions you need from JSCAD modules

Main Function

Define your geometry in the main() function

Export

Export the main function for JSCAD to use

Geometric Primitives

Primitives are the basic building blocks of 3D geometry. JSCAD provides several types of primitives.

Cube

Creates a rectangular box with specified dimensions.

Basic Usage

// Simple cube
const cube1 = cube({size: 10})

// Cube with specific dimensions
const cube2 = cube({
  size: [10, 20, 5]
})

// Cube centered at origin
const cube3 = cube({
  size: 10,
  center: [0, 0, 0]
})

Parameters

size - Number or array [x, y, z]
center - Boolean or array [x, y, z]

Tip: Use size: [x, y, z] for non-uniform dimensions.

Sphere

Creates a perfect sphere with specified radius and resolution.

Basic Usage

// Simple sphere
const sphere1 = sphere({radius: 5})

// High-resolution sphere
const sphere2 = sphere({
  radius: 5,
  segments: 32
})

// Sphere with custom center
const sphere3 = sphere({
  radius: 5,
  center: [10, 0, 0]
})

Parameters

radius - Number (default: 1)
segments - Number (default: 16)
center - Array [x, y, z] (default: [0, 0, 0])

Note: Higher segment counts create smoother spheres but increase file size.

Cylinder

Creates a circular cylinder with specified radius, height, and resolution.

Basic Usage

// Simple cylinder
const cylinder1 = cylinder({radius: 5, height: 10})

// Cylinder with segments
const cylinder2 = cylinder({
  radius: 5,
  height: 10,
  segments: 32
})

// Cylinder with different top/bottom radius
const cylinder3 = cylinder({
  radius: [5, 3], // [bottom, top]
  height: 10
})

Parameters

radius - Number or array [bottom, top]
height - Number
segments - Number (default: 16)
center - Array [x, y, z] (default: [0, 0, 0])

Tip: Use different top/bottom radii to create cones or tapered cylinders.

Torus

Creates a donut-shaped object with specified outer radius, inner radius, and resolution.

Basic Usage

// Simple torus
const torus1 = torus({outerRadius: 5, innerRadius: 1})

// High-resolution torus
const torus2 = torus({
  outerRadius: 5,
  innerRadius: 1,
  outerSegments: 32,
  innerSegments: 16
})

// Torus with custom center
const torus3 = torus({
  outerRadius: 5,
  innerRadius: 1,
  center: [10, 0, 0]
})

Parameters

outerRadius - Number (distance from center)
innerRadius - Number (thickness of ring)
outerSegments - Number (default: 16)
innerSegments - Number (default: 8)
center - Array [x, y, z] (default: [0, 0, 0])

Note: innerRadius must be smaller than outerRadius.

Transformations

Transformations modify the position, orientation, and size of geometric objects.

Translate

Moves an object to a new position in 3D space.

Basic Usage

// Move along X axis
const moved1 = translate([10, 0, 0], cube({size: 5}))

// Move along multiple axes
const moved2 = translate([5, 10, 2], sphere({radius: 3}))

// Move relative to current position
const moved3 = translate([0, 0, 5], cylinder({radius: 2, height: 10}))

Parameters

offset - Array [x, y, z] (translation vector)
object - Geometry to translate

Tip: Use negative values to move in the opposite direction.

Rotate

Rotates an object around specified axes by given angles.

Basic Usage

// Rotate around Z axis (90 degrees)
const rotated1 = rotate([0, 0, Math.PI/2], cube({size: 5}))

// Rotate around multiple axes
const rotated2 = rotate([Math.PI/4, 0, Math.PI/6], sphere({radius: 3}))

// Rotate around custom center
const rotated3 = rotateX(Math.PI/2, cylinder({radius: 2, height: 10}))

Parameters

angles - Array [x, y, z] (radians)
object - Geometry to rotate

Note: Angles are in radians. Use Math.PI/2 for 90 degrees.

Scale

Resizes an object by scaling factors along each axis.

Basic Usage

// Uniform scaling
const scaled1 = scale(2, cube({size: 5}))

// Non-uniform scaling
const scaled2 = scale([1, 2, 0.5], sphere({radius: 3}))

// Scale from custom center
const scaled3 = scale([2, 2, 2], cylinder({radius: 2, height: 10}))

Parameters

factors - Number or array [x, y, z]
object - Geometry to scale

Tip: Use values less than 1 to shrink, greater than 1 to enlarge.

Boolean Operations

Boolean operations combine multiple objects using mathematical set operations.

Union

Combines multiple objects into a single object, removing overlaps.

Basic Usage

// Combine two objects
const combined = union(
  cube({size: 10}),
  sphere({radius: 5})
)

// Combine multiple objects
const complex = union(
  cube({size: 10}),
  translate([5, 0, 0], sphere({radius: 3})),
  translate([0, 5, 0], cylinder({radius: 2, height: 8}))
)

Use Cases

• Combining multiple parts
• Creating complex assemblies
• Building up geometry
• Merging overlapping objects

Tip: Union is the most common Boolean operation for combining parts.

Subtract

Removes the volume of one object from another object.

Basic Usage

// Create a hole
const withHole = subtract(
  cube({size: 10}),
  cylinder({radius: 2, height: 12})
)

// Create multiple holes
const withHoles = subtract(
  cube({size: 10}),
  union(
    translate([-2, -2, 0], cylinder({radius: 1, height: 12})),
    translate([2, 2, 0], cylinder({radius: 1, height: 12}))
  )
)

Use Cases

• Creating holes and cutouts
• Removing unwanted material
• Creating complex cavities
• Subtracting support structures

Note: The first object is the base, the second is what gets removed.

Intersect

Keeps only the volume where objects overlap.

Basic Usage

// Keep only overlap
const overlap = intersect(
  cube({size: 10}),
  sphere({radius: 6})
)

// Complex intersection
const complex = intersect(
  cube({size: 10}),
  translate([5, 0, 0], sphere({radius: 8})),
  translate([0, 5, 0], cylinder({radius: 4, height: 12}))
)

Use Cases

• Creating complex cuts
• Limiting geometry to bounds
• Creating precise intersections
• Complex geometric constraints

Tip: Intersect is useful for creating precise geometric constraints.

Complete Example

Here's a complete example that demonstrates all the basic concepts:

const { cube, sphere, cylinder } = require('@jscad/modeling').primitives
const { translate, rotate, scale } = require('@jscad/modeling').transforms
const { union, subtract } = require('@jscad/modeling').booleans

function main() {
  // Create base plate
  const base = cube({size: [20, 20, 2]})
  
  // Create central cylinder
  const centerCylinder = translate([0, 0, 1], 
    cylinder({radius: 3, height: 8})
  )
  
  // Create corner spheres
  const corner1 = translate([8, 8, 1], sphere({radius: 2}))
  const corner2 = translate([-8, 8, 1], sphere({radius: 2}))
  const corner3 = translate([8, -8, 1], sphere({radius: 2}))
  const corner4 = translate([-8, -8, 1], sphere({radius: 2}))
  
  // Create holes in base
  const holes = union(
    translate([8, 8, 0], cylinder({radius: 1, height: 3})),
    translate([-8, 8, 0], cylinder({radius: 1, height: 3})),
    translate([8, -8, 0], cylinder({radius: 1, height: 3})),
    translate([-8, -8, 0], cylinder({radius: 1, height: 3}))
  )
  
  // Combine everything
  const result = union(
    subtract(base, holes),
    centerCylinder,
    corner1, corner2, corner3, corner4
  )
  
  return result
}

module.exports = { main }

Create base plate with holes

Add central cylinder

Add corner spheres

Ready for More?

Now that you understand the basics, explore these advanced topics:

Parameter System

Learn to create parametric designs with dynamic parameters.

Group Objects

Organize your designs with groups and child imports.