@toybox-labs/cura-wasm

Cura WASM

Cura Engine powered by Web Assembly (WASM)

Features

• Supports multiple input file formats including 3MF, AMF, PLY, OBJ, and STL via the Unified 3D Loader
• Written in modern TypeScript
• Uses Rollup for JS/TS compilation
• Uses Docker for C++ compilation (Enhanced reproducibility)
• Ships with everything already compiled
• Works in the browser and on NodeJS
• Supports custom Cura Engine launch command
• Provides print metadata (Filament usage, estimated time, etc.)
• Thoroughly commented

Install

npm i cura-wasm

Usage

Exports

Cura WASM ships with both ES6 and CJS exports. The ES6 version is built with browsers in mind and likely won't work on NodeJS; the CJS version is built with NodeJS in mind and almost certainly won't work on browsers due to lacking standard modules.

Definitions

Unless you have your own 3D printer definition (That isn't included with Cura), you should use cura-wasm-definitions for 3D printer defintions.

Examples

• Basic Benchy + Ultimaker 2 example

import {CuraWASM} from 'cura-wasm';
import {resolveDefinition} from 'cura-wasm-definitions';

const main = async () =>
{
  //Create a new slicer
  const slicer = new CuraWASM({
    /**
     * Specify Cura Engine launch arguments (Identical to desktop Cura Engine).
     * 
     * If you find that "-s" overrides aren't taking effect, make sure that you
     * order your arguments correctly.
     * 
     * NOTE: You CANNOT specify both this setting and overrides!
     */
    command: 'slice -j definitions/printer.def.json -o Model.gcode -s layer_height=0.06 -l Model.stl',

    /*
     * The 3D printer definition to slice for (See the cura-wasm-definitions
     * repository or https://github.com/cloud-cnc/cura-wasm-definitions
     * for a list of built-in definitions)
     */
    definition: resolveDefinition('ultimaker2'),

    /*
     * Overrides for the current 3D printer definition (Passed to Cura Engine
     * with the -s CLI argument)
     * 
     * NOTE: You CANNOT specify both this setting and launch arguments!
     */
    overrides: [
      {
        /*
         * The scope of the setting. (Passed to Cura Engine with a leading
         * hyphen before the corresponding -s argument)
         */
        scope: 'e0',

        //The override's key/name
        key: 'mesh_position_x',

        //The override's value
        value: -10
      }
    ],

    /**
     * Wether or not to transfer the input STL ArrayBuffer to the worker thread
     * (Prevents duplicating large amounts of memory but empties the ArrayBuffer
     * on the main thread preventing other code from using the ArrayBuffer)
     */
    transfer: true,

    /*
     * Wether to enable verbose logging (Useful for debugging; allows Cura
     * Engine to directly log to the console)
     */
    verbose: true
  });

  //Load your STL as an ArrayBuffer
  const res = await fetch('/demo/benchy.stl');
  const stl = await res.arrayBuffer();

  //Progress logger (Ranges from 0 to 100)
  slicer.on('progress', percent =>
  {
    console.log(`Progress: ${percent}%`);
  });

  //Slice (This can take multiple minutes to resolve!)
  const {gcode, metadata} = await slicer.slice(stl, 'stl');

  //Do something with the GCODE (ArrayBuffer) and metadata (Object)

  //Dispose (Reccomended but not necessary to call/intended for SPAs)
  slicer.dispose();
}
main();

• Multiple browser examples can be found in the demo and tests/web directory (Which is used for browser tests).
• Multiple NodeJS examples can be found in the tests/node directory.

Performance

The performance is decent but not great. If you're running NodeJS, consider using native Cura Engine instead unless you want the isolation from the WASM VM.

Note: Cura Engine uses OpenMP for multithreading, however, Emscripten doesn't support OpenMP.

Name	Slice Time
NodeJS V15.2.0	7782ms
Chrome 86.0.4240.193	6615ms
Firefox 82.0.3	6581ms
Native Cura Engine V4.6.1	2259ms

Note: All runtimes were benchmarked 6 times then averaged. The benchmarking computer ran Windows 10 Pro 20H2 (19042.610), with a Ryzen 7 3700X, 32GB DDR4-3600MHZ (CL16), NVMe Gen 4 SSD.

Low level API

You can directly import CuraEngine.js from the src directory. It's directly built by Emscripten but be warned: it will choke up the calling thread hence the need for Threads JS.

FAQ

How does it work?

Cura WASM uses emscripten to compile Cura Engine to Web Assembly.

Depending on the input file format, Cura WASM uses the Unified 3D Loader to convert any non-STL file to an STL file. Emscripten provides a virtual filesystem with which Cura WASM loads the STL file into as well as the 3D printer definitions. Cura WASM includes a very small modification to Cura Engine which makes it call the global worker progress function alerting Cura WASM when the progress updates so it can pass it along to the API consumer.

Hasn't this been done before?

Yes, this is by no means the first time someone has compiled Cura Engine to run in the browser. Previous projects include gyf304/cura-emscripten, nelsonsilva/CuraEngine-em, Skeen/CuraJS-Engine, and possibly more. However, none of these are maintained and only one (CuraJS) is meant to be used as a library - not a stand-alone application.

Can I contribute?

Yes. If you're looking for something specific to help with, I'd greatly appreciate any help with making Cura Engine run faster, tightening the JS/TS <---> C++ coupling (eg: improved Cura Engine error reporting), and improving the JS/TS API.

What's the license?

Cura WASM relies on Cura Engine which uses AGPL3+ and Cura which which uses LGPL3+ hence the AGLP3+/LGPL3+ license requirement. With that said, the AGLP3+ license only applies to CuraEngine.js, the LGPL3+ license only applies to all files in the src directory excluding index.ts. All other files use the MIT licensed.

License Obligations

Upstream Modifications

Minor modifications to Cura Engine to get it to compile and for progress logging (See docker/CuraEngine.patch for exact modifications). All definitions are used verbatim.

Source

The sources are located at github.com/ultimaker/curaengine, github.com/ultimaker/cura, github.com/cloud-cnc/cura-wasm-definitions.