gcode-preview-element

@chestnutlabs/gcode-preview-element

A framework-free <gcode-preview> Web Component for the Chestnut Labs G-code viewer — a thin custom-element shell over @chestnutlabs/gcode-preview-core, the same engine the Vue/React/Svelte adapters wrap. Use it from plain HTML, Angular, or any framework — no peer framework dependency.

Install

npm install @chestnutlabs/gcode-preview-element three

three is a peer dependency of the underlying renderer.

Usage

<script type="module">
  import '@chestnutlabs/gcode-preview-element/define'; // registers <gcode-preview>

  const el = document.querySelector('gcode-preview');
  el.addEventListener('ready', (e) => console.log('parsed', e.detail));
  document.querySelector('input[type=file]').addEventListener('change', (ev) => {
    el.source = ev.target.files[0]; // a File / Uint8Array / ArrayBuffer
  });
</script>

<gcode-preview quality="tubes" show-travel="false" style="width: 100%; height: 70vh"></gcode-preview>

Prefer explicit registration? Import the function instead of the side-effectful entry:

import { defineGcodePreview } from '@chestnutlabs/gcode-preview-element';
defineGcodePreview(); // idempotent; defaults to the <gcode-preview> tag

Surface

Scalar options are attributes (also settable as properties); rich options are properties.

Attribute	Property	Type	Default
quality	quality	'auto' | 'lines' | 'tubes'	'auto'
renderer	renderer	'3d' | '2d' — construction-time	'3d'
adjacent-layers	adjacentLayers	integer (2D ghost layers) — construction-time	—
camera-mode	cameraMode	'perspective' | 'orthographic'	'perspective'
show-travel	showTravel	"true" | "false"	true
show-retractions	showRetractions	"true" | "false"	false
scrub	scrub	integer	— (all)
layer-range	layerRange	"start,end" / [number, number]	— (all)
hidden-feature-roles	hiddenFeatureRoles	"6,7" / number[] — hide roles (Skirt, Brim…)	—
—	source	Uint8Array | ArrayBuffer | File	null
—	colorMode	ColorMode	—
—	theme	Theme	—
—	tube	TubeOptions — construction-time	—
—	buildVolume	BuildVolumeDef | MachineGeometry	—
—	progress	ProgressObservation | null	null
—	createWorker	() => WorkerLike	batteries default

source is a property only (never a URL attribute) — the element does not fetch. colorMode, theme, tube, and buildVolume are property-only because objects can't be HTML attributes — set them as JS properties. hidden-feature-roles gates on capabilities.featureRoles (declarative form of controls.setFeatureRoleVisible). This is a ~24-option surface; the rest of the declarative props (qualityMode, view, cameraState, frameContent, scrubTime, showWipe, showVolumeCage, interactionQuality, parseOptions, rendererOptions, layerRange) are set the same way.

DOM events (CustomEvent, kebab-case detail)

ready · camerachange · parse-error · parse-cancelled · parse-progress · stage · build-complete · disclosure · quality-fallback · progress-presentation-changed · machine-geometry-discovered · machine-geometry-mismatch · error.

A few event details are DOM-wrapped, an accepted custom-element idiom: disclosure detail is { text }, machine-geometry-discovered is { machine }, and machine-geometry-mismatch is { message }.

The underlying handle is also exposed as instance members (state, controls, raw, onEvent, parse, observeProgress, tickProgress, clearProgress, capture) for advanced use — the same neutral controller surface the other adapters expose. controls reaches the imperative extras — getRenderStats() (render diagnostics), pickSegment(ndcX, ndcY, threshold?) (source-mapping / picking), and isColorModeAvailable(mode); capture(opts?) (image Blob) is both a top-level method and controls.capture. The handle state carries capability-aware UI data (availableColorModes, hasRetractions, hasColorChanges).

Model viewing (Prepare side)

The /model/define entry registers <gcode-model-viewer> — the Prepare-side counterpart to <gcode-preview> (the tag deliberately avoids the reserved <model-viewer>). Where <gcode-preview> draws the toolpath (how a print runs), <gcode-model-viewer> draws the source model (an .stl / .3mf mesh) — the object before slicing.

<script type="module">
  import '@chestnutlabs/gcode-preview-element/model/define'; // registers <gcode-model-viewer>

  const el = document.querySelector('gcode-model-viewer');
  el.addEventListener('ready', (e) => console.log(e.detail.objectCount, e.detail.materials));
  el.source = { kind: '3mf', bytes }; // rich options are properties; primitives are attributes
</script>

<gcode-model-viewer background="transparent" style="width: 100%; height: 70vh"></gcode-model-viewer>

The ready event carries the honest material-colour tier: e.detail.materials is 'known' / 'approximated' when the file declared colours the render used, and 'unavailable' when it declared none (a neutral default, never faked). The same attribute/property split as <gcode-preview> applies — rich options (.source, .cameraState, .renderScope, …) are properties; primitives (view, background, camera-mode) are attributes. See docs/manual/adapters.md "Two viewers: Preview and Prepare" for the cross-adapter tour, and tools/example-webcomponent/model.html for a runnable minimal page.

Examples

tools/example-webcomponent in the repository is a framework-free Vite app with two tiers, both driving this published element (no raw renderer or parser imports):

• minimal.html — the smallest real integration: import /define to register <gcode-preview>, set the source property, listen for ready; the layer slider drives the layer-range attribute. Shows the attribute/property split in ~40 lines.
• showcase.html — the full surface in vanilla JS: objects (source, colorMode, hiddenFeatureRoles) set as properties, primitives (layer-range, view) as attributes; capability-gated color modes; getRenderStats()/pickSegment() diagnostics via element.controls.

Run it with npm install --prefix tools/example-webcomponent && npm run dev --prefix tools/example-webcomponent (port 5204).

Workers

By default the batteries worker parses off-thread. To supply a custom/slim worker, set the createWorker factory property (see the Vue README for the shared worker notes). The element passes the same behavioral parity suite as the Vue/React/Svelte adapters.