gcode-stringing-analyzer

CLI with static analyzer for sliced FDM/FFF G-code.

The analyzer streams ASCII .gcode input, normalizes modal machine state into physical motion events, identifies printing layers, measures extrusion and travel behavior, tracks retraction, and reports source-linked travels that may contribute to stringing. Reports are deterministic, human-readable JSON.

This is a static risk analyzer. It identifies G-code conditions associated with stringing; it does not claim that physical stringing occurred.

Features

• Parses G0, G1, G90, G91, G92, M82, and M83, including common zero-padded forms.
• Supports absolute and relative XYZ and extrusion modes.
• Treats G92 as a coordinate-baseline change, never as physical movement.
• Confirms a new layer only when material is deposited on a higher printing plane, so Z-hop does not create false layers.
• Separates unretraction from deposited filament and calculates extrusion volume.
• Reports global statistics, per-layer statistics, and source-line-linked stringing-risk findings.
• Compares two analyses layer-by-layer with deterministic Z-tolerant matching.
• Streams input instead of loading an entire G-code file into memory.
• Uses only the .NET base class library in the production project.

Requirements

• .NET 10 SDK

Build and test

dotnet restore GCodeStringingAnalyzer.slnx
dotnet build GCodeStringingAnalyzer.slnx -c Release --no-restore
dotnet test GCodeStringingAnalyzer.slnx -c Release --no-build

Usage

gcode-stringing-analyzer <input.gcode> [options]
gcode-stringing-analyzer --diff <old.gcode> <new.gcode> [options]

When running from source, place CLI arguments after --:

dotnet run --project src/GCodeStringingAnalyzer -- samples/stringing-risk.gcode

By default, JSON is written to standard output. Use --output to write a UTF-8 JSON file instead.

Option	Meaning	Default
--output <report.json>	Write JSON to a file	standard output
--filament-diameter <mm>	Filament diameter used for volume	1.75
--travel-threshold <mm>	Minimum XY travel considered risky	5
--min-retraction <mm>	Retraction depth considered sufficient	0.4
--z-tolerance <mm>	Printing-plane and diff matching tolerance	0.001
--fail-on <level>	Minimum finding severity that returns exit code 1; none disables threshold failure	none
-h, --help	Show built-in help

Analysis example

dotnet run --project src/GCodeStringingAnalyzer -- samples/stringing-risk.gcode --output report.json --fail-on high

Diff example

dotnet run --project src/GCodeStringingAnalyzer -- --diff samples/safe-travel.gcode samples/stringing-risk.gcode --output diff.json

Diff mode analyzes both files through the same configuration, aligns ascending layers by Z tolerance, and compares derived metrics rather than G-code text. Added and removed layers are explicit. In diff mode, --fail-on evaluates findings in the new file.

Exit codes

Code	Meaning
0	Analysis succeeded and the configured finding threshold was not met
1	Analysis succeeded and the configured finding threshold was met
2	Invalid CLI arguments
3	Input, parsing, or report-output failure

JSON reports

Analysis JSON contains file metadata, effective configuration, global summary statistics, per-layer statistics, and findings. Diff JSON contains old/new file metadata and matched, added, or removed layers with numeric and percentage metric deltas.

See the report contract for field details.

Scope and limitations

The tool does not rewrite G-code or model collisions, firmware acceleration, temperature, material physics, slicer behavior, or observed print defects. See the stringing-risk model for the exact detection rule and limitations.

Documentation

• Requirements
• Architecture
• Supported G-code semantics
• Stringing-risk model
• JSON report contract
• Test plan