{"id":15480,"library":"replicad-opencascadejs","title":"OpenCascade.js Custom Build for Replicad","description":"replicad-opencascadejs is a specialized, minified build of opencascade.js, which itself is a JavaScript and WebAssembly port of the Open CASCADE Technology (OCCT) CAD kernel. This package is specifically tailored to include only the necessary APIs for the replicad library, aiming to significantly reduce the overall bundle size and improve load times for web-based 3D modeling applications. The current stable version, as per the request, is 0.23.0, though npm often shows slightly older versions like 0.20.2 or 0.21.0 as most recently published, indicating an irregular release cadence tied to upstream opencascade.js updates and replicad's needs. Its key differentiator is providing a lightweight, optimized WebAssembly CAD backend for replicad, enabling efficient browser-based parametric 3D design without the full footprint of the generic opencascade.js library. It leverages the robust geometry capabilities of OCCT, exposed through a developer-friendly API for code-driven 3D model generation.","status":"active","version":"0.23.0","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","typescript"],"install":[{"cmd":"npm install replicad-opencascadejs","lang":"bash","label":"npm"},{"cmd":"yarn add replicad-opencascadejs","lang":"bash","label":"yarn"},{"cmd":"pnpm add replicad-opencascadejs","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"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.","wrong":"const initOpenCascade = require('replicad-opencascadejs');","symbol":"initOpenCascade","correct":"import initOpenCascade from 'replicad-opencascadejs';"},{"note":"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)`.","symbol":"OC","correct":"const OC = await initOpenCascade();"},{"note":"`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.","symbol":"setOC","correct":"import { setOC } from 'replicad';"}],"quickstart":{"code":"import initOpenCascade from 'replicad-opencascadejs';\nimport { setOC, Sketcher, Extrude, FaceFinder, makeCylinder } from 'replicad';\n\nasync function initializeAndCreateModel() {\n  console.log('Initializing replicad-opencascadejs...');\n  // The locateFile option is often needed to point to the .wasm file if not in the root\n  const OC = await initOpenCascade({\n    locateFile: (path) => {\n      if (path.endsWith('.wasm')) {\n        // Adjust this path based on your project's build setup\n        return `/path/to/replicad-opencascadejs.wasm`;\n      }\n      return path;\n    },\n  });\n  setOC(OC);\n  console.log('OpenCascade initialized and injected into replicad.');\n\n  // Example: Create a simple cylindrical body with a hole\n  const baseCylinder = makeCylinder(10, 30);\n\n  const holeSketch = new Sketcher('XY')\n    .circle(3)\n    .translate([0, 0, 15]) // Center the hole along the cylinder's height\n    .extrude(35, { direction: [0, 0, 1] });\n\n  const finalShape = baseCylinder.cut(holeSketch);\n\n  // You would typically use a viewer or export this shape\n  // For demonstration, we'll log a representation (e.g., its volume or type)\n  const volume = finalShape.getVolume();\n  console.log(`Created a shape with volume: ${volume.toFixed(2)} units³`);\n\n  // In a browser environment, you might render it:\n  // const modelViewerElement = document.getElementById('model-viewer');\n  // if (modelViewerElement) {\n  //   const stlBlob = await finalShape.toStl();\n  //   const url = URL.createObjectURL(stlBlob);\n  //   modelViewerElement.src = url;\n  // }\n\n  // Clean up if needed, though OC is often long-lived\n  // OC.Module.clean(); // This depends on opencascade.js API\n  return finalShape;\n}\n\ninitializeAndCreateModel().catch(console.error);\n","lang":"typescript","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure you are using `import initOpenCascade from 'replicad-opencascadejs';` for ESM environments. Verify your build system correctly handles default exports.","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).","error":"TypeError: initOpenCascade is not a function"},{"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.","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.","error":"WebAssembly.instantiate(): Compilation failed: expected magic word 0x0061736d"},{"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.","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)`.","error":"Error: replicad has not been initialised. Please run `setOC(opencascade)` first"}],"ecosystem":"npm"}