┌─────────────────────────────────────────────────────────────────────┐
│  REVERSCAD                                                          │
│  Turn a raw STL scan into a parametric STEP model.                  │
└─────────────────────────────────────────────────────────────────────┘

Open-source reverse-engineering workbench. Upload an STL scan, detect primitives and cross-sections, and download a clean STEP file — no commercial CAD license required.

What it is

REVERSCAD reads a triangle mesh (STL) and reconstructs a parametric CAD model in STEP format. It is built for engineers, makers, and researchers who need reproducible geometry instead of manual tracing.

The project ships three complementary workflows:

• Process Scan — fully automatic STL → STEP via primitive detection and CSG.
• Analyze STL — inspect dimensions, volume, and dominant primitives without generating CAD.
• Geomagic Killer — interactive segment → cross-section → sketch → feature tree, inspired by Geomagic Design X.

There is also an Auto Director for hands-off Z-sweep reconstruction and a deviation gate that reports how close the generated model is to the original scan.

Features

	Feature	What it gives you
✨	STL → STEP pipeline	Automatic mesh analysis, primitive detection, and parametric reconstruction.
🔧	Geomagic-style workflow	Segment by curvature, slice with a click, auto-sketch, extrude/revolve, build a CSG tree.
🤖	Auto Director	Z-sweep cross-sections, critical-plane detection, and sequential Extrude + Union.
📐	Deviation analysis	Cloud-to-mesh distance metrics (max / mean / RMS) as a quality gate.
⚡	Multi-engine backend	Pure-Python pipeline by default; optional C++ native core or Rust truck-engine.
🖥️	Web UI	React + Three.js viewer for uploads, previews, and downloads.

Quick start

Requirements

• Python 3.10+
• Node.js 18+
• (Optional) CMake / Rust toolchain for native engines

Backend

# 1. Clone the repository
git clone https://github.com/Shugar86/reverscad.git
cd reverscad

# 2. Create a virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate          # On Windows: .venv\Scripts\activate

# 3. Install the core Python stack
pip install -r requirements.txt

# 4. Optional: extended engines (SolveSpace, Open3D, NURBS, CoACD)
pip install -r requirements-ai.txt

# 5. Start the API server
python -m uvicorn reverse_engineering_app.server:app --reload --port 8000

Frontend

cd frontend
npm install
npm run dev

Open http://localhost:1420, upload an STL, and press Analyze & Generate.

Run tests

pip install -r requirements-dev.txt
python -m pytest

CLI

python -m reverse_engineering_app tests/fixtures/box_ascii.stl --output box --verbose

Workflows

Process Scan (automatic)

POST /api/process-scan runs the full pipeline: preprocess → detect primitives → classify shape → extract profile → generate CAD → export STEP + preview STL. If the Auto Director succeeds, you get the result immediately; otherwise the pipeline falls back to a sequential CSG pass.

Analyze STL (inspect only)

POST /api/analyze-stl returns dimensions, volume, watertight status, and the dominant primitive detected by RANSAC — without generating a STEP file.

Geomagic Killer (interactive)

POST /api/geomagic/segment → cross-section → sketch → add-feature lets you build a parametric history tree step by step: pick a surface, slice it, auto-sketch the profile, and extrude or revolve it into solid geometry.

Architecture

Frontend (React + Vite + Three.js)          Native Core
┌──────────────────────────┐           ┌──────────────────────┐
│  3D Viewport             │           │  C++ / pybind11      │
│  Settings Panel          │           │  ├─ decompose.cpp    │
│  Feature Tree            │           │  ├─ detect.cpp       │
│  Deviation Card          │           │  └─ build_csg.cpp    │
└──────────┬───────────────┘           └──────────┬───────────┘
           │ HTTP                                  │ Python bindings
           ▼                                       ▼
┌──────────────────────────────────────────────────────────────┐
│  FastAPI Backend (reverse_engineering_app/server.py)          │
│  ├─ Auto Director Pipeline                                   │
│  ├─ Sequential CSG Pipeline                                  │
│  ├─ Geomagic Pipeline (interactive 5-stage)                  │
│  └─ Deviation Gate                                           │
└──────────────────────────────────────────────────────────────┘
           │
           ▼
┌──────────────────────┐    ┌──────────────────────┐
│  build123d / OCCT    │    │  Rust truck-engine   │
│  (CAD kernel)        │    │  (B-Rep → STEP)      │
└──────────────────────┘    └──────────────────────┘

Project structure

.
├── reverse_engineering_app/    # Python backend & pipelines
│   ├── server.py               # FastAPI app
│   ├── pipeline.py             # Full automatic pipeline
│   ├── stl_analyzer.py         # STL analysis endpoints
│   ├── geomagic_pipeline.py    # Interactive Geomagic workflow
│   ├── auto_director.py        # Z-sweep auto reconstruction
│   ├── sketch_pipeline/        # Segment / section / sketch / CSG
│   └── ...
├── cad_engine/                 # Precision & BRep utilities
│   ├── deviation_analyzer.py
│   ├── precision_fitter.py
│   └── brep_stitcher.py
├── frontend/                   # React + Vite + Three.js UI
├── native_core/                # Optional C++ pybind11 module
├── truck-engine/               # Optional Rust B-Rep engine
├── tests/                      # pytest suite
├── scripts/                    # Benchmarks & audits
└── docs/                       # Architecture & dependency docs

API overview

Method	Route	Description
POST	/api/process-scan	Upload STL → full pipeline → STEP + preview + feature tree
POST	/api/analyze-stl	STL analysis only (dimensions, volume, primitives)
POST	/api/geomagic/segment	Segment mesh by curvature
POST	/api/geomagic/cross-section	Cross-section at click point
POST	/api/geomagic/sketch	Auto-sketch from cross-section
POST	/api/geomagic/add-feature	Add extrude/revolve feature to CSG tree
GET	/api/health	Health check

See docs/PROJECT_AUDIT.md and docs/GEOMAGIC_KILLER.md for detailed endpoint schemas and examples.

Examples

Upload a scan with curl

# With the server running on port 8000
curl -X POST \
  -F "file=@tests/fixtures/box_ascii.stl" \
  http://localhost:8000/api/process-scan

Use the Python API

from reverse_engineering_app import ReversEngineeringPipeline

pipeline = ReversEngineeringPipeline(output_dir="./output")
result = pipeline.run("scan.stl", output_name="bracket")

if result.success:
    print(result.generation.exports.step_path)
else:
    print("Failed:", result.generation.error)

Documentation

• docs/PROJECT_AUDIT.md — architecture and how everything works
• docs/GEOMAGIC_KILLER.md — interactive Geomagic-style workflow
• docs/DEPENDENCIES.md — real engines and optional dependencies
• docs/AUDIT.md — project audit, risks, and recommendations
• CONTRIBUTING.md — how to contribute
• CHANGELOG.md — release history

Roadmap & Changelog

See CHANGELOG.md.

Contributing

See CONTRIBUTING.md.

License

MIT © 2026 Shugar86