OpenCascade.js Custom Build for Replicad

Common errors

• TypeError: initOpenCascade is not a function

  cause The import statement for replicad-opencascadejs is incorrect (e.g., using `require` in an ESM context, or attempting a named import when it's a default export).
  fix Ensure you are using `import initOpenCascade from 'replicad-opencascadejs';` for ESM environments. Verify your build system correctly handles default exports.

• WebAssembly.instantiate(): Compilation failed: expected magic word 0x0061736d

  cause The browser or Node.js environment could not find or correctly load the `.wasm` file. This often happens if the `locateFile` option in `initOpenCascade` is misconfigured, or the WASM file is not deployed to the correct path on the server/CDN.
  fix Adjust the `locateFile` function passed to `initOpenCascade` to return the correct URL path for the `replicad-opencascadejs.wasm` file. Ensure the `.wasm` file is deployed to that accessible path relative to your application's entry point.

• Error: replicad has not been initialised. Please run `setOC(opencascade)` first

  cause The `replicad` library attempts to perform a CAD operation (e.g., creating a `Sketcher` instance or a shape) before the `opencascade.js` WebAssembly module has been initialized and its core `OC` object injected into `replicad` via `setOC(OC)`.
  fix Ensure that the asynchronous `initOpenCascade()` call has completed and `setOC(OC)` has been successfully executed *before* any `replicad` functions that depend on the CAD kernel are invoked. Wrap your `replicad` logic in an `async` function and `await` the initialization.

Warnings

• breaking The underlying opencascade.js library, and by extension replicad-opencascadejs, has undergone significant breaking changes in previous major versions (e.g., in beta releases leading to v1.x). These often involve changes to API conventions, especially around static methods and supported classes, due to updates in the Emscripten build process and OpenCascade Technology (OCCT) versions. Users should consult the specific changelogs for opencascade.js if encountering issues with the underlying CAD kernel.
  Fix: Always check the `opencascade.js` and `replicad` release notes when upgrading for specific API adjustments. Review console errors carefully for clues about method or class deprecations.
• gotcha Loading the WebAssembly module can be time-consuming and block the main thread, especially for complex models or older devices. For optimal user experience, it is strongly recommended to load and execute CAD computations within a Web Worker.
  Fix: Implement a Web Worker to handle the `initOpenCascade` call and all subsequent `replicad` operations that involve heavy computation. Transfer results back to the main thread for rendering or display.
• gotcha Custom builds of `replicad-opencascadejs` or `opencascade.js` require Docker and `ytt` for configuration file generation. Directly using the npm package avoids this build-time dependency, but attempting to modify or rebuild the WASM module without these tools will fail.
  Fix: Ensure Docker and `ytt` are installed and correctly configured if you intend to create or modify custom `opencascade.js` builds. For standard usage, simply install the `replicad-opencascadejs` npm package.
• gotcha OpenCascade Technology (OCCT) itself has a known limitation called the 'Topological Naming Problem' (TNP). When a model is modified in a way that changes its topology (e.g., adding a hole, filleting an edge), the internal identifiers for faces, edges, and vertices can change. While `replicad` introduces 'finders' to mitigate this for higher-level operations, direct interaction with the underlying OCCT objects via `replicad-opencascadejs` might expose this issue.
  Fix: When using raw OCCT calls (if ever), avoid relying on fixed indices or names for topological elements across modifications. Use `replicad`'s higher-level abstractions and 'finders' (e.g., `FaceFinder`, `EdgeFinder`) where possible, as they are designed to provide more robust referencing.

Install

• npm install replicad-opencascadejs npm
• yarn add replicad-opencascadejs yarn
• pnpm add replicad-opencascadejs pnpm

Imports

• initOpenCascade
  wrong:

  const initOpenCascade = require('replicad-opencascadejs');

  correct:

  import initOpenCascade from 'replicad-opencascadejs';

  This package is designed for ESM imports. The default export is the WebAssembly initialization function, typically named `initOpenCascade` or `opencascade`. This function loads the WASM module asynchronously.
• OC

  const OC = await initOpenCascade();

  The `initOpenCascade` function returns a Promise that resolves to the initialized OpenCascade (OC) object, which provides access to the underlying CAD kernel's functions. This object is then typically injected into the `replicad` library using `setOC(OC)`.
• setOC

  import { setOC } from 'replicad';

  `setOC` is not exported by `replicad-opencascadejs` itself, but by `replicad`. It's crucial for integrating the initialized `replicad-opencascadejs` instance with the `replicad` library for actual CAD operations.

Quickstart

This quickstart demonstrates how to asynchronously initialize replicad-opencascadejs, inject the resulting OC object into replicad using `setOC`, and then use replicad's API to construct a basic 3D shape (a cylinder with a hole). It highlights the core integration pattern for browser-based CAD applications.

import initOpenCascade from 'replicad-opencascadejs';
import { setOC, Sketcher, Extrude, FaceFinder, makeCylinder } from 'replicad';

async function initializeAndCreateModel() {
  console.log('Initializing replicad-opencascadejs...');
  // The locateFile option is often needed to point to the .wasm file if not in the root
  const OC = await initOpenCascade({
    locateFile: (path) => {
      if (path.endsWith('.wasm')) {
        // Adjust this path based on your project's build setup
        return `/path/to/replicad-opencascadejs.wasm`;
      }
      return path;
    },
  });
  setOC(OC);
  console.log('OpenCascade initialized and injected into replicad.');

  // Example: Create a simple cylindrical body with a hole
  const baseCylinder = makeCylinder(10, 30);

  const holeSketch = new Sketcher('XY')
    .circle(3)
    .translate([0, 0, 15]) // Center the hole along the cylinder's height
    .extrude(35, { direction: [0, 0, 1] });

  const finalShape = baseCylinder.cut(holeSketch);

  // You would typically use a viewer or export this shape
  // For demonstration, we'll log a representation (e.g., its volume or type)
  const volume = finalShape.getVolume();
  console.log(`Created a shape with volume: ${volume.toFixed(2)} units³`);

  // In a browser environment, you might render it:
  // const modelViewerElement = document.getElementById('model-viewer');
  // if (modelViewerElement) {
  //   const stlBlob = await finalShape.toStl();
  //   const url = URL.createObjectURL(stlBlob);
  //   modelViewerElement.src = url;
  // }

  // Clean up if needed, though OC is often long-lived
  // OC.Module.clean(); // This depends on opencascade.js API
  return finalShape;
}

initializeAndCreateModel().catch(console.error);