gcode-retraction-analyzer

CLI for streaming analysis of retraction behavior in large sliced G-code files.

The analyzer reconstructs extrusion state, pairs retract/recovery episodes, quantifies travel and mechanical retraction activity, detects suspicious patterns, proposes evidence-based slicer experiments, and generates a self-contained interactive HTML diagnostic report.

Guiding workflow: Measure → explain → suggest an experiment → re-slice → compare.

Why this project exists

Slicer settings describe intent. G-code describes what the printer will actually execute.

A slicer profile may say “0.8 mm retraction” and “minimum travel 1 mm”, but a large sliced model can still contain tens of thousands of retractions, short-travel bursts, concentrated retraction-heavy layers, unexpected recovery deltas, or long travels without retraction. This tool analyzes the generated machine instructions rather than trusting configuration alone.

The project is deliberately distinct from a general G-code viewer or gcode-inspector. It focuses on extrusion/retraction mechanics and practical diagnostics.

MVP questions

The analyzer answers:

• How many retractions occur?
• How many occur per layer and per printed meter?
• What retraction distances are actually generated?
• What travel distances are protected by retractions?
• How often do extremely short retract/travel/unretract cycles occur?
• What is the peak retraction frequency?
• Where do retraction bursts occur?
• How much additional backward/forward filament motion is generated?
• Are retract and recovery distances balanced?
• Are suspicious patterns global or concentrated in a small layer/XY region?
• What slicer experiment is reasonable to try next?
• Did a re-sliced version improve the relevant metrics?

Design constraints

• .NET 10.
• One-pass streaming analysis where practical.
• Never load the complete G-code file into memory.
• Exact analysis must not depend on visualization sampling.
• The tool is analysis-only: it does not rewrite G-code.
• No printer connection.
• No slicer integration.
• No Node.js toolchain.
• HTML reports are self-contained and work offline.
• All heuristics and warning thresholds are configurable.
• Recommendations must be evidence-based experiments, not claims of universal “correct” slicer values.

Quick start

Requires the .NET 10 SDK to build, or a compatible .NET 10 runtime for framework-dependent release binaries.

dotnet restore
dotnet build
dotnet run --project src/GCode.RetractionAnalyzer.Cli -- analyze samples/minimal-relative.gcode

See docs/packaging.md for Windows and Linux single-file publishing.

CLI

The CLI provides streaming analysis, a default standalone HTML dashboard, console output, and optional deterministic JSON schema 1.0 output:

gcode-retraction-analyzer analyze model.gcode
gcode-retraction-analyzer analyze model.gcode --html custom.analysis.html --json model.analysis.json
gcode-retraction-analyzer analyze model.gcode --json model.analysis.json --no-html --no-console --quiet

By default, analyze model.gcode writes model.retraction-analysis.html; use --no-html for analysis-only automation. Comparison mode accepts either two G-code files or two schema-compatible saved analysis JSON files:

gcode-retraction-analyzer compare old.gcode new.gcode
gcode-retraction-analyzer compare old.analysis.json new.analysis.json --json comparison.json
gcode-retraction-analyzer compare old.gcode new.gcode --html experiment-comparison.html

Raw G-code inputs are analyzed with the same normalized options. Comparison reports keep objective deltas separate from recommendation-specific interpretation and surface defined cross-metric trade-offs. By default, compare also writes a standalone offline HTML report beside the second input. Use gcode-retraction-analyzer --help for all options.

Typical analysis options:

gcode-retraction-analyzer analyze model.gcode \
  --short-travel 1.0 \
  --max-frequency 8 \
  --frequency-window 1 \
  --burst-gap-ms 250

Outputs

Console

Fast diagnostic summary suitable for terminals and scripts.

JSON

Versioned machine-readable analysis data suitable for comparison, automation, and future integrations.

Interactive HTML

A single offline file containing:

• overview KPIs;
• findings and recommendations;
• retractions per layer;
• frequency timeline;
• protected-travel histogram;
• retraction-distance histogram;
• retraction scatter plot;
• XY retraction-location plot;
• threshold simulation.

Large-file principle

A 1 GB G-code file should not require 1 GB of managed memory.

Analysis uses streaming parsing, online statistics, bounded sliding windows, layer aggregation, bounded quantile estimation, and deterministic visualization sampling.

Charts may be aggregated or sampled; analysis never is.

Architecture

The solution separates streaming mechanics, analysis, comparison, reporting, and CLI orchestration:

Project	Responsibility
Core	G-code parsing, modal machine state, retraction tracking, timing primitives, and streaming statistics
Analysis	Exact metrics, bounded visualization datasets, findings, recommendations, and threshold simulation
Compare	Objective metric deltas, recommendation verification, and trade-off detection
Reporting	Console, JSON, and self-contained HTML rendering
CLI	Input validation, orchestration, progress, output selection, and exit codes
Benchmarks	Deterministic parser, analyzer, JSON, and HTML performance measurement

See docs/architecture.md for dependency boundaries and data flow.

Performance and release documentation

• docs/benchmarks.md — reproducible 10/100 MiB throughput and allocation measurements;
• docs/packaging.md — Windows/Linux single-file publishing and Native AOT decision;
• docs/schema-versioning.md — JSON compatibility and unit policy;
• docs/limitations.md — explicit MVP semantic limits.