Cascade Studio Documentation

Cascade Studio provides several specialized APIs for programmatic 3D modeling:

Sketch API

Allows drawing sketches on specific planes. You can specify the plane using a parameter like new Sketch([x,y], 'XZ') to draw in the XZ plane.

Selector API

Used for querying specific geometric entities like edges and faces within a shape. For example, you can find indices of faces that are parallel to a specific vector and have a maximum value in a certain direction: Edges(shape).parallel([0,0,1]).max([0,0,1]).indices()

Measurement Functions

Provides geometric analysis for shapes:

• Volume(): Returns the volume of the shape.
• SurfaceArea(): Returns the surface area.
• CenterOfMass(): Returns the center of mass.

OpenCASCADE Access

For advanced users, the full OpenCASCADE kernel is accessible via the oc. namespace.

To set up the Cascade Studio development environment and run the browser-based IDE locally, follow these steps:

1. Install dependencies.
2. Build the project (this builds cascade-core first, then cascade-studio).
3. Serve the built distribution using a local HTTP server.

After running these commands, open http://localhost:8080 in your browser.

npm install
npm run build
npx http-server ./packages/cascade-studio/dist -p 8080 -c-1

Install the cascade-core package via npm to use the headless CAD modeling engine in your web application.

npm install cascade-core

To use cascade-core, initialize a CascadeEngine with the path to your worker file, initialize it, and then evaluate CAD code. The engine returns mesh data that can be rendered using WebGL frameworks like Three.js or Babylon.js.

Important: You must copy cascade-worker.js, cascadestudio.wasm, and the fonts/ directory from node_modules/cascade-core/dist/ to your project's static assets directory for the engine to function.

import { CascadeEngine } from 'cascade-core';

const engine = new CascadeEngine({ workerUrl: './cascade-worker.js' });
await engine.init();

const result = await engine.evaluate(`
  let box = Box(20, 20, 20);
  FilletEdges(box, 3, Edges(box).max([0,0,1]).indices());
`, { guiState: { 'Cache?': true } });

// result.meshData = { faces: [...], edges: [...] }
// Render with Three.js, Babylon.js, or any WebGL framework

The cascade-core package provides the CAD engine as a standalone library without GUI dependencies. It is designed to be used in your own applications (e.g., rendering with Three.js or Babylon.js).

To use it, instantiate CascadeEngine, initialize it, and use engine.evaluate() to run CAD code. The result contains meshData (faces and edges) which can be passed to a WebGL framework.

import { CascadeEngine } from 'cascade-core';

const engine = new CascadeEngine({ workerUrl: './cascade-worker.js' });
await engine.init();

const result = await engine.evaluate(`
  let box = Box(20, 20, 20);
  FilletEdges(box, 3, Edges(box).max([0,0,1]).indices());
`, { guiState: { 'Cache?': true } });

// result.meshData = { faces: [...], edges: [...] }

The repository includes a Playwright test suite that covers primitives, transforms, booleans, operations, selectors, OpenSCAD, and exports.

Note: WebGL rendering in headless mode requires specific flags (--use-gl=angle --use-angle=swiftshader) which are pre-configured in playwright.config.js.

npm run build
npx playwright test

The CAD engine uses two global variables to manage objects for rendering:

• sceneShapes: An array of oc.TopoDS_Shape objects that are rendered in the view. When creating new shapes or importing files, you must push them to this array to make them visible.
• externalShapes: A dictionary storing imported STEP and IGES files, keyed by their filename. To render an imported file, push it from this dictionary into sceneShapes.

Example of rendering an imported STEP file:

sceneShapes.push(externalShapes['myStep.step']);

The CascadeAPI class provides a programmatic interface for interacting with the Cascade Studio environment. It is specifically designed for use by AI agents (e.g., via Playwright) and developer tooling to automate CAD modeling tasks.

To use it, the API must be installed on the window object via CascadeAPI.install().

To use CascadeEngine, you must first instantiate it with a workerUrl pointing to your worker script and then call init(). The init() method loads the Web Worker and WASM modules, and it resolves only when the worker signals it is ready via a startupCallback.

const engine = new CascadeEngine({ workerUrl: './cascade-worker.js' });
await engine.init();