OpenJSCAD.org Documentation

The @jscad/vtree repository contains experimental implementations aimed at speeding up JSCAD design computation times. The core goal is to move away from recomputing the entire geometry every time a variable changes by implementing a tree-based approach similar to a virtual DOM.

Key concepts explored include:

• Tree Generation: Generating a tree structure of object nodes (containing metadata like dimensions and operands) instead of direct geometry.
• Decoupling: Separating the API from the geometric implementation.
• Caching: Using hashes of JSON-based nodes to cache generated geometry. This allows for 3X to 10X speedups during re-evaluation of scripts.
• Cache Invalidation: Implementing a counter-based system to remove unused geometry/hashes from the in-memory cache after each pass.

JSCAD provides several ways to use its parametric 2D and 3D modeling tools depending on your workflow:

• Browser-based modeling: No installation required. Use the web interface at https://openjscad.xyz/.
• Command Line Interface (CLI): Install via NPM as part of a project for automated or terminal-based workflows.
• Modular Integration: Use individual JSCAD packages available on NPM under the @jscad scope or via the GitHub repository.

JSCAD can be used in three primary ways depending on your workflow:

1. In-browser application: The easiest way to start. Visit https://openjscad.xyz/ to use the web-based modeling interface.
2. Stand-alone application: A dedicated desktop application.
3. Command-line tool: For automated or script-based workflows.

In all modes, you provide a JavaScript file that programmatically describes your 3D model. The output can be exported in STL, AMF, DXF, JSON, and X3D formats.

JSCAD projects can be organized as a folder structure rather than a single file. This allows you to modularize your design by creating helper methods, tools, and sub-modules.

A standard project folder structure includes:

• A main entry point file (defaults to index.js).
• A package.json file to define project metadata and the entry point.
• Additional JavaScript module files that use module.exports to provide functionality.
• External assets like STL, AMF, or SVG files that can be imported into the design.

To make a JSCAD design parametric (allowing users to adjust dimensions or properties via a UI), you must export a getParameterDefinitions function alongside your main function.

1. Define getParameterDefinitions to return an array of objects describing the parameters.
2. The main function receives a params object containing the values selected by the user.
3. Use these values within your modeling logic to drive geometry creation.

const jscad = require('@jscad/modeling')
const { cuboid } = jscad.primitives

const getParameterDefinitions = () => {
  return [
    {name: 'width', caption: 'Width:', type: 'float', initial: 100},
  ];
}

const main = (params) => {
  return cuboid({
    size: [params.width, 10, 10],
    center: [0, 0, 0]
  });
}

module.exports = { main, getParameterDefinitions }

You can install the JSCAD CLI either globally for general use or as a development dependency within a specific project.

Global Installation

To install the CLI globally using NPM:

npm install -g @jscad/cli

Once installed, you can invoke it using jscad.

Project-specific Installation

To install the CLI as a development dependency in your project:

cd myproject
npm install -D @jscad/cli

In this case, invoke the CLI using npx jscad.

To maintain clean and idiomatic JSCAD code, follow these conventions:

• Use Arrow Functions: Prefer const func = () => { ... } over function func() { ... }.
• Object Shorthand: Use { radius, height } instead of { radius: radius, height: height } when creating objects.
• Destructuring: Use const { radius, height } = options instead of accessing properties individually.

To use the translator in a browser, include lib/underscore.js and dist/web-built.js in your HTML. This exposes the openscadOpenJscadParser object.

  <script src="../dist/web-built.js"></script>

  <script type="text/javascript">
    var text = document.getElementById('txt').innerText
    console.log(openscadOpenJscadParser.parse(text))
  </script>