@polar3d/gcode-viewer

A lightweight, framework-agnostic G-code viewer built with Three.js. Parse and visualize G-code files with support for layer-by-layer viewing, 3D tube rendering, color themes, and print information extraction.

⚠️ License & Attribution Requirement

IMPORTANT: This package requires visible attribution. This is required by the license and cannot be removed.

See LICENSE for full terms.

Features

- 🆕 3D Tube Rendering: Realistic visualization with continuous tube geometry (eliminates z-fighting)
- 🆕 Color Themes: 5 built-in color themes (Default, Ocean, Forest, Sunset, Monochrome) + custom colors
- 🆕 Standalone Parser & Renderer: Use parser and renderer independently for custom integrations
- 🆕 G2/G3 Arc Support: Full support for clockwise/counter-clockwise arc moves (I/J and R formats)
- 🆕 Thumbnail Extraction: Extract embedded thumbnails from G-code files (PNG/QOI formats)
- Layer-by-layer visualization: Navigate through print layers with a simple API
- Path type detection: Automatically detects and colors different path types (perimeter, infill, support, etc.)
- Multiple slicer support: Works with PrusaSlicer, Cura, BambuSlicer, OrcaSlicer, Simplify3D, and IdeaMaker
- Slicer detection: Automatically detects which slicer generated the G-code
- Multi-tool support: Handles multi-extruder printers with tool changes
- Print info extraction: Extracts estimated time, filament usage, and dimensions
- Color schemes: Switch between path-type coloring and height-gradient coloring
- Purge line filtering: Automatically filters out purge/intro lines
- Travel move toggle: Show/hide travel moves

Installation

``bash
npm install @polar3d/gcode-viewer three
`

Usage

$3

`typescript
import * as THREE from 'three';
import { GCodeViewer } from '@polar3d/gcode-viewer';

// Get your viewer container
const container = document.getElementById('viewer-container');
container.style.position = 'relative';

// Create viewer with container
const viewer = new GCodeViewer({
container,
lineWidth: 2,
hidePurgeLines: true,
colorScheme: 'pathType',
showTravelMoves: false,
});

// Parse G-code
const gcodeText = await fetch('model.gcode').then(r => r.text());
const result = viewer.parse(gcodeText);

// Add to your Three.js scene
scene.add(result.object);
`

$3

Enable realistic 3D visualization with continuous tube geometry:

`typescript
const viewer = new GCodeViewer({
container,
renderTubes: true, // Enable 3D tube rendering
extrusionWidth: 0.4, // Extrusion width in mm
lineHeight: 0.2, // Layer height in mm
radialSegments: 4, // Tube quality (4-8 recommended)
});

const result = viewer.parse(gcodeText);
scene.add(result.object);
`

Benefits of tube rendering:
- More realistic visualization of extrusion paths
- No z-fighting flickering (continuous geometry)
- Better visual distinction between layers

$3

For custom integrations, you can use the parser and renderer separately:

`typescript
import { GCodeParser, GCodeRenderer } from '@polar3d/gcode-viewer';
import * as THREE from 'three';

// Parse G-code
const parser = new GCodeParser();
const parseResult = parser.parse(gcodeText);

// Access parsed data
console.log('Total layers:', parseResult.layers.length);
console.log('Slicer:', parseResult.metadata.slicer);
console.log('Has thumbnails:', parseResult.thumbnails.length > 0);
console.log('Bounding box:', parseResult.boundingBox);

// Create renderer with your options
const renderer = new GCodeRenderer({
renderTubes: true,
extrusionWidth: 0.4,
lineHeight: 0.2,
});

// Render parsed data
const object3D = renderer.render(parseResult.layers);
scene.add(object3D);
`

Thumbnail Extraction:

`typescript
const parser = new GCodeParser();
const result = parser.parse(gcodeText);

// Get thumbnails (PNG or QOI format)
for (const thumbnail of result.thumbnails) {
console.log(Thumbnail: ${thumbnail.width}x${thumbnail.height});
console.log(Format: ${thumbnail.format});

// For PNG thumbnails, create data URL for display
if (thumbnail.format === 'png') {
const base64 = btoa(String.fromCharCode(...thumbnail.data));
const dataUrl = data:image/png;base64,${base64};
// Use in img src
}
}
`

Metadata & Slicer Detection:

`typescript
const result = parser.parse(gcodeText);

// Access metadata
console.log('Slicer:', result.metadata.slicer);
console.log('Estimated time:', result.metadata.estimatedTime);
console.log('Filament used:', result.metadata.filamentUsed);
console.log('Layer height:', result.metadata.layerHeight);
console.log('Nozzle diameter:', result.metadata.nozzleDiameter);

// Bounding box for camera setup
const bbox = result.boundingBox;
console.log('Print size:', bbox.max.x - bbox.min.x, 'x', bbox.max.y - bbox.min.y, 'x', bbox.max.z - bbox.min.z);
`

G2/G3 Arc Support:

The parser automatically handles G2 (clockwise) and G3 (counter-clockwise) arc commands:

`gcode
G2 X10 Y10 I5 J0 ; Arc using I/J center offsets
G3 X20 Y20 R5 ; Arc using R radius
`

Arcs are interpolated into smooth curves for accurate visualization.

$3

Apply different color themes to your visualization:

`typescript
import { GCodeViewer, COLOR_THEMES } from '@polar3d/gcode-viewer';

const viewer = new GCodeViewer({
container,
renderTubes: true,
customColors: COLOR_THEMES[1].colors, // Ocean theme
});

// Or set theme dynamically
viewer.setCustomColors(COLOR_THEMES[2].colors); // Forest theme
`

Available themes:
| Theme | Description |
|-------|-------------|
| default | Original vibrant colors |
| ocean | Cool blue/teal tones |
| forest | Natural green/brown tones |
| sunset | Warm red/orange/pink tones |
| monochrome | Grayscale |

Custom colors:

`typescript
viewer.setCustomColors({
outer_perimeter: '#FF0000',
inner_perimeter: '#00FF00',
infill: '#0000FF',
// ... other path types
});
`

$3

`typescript
const viewer = new GCodeViewer();

// Set container before parsing
viewer.setContainer(document.getElementById('viewer-container'));

const result = viewer.parse(gcodeText);
`

$3

`tsx
import { useRef, useEffect } from 'react';
import { GCodeViewer } from '@polar3d/gcode-viewer';

function GCodeViewerComponent({ gcodeText }) {
const containerRef = useRef(null);
const viewerRef = useRef(null);

useEffect(() => {
if (containerRef.current && gcodeText) {
// Create viewer with container and tube rendering
viewerRef.current = new GCodeViewer({
container: containerRef.current,
renderTubes: true,
});
const result = viewerRef.current.parse(gcodeText);
// ... add to Three.js scene
}

return () => {
viewerRef.current?.dispose();
};
}, [gcodeText]);

return (