📑 Table of Contents

• Executive Overview
• Key Engineering Capabilities
• System Architecture (7-Stage Pipeline)
• Cross-Platform & Architecture Support
• Multithreading & Resilience Engine
• Quick Start & CLI Usage
  • 1. Installation & Build
  • 2. Single File Conversion
  • 3. Custom Output Directory
  • 4. High-Throughput Batch Processing
  • 5. Specialized Execution Modes
• Output Artifacts & The Two-File Rule
• Model Context Protocol (MCP) Server
  • Why ReverseCAD MCP is Enterprise-Grade
  • Available MCP Tools Catalog
  • Client Configurations (Claude Desktop, Cursor, Trae, Antigravity)
• RSVS Reality Simulation Engine
• Automated Verification & Test Suite
• Author & Collaboration
• License & Commercial Terms

🎯 Executive Overview

For over three decades, computer-aided engineering has struggled with a fundamental divide:

• The Mesh World (.stl): A lossy, unorganized "raster snapshot" consisting of raw 3D triangles without topology, cylinder equations, radii, centers, or manufacturing semantics.
• The CAD World (.step, B-Rep): Exact mathematical boundary representations (surfaces, curves, vertices, faces) capable of parametric editing, assembly mating, and CAM toolpath generation.

Traditional solutions fall into two extremes:

1. Crude "Facet Wrappers" (FreeCAD, OpenCASCADE, online converters): Wrap every single STL triangle into a STEP face, bloating a 5 MB STL into a 250 MB STEP that freezes SolidWorks, Fusion 360, and slicers, while providing zero analytical cylinders or mating references.
2. Expensive, Manual Reverse Engineering (Geomagic Design X, CATIA): Costing upwards of $25,000/license and requiring an experienced engineer to spend 2 to 8 hours per part clicking surfaces and redrawing sketches. Their automated "Autosurface" functions smear sharp edges and ruin threads into wavy NURBS patches.

ReverseCAD bridges this divide deterministically in seconds. By combining multi-surface RANSAC segmentation with strict non-destructive feature validators, ReverseCAD extracts exact analytical primitives (planes, cylinders, cones, tori) while preserving micro-mechanical geometry (helical threads, 45° entrance chamfers, knurling) 1:1 as continuous B-Rep facet shells.

✨ Key Engineering Capabilities

🏗️ System Architecture (7-Stage Pipeline)

flowchart TD
    A["Raw .stl Input Mesh"] --> S1["Stage 1: Fast Intake & Spatial Hashing"]
    S1 --> S2["Stage 2: QEM Adaptive Decimation"]
    S2 --> S3["Stage 3: Topology Sanitization & Multi-Shell Split"]
    S3 --> S4["Stage 4: Surface Segmentation & Feature Protection"]
    S4 --> S5["Stage 5: Feature Profiling & Kinematics Engine"]
    S5 --> S6["Stage 6: STEP AP242 Kernel Synthesis"]
    S5 --> S7["Stage 7: RSVS Reality Simulation & JSON Export"]
    S6 --> OUT1["📦 Solid B-Rep .step (ISO 10303-21 AP242)"]
    S7 --> OUT2["⚡ cad_features.summary.json (< 1200 tokens)"]
    S7 --> OUT3["📊 verification_report.json (RSVS Gates G0-G4)"]

1. Stage 1 (Fast Intake & 64-bit Spatial Hashing): Auto-detects Binary vs. ASCII STL formats. Uses a collision-free 64-bit spatial coordinate hash for vertex welding without string allocation or V8 GC overhead.
2. Stage 2 (Adaptive Decimation): Quadric Error Metric (QEM) edge-collapse decimation simplifies planar regions while locking boundary loops and high-curvature feature lines.
3. Stage 3 (Topology Sanitization): Validates manifold watertightness, repairs T-junctions, discards degenerate sliver triangles, and separates disjoint bodies into independent shells.
4. Stage 4 (Surface Segmentation & Feature Protection): RANSAC extraction for planes, cylinders, cones, and tori. Validates plane candidates against spatial compactness and angular dispersion to protect 45° chamfers and helical thread crests.
5. Stage 5 (Feature Profiling & Kinematics Engine): Matches holes to ISO metric standards, extracts bolt circle pitch diameter circles (PCD), and quantifies Print-in-Place kinematic joints.
6. Stage 6 (STEP AP242 Kernel): Direct synthesis of STEP AP242 ISO 10303-21 B-Rep entities via 256 KB buffered streaming I/O, with automatic IEEE 754 negative zero (-0.0) sanitization.
7. Stage 7 (RSVS Reality Simulation & Dual JSON Export): Zero-Heap scalar calculation of Hausdorff distance percentiles (H99), Mirtich polyhedral mass integration, and dual-tier JSON generation.

💻 Cross-Platform & Architecture Support

ReverseCAD is engineered using pure standard Node.js runtime APIs, portable typed memory buffers (Float32Array), and cross-platform Worker Threads. It runs seamlessly with 0 native compilation prerequisites across all desktop, workstation, and cloud server environments:

