CNCKitchen/ScanRuler

Overview

ScanRuler is a browser-based inspection and modelling workspace for 3D scans, aimed at engineers and makers who need to check a part against its design or rebuild it as CAD geometry. It runs as a static Vite + React + three.js app with heavy geometry work in a Web Worker, and all processing happens locally in the browser by default (project README, development notes).

The tool is organised into workspaces that all operate on the same loaded scan:

• 3D Measure fits spheres, cylinders, cones, tori, planes and circles to clicked surfaces, builds points/lines/planes from the fits, adds distance and angle dimensions, applies nominal ± tolerances and GD&T checks, aligns by 3-2-1, auto-align or symmetry plane, cuts sections (including a "shadow" outline), and exports the measured geometry as STEP.
• Deviation aligns a scan to a nominal mesh or STEP part and paints signed deviation, with optional local fine fits, volume error detection, an exaggerated deformation animation, and comparison against a single fitted element.
• Wall thickness casts rays or spheres through the material from each point and colours thin walls red; no reference part or alignment is needed.
• 2D Measure works on flatbed scans (PNG/JPEG) or sections cut through the 3D scan, detects edges to subpixel accuracy, fits points, lines, circles, arcs and splines, dimensions them, and exports SVG, DXF or CSV at scale.
• Reverse engineer turns fitted sections into a solid STEP body with extrude/revolve, fillets, chamfers, shells, holes, threads, drafts, mirrors, patterns, lofts and sweeps, or from B-spline patches for freeform parts.
• Mesh Tools cleans, fills, smooths, booleans, shells and decimates meshes against the original scan.

Supported inputs include STL, PLY, OBJ with MTL and textures, 3MF and STEP; the written project file is a .scanruler zip containing the inputs and project.json. Scan exports can be STL, 3MF, PLY or XYZ, and 2D sheets go to SVG, DXF or CSV (file formats).

Getting started

The hosted app is available at scanruler.com, so nothing needs to be installed for ordinary measurement work.

1. Drag an STL/PLY/OBJ/3MF/STEP scan into the window, or press Load. STL has no units, so the app asks which unit the file uses (getting started).
2. In 3D Measure, choose Sphere, Cylinder or Plane and click the feature on the scan. The fit previews in grey; press Create (or Enter, or the middle mouse button) to commit it. Click each patch if a feature is split.
3. Press New dimension, pick the type, and select the two elements. Copy summary copies all results to the clipboard.
4. Use Ctrl+Z / Ctrl+Shift+Z for undo and redo across workspaces; the ✎ key on a dimension row reopens it.
5. Press Save to write the session to a single .scanruler project file.

The optional AI agent integration uses the same open tab. It needs Node.js 22 or newer plus Chrome, Edge or Firefox, and the helper is registered once, for example:

claude mcp add --scope user scanruler -- npx -y scanruler-mcp@latest

Or for Codex:

codex mcp add scanruler -- npx -y scanruler-mcp@latest

After connecting, ask the agent to open a file by full path, fit features, measure and produce a report. The agent works the panels step by step and every step can be undone (MCP setup).

To run from source, install dependencies and start the Vite dev server:

npm install
npm --prefix mcp ci
npm run dev

npm test runs unit tests plus acceptance tests on local scans when present, and npm run build type-checks and builds to dist/ (development commands).

Constraints and data handling

Without an agent connected, scans are processed locally in the browser and are not uploaded. With an agent connected, the measurement results, reports, part images, file names, notes and any files the agent opens are processed by that agent and sent to its model provider, unless the model runs locally; the helper itself runs on the user's machine and communicates over 127.0.0.1 (agents and data).

Flatbed images start flagged UNCALIBRATED until calibrated against an object of known size; the resulting scale can be saved as a scanner profile. Accuracy claims in the README are tied to a structured-light ball-bar scan (centre distance 148.639 mm versus 148.64 mm in GOM Inspect) and a randomly displaced scan returning within 0.9 µm of its fitted pose, so they should be read as examples rather than a general guarantee (accuracy).

The Reverse engineer and agent-driven modelling workflow has explicit limits: freeform shapes come out as fitted patch skins rather than parametric models, hidden interior features cannot be inferred from the scan, tolerances are never finer than roughly three times the scan noise, and agent runs can be slow and consume a significant part of a model subscription's usage limit (limits).

ScanRuler is licensed AGPL-3.0-only. Distributing it or hosting a modified version over a network requires publishing the complete corresponding source under the same terms; a commercial license is available for closed-source or non-published hosting (license, commercial licensing). Contributions require a CLA, and the bundled fonts and colour-map data carry their own licenses.

The site's beta workspace is not part of this repository and is not covered by the same license.

HotRepo's take

ScanRuler entered the TypeScript daily list on 2026-11-02 at position 5, gaining 256 stars in that snapshot to reach 658 stars and 118 forks. That is a single recorded snapshot, so it supports the fact of a strong one-day showing but not a trend. The repository also has a substantial technical surface beyond the hosted demo: a documented MCP integration and a working reverse-engineering guide built from real runs, which makes the codebase worth examining rather than treating the web app as the whole project.