gcode-preview - v3.0.0-alpha.6
    Preparing search index...

    gcode-preview - v3.0.0-alpha.6

    GCode Preview npm version MIT license

    A simple G-code parser & viewer lib with 3D printing in mind. Written in Typescript.

    Join us on discord

    11-11-2024 This repo was moved to a brand new org which is a collaboration between @remcoder and @sophiedeziel for everything 3D printing related.

    • multi-color
    • tube geometry
    • g2/g3 arcs
    • streaming (progressive rendering from a ReadableStream)
    • thumbnail preview
    • build volume
    • orthographic camera
    • slicer detection (PrusaSlicer family, Cura, Simplify3D, Slic3r)
    • per-path extrusion width & line height from ;WIDTH: / ;HEIGHT: slicer comments (adaptive layer height)
    • drag & drop
    • examples for various frameworks
    image

    try it out: https://codepen.io/remcoder/pen/PwYVXBg

    Click to see the full-fledged demo:

    image

    npm install gcode-preview

    GCode Preview depends on three.js and supports three >=0.166.0 <0.186.0.

    The package is ESM-only. Import from gcode-preview; the only other public package path is gcode-preview/package.json. Deep imports such as gcode-preview/dist/gcode-preview.es.js are no longer supported, and the legacy UMD build / GCodePreview browser global has been removed.

    TypeScript supports node16, nodenext, and bundler module resolution. Legacy moduleResolution: "node" can still resolve the root import through types; no typesVersions mapping is needed for the current root-only API.

    For native browser modules, map three in an import map and load dist/gcode-preview.es.js as a module. When self-hosting, copy the entire dist directory, including any chunks. The debug GUI (lil-gui) is bundled, so it needs no separate install or import-map entry. The GUI remains synchronous; bundling adds roughly 9 KB gzipped even when devMode is disabled.

      import { GCodePreview } from 'gcode-preview';

      const preview = new GCodePreview({
          canvas: document.querySelector('canvas'),
          extrusionColor: 'hotpink'
      });
      
      // draw a diagonal line
      const gcode = 'G0 X0 Y0 Z0.2\nG1 X42 Y42 E10';
      preview.processGCode(gcode);

    G-code can also be streamed in and rendered progressively:

      const response = await fetch('benchy.gcode');
      await preview.processGCodeStream(response.body);

    The main options accepted by new GCodePreview({ ... }) (see the API docs for the full reference):

    • canvas — the canvas element to render to
    • buildVolume — renders the build volume (see below)
    • colors: backgroundColor, extrusionColor, travelColor, topLayerColor, lastSegmentColor, boundingBoxColor
    • render toggles: renderExtrusion, renderTravel, renderTubes, disableGradient
    • geometry: lineWidth, lineHeight, extrusionWidth — per-path dimensions from ;WIDTH: / ;HEIGHT: slicer comments always win (adaptive layer height renders correctly); lineHeight / extrusionWidth fill in for paths without them, and built-in defaults (0.6 width / 0.2 height) apply last
    • layer range: startLayer, endLayer
    • camera: orthographic, initialCameraPosition
    • streaming: liveRenderInterval (throttles progressive rendering)
    • arcs: arcChordTolerance (tessellation precision for G2/G3)
    • misc: droppable (drag & drop g-code files onto the canvas), devMode (debug GUI + stats), keepLines, minLayerThreshold

    After construction, most rendering properties live on the scene manager and can be changed at runtime, e.g. preview.sceneManager.renderTubes = true, followed by a re-render.

    Check the full API documentation at https://gcode-preview.web.app/docs

    Vue.js / React / Svelte integration

    There's a Vue.js example that has a Vue component to wrap the library.

    @Zeng95 provided a React & Typescript example that has a React component to wrap the library.

    There is a Svelte example with a Svelte component.

    The interpreter currently handles:

    Command Meaning
    G0 / G1 linear move
    G2 / G3 clockwise / counter-clockwise arc
    G20 / G21 set units to inches / millimeters
    G28 home
    G31 straight probe
    G38.2–G38.5 probe family
    G92 set position
    G92.1 reset coordinate system offsets
    T0–T7 tool selection

    Commands without a handler are parsed but ignored by the interpreter.

    G92.2 and G92.3 are not supported. Standalone ;WIDTH:<mm> and ;HEIGHT:<mm> comments (emitted by PrusaSlicer, SuperSlicer, OrcaSlicer and Bambu Studio) are picked up by the slicer metadata pipeline and set the extrusion width and line height of the paths that follow, so prints sliced with adaptive layer height render with the true dimensions of each path. Dimensions resolve per path: the slicer-announced value wins, the lineHeight / extrusionWidth options fill in for paths without one, and the built-in defaults (0.6 width / 0.2 height) apply last.

    GCode files that were sliced for a multi-tool system can be previewed as such. Pass an array of colors as the extrusionColor constructor option (or assign preview.sceneManager.extrusionColor at runtime), where the index in the array corresponds to the index of the tool: T0..T7.

    example:

    extrusionColor: ['hotpink', 'indigo', 'lime']

    Here, T0 is hotpink, T1 is indigo and T2 is lime.

    image

    Supported systems include:

    • Prusa MMU1/2/3 and XL
    • Bambulab AMS & AMS lite
    • Enraged Rabbit Carrot Feeder (ERCF)
    • IDEX machines
    • toolchangers
    • 3D Chameleon
    • Virtual tools (color mixing)
    • and possibly more

    Extrusions are rendered as tubes by default; pass renderTubes: false as a constructor option to render flat lines (it can also be toggled at runtime via preview.sceneManager.renderTubes):

    new GCodePreview({ canvas, renderTubes: false });

    Thanks to @Sindarius arc commands are now supported, which means gcode processed by ArcWelder should be rendered correctly.

    Thumbnail previews as generated by PrusaSlicer are detected and parsed. In the gcode these are found in comments, enclosed between 'thumbnail begin' and 'thumbnail end'. The images are encoded as base64 strings but split over multiple lines. These are now parsed and patched back together, but still kept a base64. This allows easy use in the browser for us as data urls.

    image Thumbnail Preview as generated by PrusaSlicer

    The thumbnails can be accessed like this: gcodePreview.parser.metadata.thumbnails['220x124']

    Thumbnails have a .src property that will create a usable data url from the base64 string.

    See an example in the demo source.

    The build volume will be rendered if the buildVolume parameter is passed. It has the following type:

    buildVolume: { 
      x: number; 
      y: number; 
      z: number;
      smallGrid?: boolean;
    }

    Negative dimensions are clamped to 0.

    example:

    To develop on gcode-preview run:

    npm i && npm run dev

    This runs the demo app which is fairly complete in using the libs features.

    If you don't need the demo app, just run npm run dev:watch.

    Both build a dev bundle in the dist directory. Note the dev bundle:

    • is not minified
    • has no type defs (.d.ts)

    See CONTRIBUTING.md for the full guidelines. In short, before submitting a PR run:

    • npm run check (test + typeCheck + lint)
    • npm run build for a production build
    • npm run test:coverage — CI requires 100% coverage for every file under src/

    To auto-fix simple issues:

    • npm run lint:fix or npm run prettier:fix

    For working on production builds you can use:

    • npm run demo which does a prod build and launches the demo app using local server
    • or just npm run build or npm run build:watch

    If you have found a bug or if have an idea for a feature, don't hesitate to create an issue on GitHub or talk to us on Discord.

    Want to help out? We are open to your ideas and always willing to get you started! talk to us on Discord.

    • maybe there is an open issue that appeals to you?
    • other things that are always helpful:
      • testing different gcode files, from different slicers
      • reporting bugs! Screenshot == ❤️
      • making GCode Preview suitable for different printer types, like Deltas, Belt printers, IDEX, etc. Even CNC machines
      • documentation & examples
      • unit tests
    • ❤️ Thank you @0xTHAC0 for adding the orthographic camera.
    • ❤️ Thank you @sophiedeziel for rendering extrusion as tubes and creating a new interpreter.
    • ❤️ Thank you @RickRyan26 and @Sindarius for implementing G2/G3 arc support.
    • ❤️ Thank you @Zeng95 for providing a React & Typescript example.
    • ❤️ Thank you @raulodev for parser and preview fixes.
    • ❤️ Thank you @TimTheBig for dependency and tooling updates.

    This is caused by the device recognition shield in Brave. By changing the setting for "Device Recognition" in Shield settings to "Allow all device recognition attemps" or "Only block cross-site device recognition attemps" you should not get this error. https://github.com/mrdoob/three.js/issues/16904

    A big thanks to these sponsors for their contributions.

    If you want to show gratitude you can always buy me beer/coffee/filament via ko-fi or PayPal ^_^

    This project is licensed under the MIT License.

    Settings
    Member Visibility

    On This Page
    GCode Preview npm version MIT license