• Operating Systems:
  • 🍏 macOS (macOS 12+ Monterey, Ventura, Sonoma, Sequoia) via ./convert.sh
  • 🐧 Linux (Ubuntu, Debian, Fedora, Arch, Alpine, RHEL) via ./convert.sh
  • 🪟 Windows (Windows 10, 11, Server via PowerShell .\convert.ps1, Command Prompt convert.cmd, or WSL2 / Git Bash)
• CPU Architectures:
  • ⚡ ARM64 / AArch64 (Apple Silicon M1/M2/M3/M4 with automatic P-Core affinity, Qualcomm Snapdragon X Elite, AWS Graviton, Raspberry Pi 5)
  • ⚡ x86_64 / AMD64 (Intel Core / Xeon, AMD Ryzen / EPYC with multithreaded worker pool)

Platform & Shell Matrix

⚡ Multithreading & Resilience Engine

• Piscina Worker Threads Pool: Maximizes CPU saturation by dynamically detecting Performance cores on Apple Silicon (M1–M4) and multi-core Intel/AMD architectures, configured with explicit memory limits (maxOldGenerationSizeMb: 4096).
• Deficit Weighted Round-Robin (DWRR): Fair-share batch scheduler ensures small parts are never starved when processing giant multi-million triangle meshes simultaneously.
• Memory Circuit Breaker & Watchdog Guard: Proactive Heap allocation monitoring trips gracefully before reaching Out-of-Memory thresholds. An adaptive execution watchdog kills and reports corrupt/infinite-loop geometry.
• Streaming Manifest (conversion_manifest.ndjson): Live step-by-step progress logging in structured NDJSON for automated CI/CD monitoring.

💻 Quick Start & CLI Usage

1. Installation & Build

# Clone repository
git clone https://github.com/grizlizora/reverse-cad.git
cd reverse-cad

# Install dependencies and build TypeScript
npm install
npm run build

# Make launcher executable (macOS / Linux only)
chmod +x ./convert.sh

2. Single File Conversion

macOS & Linux:

./convert.sh ./models/bracket_m6.stl
./convert.sh "/path/to/part.stl" -o ~/Downloads/

Windows (PowerShell):

.\convert.ps1 .\models\bracket_m6.stl
.\convert.ps1 "C:\path\to\part.stl" -o "$HOME\Downloads"

Windows (Command Prompt):

convert.cmd models\bracket_m6.stl
convert.cmd "C:\path\to\part.stl" -o "%USERPROFILE%\Downloads"

Universal NPM (Any Platform):

npm run convert -- ./models/bracket_m6.stl -o ./output

3. Custom Output Directory (-o / --out-dir)

By default, converted models are saved to ./output. You can route output to any directory across platforms:

# Save to Downloads (macOS/Linux)
./convert.sh "model.stl" -o ~/Downloads/

# Save to Downloads (Windows PowerShell)
.\convert.ps1 "model.stl" -o "$HOME\Downloads"

# Save to custom engineering workspace
npm run convert -- "model.stl" -o ./cad_exports/

4. High-Throughput Batch Processing

# macOS / Linux: batch convert directory with 8 parallel worker threads
./convert.sh ./models/ -o ./output/ -t 8

# Windows (PowerShell):
.\convert.ps1 .\models\ -o .\output\ -t 8

# Universal NPM:
npm run convert -- ./models/ -o ./output/ -t 8

5. Specialized Execution Modes

# Fast AI inspection: generate semantic JSON only (skips heavy STEP generation)
./convert.sh part.stl --json-only

# Pure CAD conversion: generate solid STEP file only
./convert.sh part.stl --step-only

# Run full RSVS benchmark suite, mutation injection & memory leak audits
./convert.sh --test
# (or on Windows: .\convert.ps1 --test  /  npm test)

📁 Output Artifacts & The Two-File Rule

Upon pipeline completion, the target directory contains a clean, production-ready set of files:

├── 🟢 part.step                      <- PRIMARY FOR CAD & SLICERS (Solid B-Rep model)
├── 🟢 part.cad_features.summary.json <- PRIMARY FOR AI LLMS (< 1200 tokens, full semantics)
├── ⚪️ part.cad_features.topology.json<- Full geometric dump (vertices, facets, bounds)
├── ⚪️ part.verification_report.json  <- RSVS G0-G4 reality simulation report
└── ⚪️ conversion_manifest.ndjson      <- Real-time pipeline execution log

💡 The Two-File Rule for Users & Engineers:

1. 🟢 *.step ➔ Open directly in Autodesk Fusion 360, SolidWorks, FreeCAD, Shapr3D, Siemens NX, or 3D slicers (Bambu Studio, PrusaSlicer, OrcaSlicer).
2. 🟢 *.cad_features.summary.json ➔ Attach to your chat with Claude, GPT-4o, Cursor, or Gemini. Contains complete mechanical semantics (threads, holes, mass, bounding box, kinematics) without consuming LLM context window limits.

