Modern TypeScript/JavaScript implementation of the core FullControl design + G-code generation pipeline. Browser-first, Node supported. Mirrors the authoritative Python library; primary development occurs in Python and this package tracks released Python features.
Runtime Support: Node 16+ (ES2020 output) and modern evergreen browsers.
FullControl JS follows the FullControl python codebase in every way including function names and snake_case. Refer to the FullControl official repo, examples, and documentation for the best up to date information on the library.
📚 View the API Reference for a complete, searchable list of all exported classes, methods, and geometry helpers.
npm install fullcontrol-jsimport { Point, Printer, Extruder, ExtrusionGeometry, transform } from 'fullcontrol-js'
const printer = new Printer({ print_speed: 1800, travel_speed: 6000 })
const extruder = new Extruder({ units: 'mm', dia_feed: 1.75, relative_gcode: false, travel_format: 'G1_E0' })
const geom = new ExtrusionGeometry({ area_model: 'rectangle', width: 0.45, height: 0.2 })
// Simple square path (extruding)
const z = 0.2
const path = [
new Point({ x: 0, y: 0, z, extrude: false }),
new Point({ x: 20, y: 0, z, extrude: true }),
new Point({ x: 20, y: 20, z, extrude: true }),
new Point({ x: 0, y: 20, z, extrude: true }),
new Point({ x: 0, y: 0, z, extrude: true })
]
const { gcode } = transform([printer, extruder, geom, path])
console.log(gcode)- Mutable model objects (
Point,Extruder,Printer, etc.) - Geometry helpers (polar, move, reflect, arcs, segmentation, shapes, waves…)
- Extrusion geometry area models: rectangle, stadium, circle, manual
- G-code pipeline: movement + extrusion E accumulation (absolute or relative)
- Visualization pipeline: Structured plot data with path segmentation, color gradients, and bounding box calculation
- Manual / command list G-code insertion + inline comments
- Design export/import (JSON) + class registry hook
- Per-move feedrate appended only when changed (Printer sets
speed_changedinternally via pointspeedoverride). Extruder.units:mm3: E equals volumetric mm^3 (ratio = 1)mm: E equals filament length; ratio computed fromdia_feeddiameter
Extruder.relative_gcode = trueresets volume reference after each move.travel_format: 'G1_E0'appendsE0on non-extrusion moves (useful for some slicer conventions).
| Model | Parameters | Formula |
|---|---|---|
| rectangle | width, height | width * height |
| stadium | width, height | (width - height)*height + PI*(height/2)^2 |
| circle | diameter | PI*(d/2)^2 |
| manual | area (set directly) | (unchanged) |
Call ExtrusionGeometry.update_area() automatically handled in pipeline when geometry present.
import { export_design, import_design } from 'fullcontrol-js'
const steps = [printer, extruder, geom, path]
const json = export_design(steps)
// Provide your own registry mapping type name -> class
const registry = { Printer, Extruder, ExtrusionGeometry, Point }
const restored = import_design(registry, json)Generate structured plot data for external rendering:
import { Point, transform } from 'fullcontrol-js'
const steps = [
new Point({ x: 0, y: 0, z: 0 }),
new Point({ x: 10, y: 0, z: 0 }),
new Point({ x: 10, y: 10, z: 0 }),
]
// Generate visualization data
const result = transform(steps, 'plot', {
raw_data: true,
color_type: 'print_sequence'
})
// Access structured data
const plotData = result.plot.toJSON()
console.log(plotData)
// {
// paths: [{
// xvals: [0, 10, 10],
// yvals: [0, 0, 10],
// zvals: [0, 0, 0],
// colors: [[0, 1, 1], [0.5, 0.5, 1], [1, 0, 1]],
// widths: [0.4, 0.4, 0.4],
// heights: [0.2, 0.2, 0.2],
// extruder: true
// }],
// boundingBox: { minx: 0, maxx: 10, ... },
// annotations: []
// }z_gradient(default): Blue (low Z) → Red (high Z)print_sequence: Cyan (start) → Magenta (end)print_sequence_fluctuating: Oscillating rainbow colorsrandom_blue: Random blue shades- Travel moves automatically use gray
Paths are automatically segmented when the extruder turns on/off. See docs/visualization.md for full documentation.
Visualization Parity: ✅ 100% Complete - All visualization outputs match the Python reference implementation exactly.
See examples/ for more patterns:
basic-line.ts: one extrusion movesquare.ts: perimeter pathspiral.ts: spiral helix demo (uses geometry helpers)
npm run build- compile the library for local testingnpm run parity- run parity tests against Python referencenpm run typecheck- verify TypeScript typesnpm run dev- watch mode for development
Prerequisites:
- Ensure you're logged in:
npm login - Verify authentication:
npm whoami
Publishing workflow:
# 1. Update version in package.json (e.g., 0.2.0 -> 0.2.1)
# 2. Commit version bump and any changes
git add .
git commit -m "Release v0.2.1"
git tag v0.2.1
# 3. Dry run to verify package contents
npm run publish:dry-run
# 4. Publish to npm as `latest` (runs parity tests + clean build + typecheck automatically)
npm run publish:latest
# 5. Push tags to GitHub
git push && git push --tagsNote: The prepublishOnly script automatically runs parity tests, build, and typecheck before publishing to ensure quality.
Parity Status: ✅ 100% Complete - All 27 automated parity cases pass (24 G-code + 3 visualization;
initialization_datareports one known warning).pythonParityinpackage.jsonindicates the Python version matched. The JavaScript implementation produces identical outputs (within numeric tolerances) to the Python version for both G-code generation and visualization.
Note: Parity tests run on fullcontrol python branch bf-zgradient-edge-case, pending PR upstream. The fullcontrol-py submodule is checked out there (c22c01d); the commit recorded in this repo (9a90c40) is older and not yet updated.
Python remains the source of truth. This repository includes an automated parity harness that runs paired real scripts (one Python, one JS) and performs tolerant G-code diffs.
Run all scenarios:
npm run parity
Add a new scenario:
- Create
scripts/parity/scenarios/py/<name>.pythat prints G-code or JSON plot data. - Create
scripts/parity/scenarios/js/<name>.mjsthat writes the JS-generated output. - Re-run
npm run parityand ensure no semantic diffs.
Scenario types:
- G-code scenarios: Compare line-by-line G-code output with numeric tolerances
- Visualization scenarios: Compare JSON plot data (paths, colors, bounding box) with tolerances for coordinates (±0.0005mm), colors (±0.001), and geometry (±0.001mm)
Semantic vs formatting differences: numeric fields (X/Y/Z/E/F for G-code, coordinates/colors for visualization) are compared with small tolerances defined in scripts/parity/config.json. Formatting-only differences (spacing, ordering within tolerance) do not fail the run.
See also:
PARITY.md– high-level feature parity matrix covering G-code generation and visualization.docs/visualization.md– comprehensive visualization system documentation.scripts/parity/README.md– harness implementation details & roadmap.
- Additional parity: advanced transforms, color handling modes, richer annotation semantics.
- Optional E/volume normalization strategies.
GPL-3.0 (inherits copyleft requirements; see license file). Ensure compliance when redistributing or combining. Upstream Python project licensing guidance applies.