warp-engine

A predictive warp analysis engine for 3D printing. Feed it G-code and it tells you where your print is likely to warp, why, and what to do about it.

warp-engine parses G-code from any major slicer, runs a multi-factor risk analysis (thermal, geometry, adhesion, print settings), and produces a scored report with per-region risk breakdowns and actionable recommendations.

Installation

pip install warp-engine

Requires Python 3.11+.

Quick Start

from warp_engine.engine import Engine
from warp_engine.models import AnalysisTier

engine = Engine()

# Read your G-code file
with open("my_print.gcode") as f:
    gcode = f.read()

# Run analysis
report = engine.analyze(
    gcode=gcode,
    material="ABS",
    tier=AnalysisTier.STANDARD,
    printer_profile="bambu_x1c",
)

# Check results
print(f"Risk: {report.risk_level.name} ({report.overall_score:.0%})")
for rec in report.recommendations:
    print(f"  [{rec.category}] {rec.message}")

Visualize Results

Open an interactive 3D viewer right from Python:

report.show()  # Opens browser with 3D heatmap viewer

Or save the report and view it later with the CLI:

# Save report to JSON
python -c "
from warp_engine.engine import Engine
engine = Engine()
report = engine.analyze(open('print.gcode').read(), material='ABS')
with open('report.json', 'w') as f:
    f.write(report.to_json())
"

# View it
warp-view report.json --gcode print.gcode

The viewer shows a 3D risk heatmap, per-region risk cards, thermal timeline, and actionable recommendations.

Analysis Tiers

All tiers produce the same WarpReport output structure.

Risk Factors

The engine evaluates four independent risk categories and combines them with material-specific weights:

• Thermal -- inter-layer cooling, temperature gradients, airflow effects
• Geometry -- large flat regions, thin walls, sharp corners, overhangs
• Adhesion -- bed contact area, first layer coverage, adhesion type
• Settings -- cooling fan speed, bed temp, print speed, layer height

Supported Materials

18 calibrated profiles: PLA, PETG, ABS, ASA, TPU, Nylon, PC, plus carbon fiber composites (PLA-CF, PETG-CF, ASA-CF, PET-CF, PAHT-CF, PA6-CF, PPA-CF, PPS-CF), glass fiber composites (ABS-GF, PA6-GF), and specialty (PC-FR). See docs/materials.md for full property tables.

Supported Printers

Bambu Lab X1C, H2D, P1S, A1, A1 Mini | Prusa MK4 | Creality Ender-3 V3 | Voron 2.4

Printer profiles include airflow source positions for accurate thermal simulation. See docs/printers.md for details.

G-code Compatibility

Parses all major G-code flavors: Marlin, Klipper, RepRap, Smoothieware, Sailfish. Auto-detects the flavor from slicer comments.

Documentation

• Getting Started -- installation, first analysis, interpreting results
• API Reference -- Engine class, data models, WarpReport structure
• Visualizer -- standalone 3D viewer and CLI
• Materials -- built-in material profiles and properties
• Printers -- built-in printer profiles and airflow configs
• REST API -- Django integration endpoints

License

MIT -- see LICENSE.