🤖 Model Context Protocol (MCP) Server

ReverseCAD features a built-in enterprise-grade MCP Server that exposes deterministic CAD reverse engineering tools directly to AI coding environments (Claude Desktop, Cursor, Trae, Windsurf, Antigravity).

Why ReverseCAD MCP is Enterprise-Grade:

• Zero Event Loop Latency (< 0.02 ms Ping SLA): Heavy geometric calculations run entirely within background worker threads. The main process handles only asynchronous Stdio transport, guaranteeing instant ping responses even while processing 100 MB meshes.
• Strict Stdio Framing Isolation: All internal logs, worker stdout, and warnings are redirected to stderr. This prevents invalid characters in stdout and eliminates -32700 JSON Parse Errors.

Available MCP Tools Catalog:

Client Configurations

1. Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "reverse-cad": {
      "command": "/bin/bash",
      "args": [
        "/absolute/path/to/reverse-cad/convert.sh",
        "--mcp"
      ]
    }
  }
}

2. Cursor IDE (.cursor/mcp.json)

{
  "mcpServers": {
    "reverse-cad": {
      "command": "/bin/bash",
      "args": [
        "/absolute/path/to/reverse-cad/convert.sh",
        "--mcp"
      ]
    }
  }
}

🔬 RSVS Reality Simulation Engine

ReverseCAD includes a proprietary Reality Simulation Verification Suite (RSVS) that verifies geometric fidelity against the original STL mesh:

• David Eberly 3D Triangle Projection: Calculates exact scalar distances from any point in space to a 3D triangle across all 7 Voronoi zones directly from contiguous Float32Array buffers.
• Zero-Heap Scalar Fast-Path: Eliminates intermediate { distance, point } object allocations in hot loops ($10^6$ sample points), preventing V8 Garbage Collector pauses.
• Analytical Quadric Math: Exact analytical distance metrics for planes, finite clamped cylinders with endcaps $d = \sqrt{\Delta r^2 + \Delta t^2}$, cones, and tori.
• $O(N)$ QuickSelect Percentile Calculation: Computes the 99th percentile Hausdorff distance ($H_{99}$) in linear time without expensive full-array sorting.

🧪 Automated Verification & Test Suite

Run the full end-to-end regression and verification suite:

./convert.sh --test

Verified Suite Coverage:

• 4 Procedural Industrial Benchmarks: Prismatic M6 bracket, hollow internal labyrinth, Print-in-Place hinge, and organic saddle surface.
• Mutation Self-Test: Injects 4 intentional geometric mutations (axis tilt, scaling distortion, wall rupture, clearance collapse) and confirms 100% detection by RSVS reality gates.
• Combinatorial Matrix Scanner: Stress tests dense 80,000 and 40,000 triangle procedural meshes.
• Zero-Leak Memory Audit: Verifies zero dangling ArrayBuffer allocations with Heap growth strictly $< 0.7$ MB.

======================================================
  RSVS REALITY SIMULATION & GROUND-TRUTH TEST BENCHMARK
======================================================

• Testing procedural model: benchmark_prismatic_m6.stl
  ✔ Successfully converted in 22 ms
  ✔ Analytical surfaces extracted: 10
  ➜ RSVS Gates: [G0: PASSED] [G1: PASSED] [G2: PASSED] [G3: PASSED] [G4: WARNING]
  ✔ M6 thread detection: CONFIRMED

• Testing procedural model: benchmark_internal_labyrinth.stl
  ✔ Internal cavity detection (Zero-Voxel): CONFIRMED

• Testing procedural model: benchmark_pip_hinge.stl
  ✔ Print-in-Place clearance detection: CONFIRMED

• Running RSVS mutation self-test (4 injected defects)...
  ✔ Detected 4/4 defects

✔ Memory Audit Clean: No lingering ArrayBuffer leaks detected.
======================================================
  ✔ ALL TESTS PASSED SUCCESSFULLY! PIPELINE 100% VALID.
======================================================

👨‍💻 Author & Collaboration

Crafted by Roman (@grizlizora) — Software Engineer specializing in High-Performance Systems, Computational Geometry, Multithreaded Pipelines, and AI Agent Integrations.

• 💬 Telegram: @grizlizora
• 🐙 GitHub: @grizlizora
• 💼 LinkedIn: Roman Vaida
• 📧 Email: [email protected]

📄 License & Commercial Terms

ReverseCAD is released under a Dual-Licensing Model:

⚠️ Legal Enforcement Notice:

Commercial use without an active, paid Commercial License constitutes statutory copyright infringement under international treaties (Berne Convention), Title 17 of the United States Code (17 U.S.C. § 504 statutory damages up to $150,000 USD per willful infringement), and European Union Intellectual Property Directives. Pre-trial formal demands and litigation will be actively enforced.

To obtain an official corporate license, request an invoice, or execute a master enterprise agreement:

• Licensor: Roman Vaida
• Email: [email protected]
• Telegram: @grizlizora
• Terms & Wire Transfer Instructions: COMMERCIAL.md