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-js
import { 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)
Point, Extruder, Printer, etc.)speed_changed internally via point speed override).Extruder.units:
mm3: E equals volumetric mm^3 (ratio = 1)mm: E equals filament length; ratio computed from dia_feed diameterExtruder.relative_gcode = true resets volume reference after each move.travel_format: 'G1_E0' appends E0 on 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 shadesPaths 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 developmentPrerequisites:
npm loginnpm whoamiPublishing 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 --tags
Note: 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:
scripts/parity/scenarios/py/<name>.py that prints G-code or JSON plot data.scripts/parity/scenarios/js/<name>.mjs that writes the JS-generated output.npm run parity and ensure no semantic diffs.Scenario types:
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.GPL-3.0 (inherits copyleft requirements; see license file). Ensure compliance when redistributing or combining. Upstream Python project licensing guidance applies.