CNCKitchen/ScanRuler

项目介绍

ScanRuler 是一个在浏览器中运行的 3D 扫描检测与建模工作台，面向需要核对零件与设计是否一致、或把扫描重建为 CAD 几何的工程师和创客。应用本身是静态的 Vite + React + three.js 构建，复杂几何计算放在 Web Worker 中，默认所有处理都在本机浏览器完成（项目说明、开发文档）。

各工作区共享同一份已载入的扫描数据：

• 3D Measure：点击扫描表面即可拟合球、圆柱、圆锥、圆环、平面和圆，给出高斯最优拟合及其 σ 和形状误差；也可用笔刷、窗口或套索手动标注表面。由拟合结果构建点、线、面，添加距离与角度尺寸，支持名义值 ± 公差以及平面度、平行度、垂直度、同轴度等 GD&T 检查；可按 3-2-1 基准、自动对齐或对称面对齐零件；可任意剖切并在 2D 图上测量，或生成“阴影”外轮廓；测量的解析几何可导出为 STEP。
• Deviation：载入名义零件的网格或 STEP 文件，自动对齐后按有符号偏差着色，支持悬停读数、拾取对齐、局部精细拟合、体积误差查找、形变动画，也可直接对照单个拟合元素（如检查某个面是否平面、某个孔是否圆）。
• Wall thickness：只需一个文件，从每个点向材料内投射射线或球体，薄壁显示为红色，无需参考件或对齐。
• 2D Measure：处理平板扫描图（PNG/JPEG）或 3D 扫描的剖切截面，边缘检测达到亚像素精度，可拟合点、线、圆、弧和样条并标注尺寸，按真实比例导出 SVG、DXF 或 CSV。
• Reverse engineer：把扫描截面拟合成草图，通过拉伸、旋转以及圆角、倒角、抽壳、孔、螺纹、拔模、镜像、阵列、放样、扫掠等特征生成实体 STEP 文件；自由曲面可用拟合曲面或 B 样条补片网络建模。
• Mesh Tools：移除孤岛、删除面、翻转法线、平面切割、补洞、平滑、收缩/膨胀、布尔运算、抽壳，并按容差减面。

输入支持 STL、PLY、OBJ（含 MTL 和贴图颜色）、3MF、STEP；工程文件 .scanruler 是一个 zip，包含输入文件和 project.json。扫描可导出 STL、3MF、PLY 或 XYZ 点云，2D 图纸可导出 SVG、DXF 或 CSV（文件格式）。

快速使用

普通测量不需要安装，直接打开 scanruler.com 即可。

1. 把 STL/PLY/OBJ/3MF/STEP 扫描文件拖入窗口，或按 Load。STL 没有单位，应用会先询问文件使用什么单位（入门步骤）。
2. 进入 3D Measure，按 Sphere、Cylinder 或 Plane，点击扫描上的对应特征。拟合结果先以灰色预览，按 Create（或 Enter，或鼠标中键）创建；如果特征被拆成多块，逐块点击。
3. 按 New dimension，选择尺寸类型并点选两个元素。Copy summary 会把全部结果复制到剪贴板。
4. Ctrl+Z / Ctrl+Shift+Z 在各工作区间撤销和重做；尺寸行上的 ✎ 可重新编辑该项。
5. 按 Save 把整个会话保存为一个 .scanruler 工程文件。

可选的 AI agent 集成会驱动已打开的 ScanRuler 标签页，需要 Node.js 22 或更高版本，以及 Chrome、Edge 或 Firefox。以 Claude Code 为例，先注册一次 helper：

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

Codex 使用：

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

连接后可让 agent 按完整路径打开文件、拟合特征、测量并生成报告；agent 会逐步操作面板，每一步都可撤销（MCP 配置）。

从源码运行需要先安装依赖并启动开发服务器：

npm install
npm --prefix mcp ci
npm run dev

npm test 运行单元测试，本地存在扫描样本时还会运行验收测试；npm run build 做类型检查并构建到 dist/（开发命令）。

使用约束

未连接 agent 时，扫描在本机浏览器中处理，不会上传。连接 agent 后，agent 读取的测量结果、报告、零件图片、文件名、备注以及它自己打开的文件都会由该 agent 处理并发送给其模型提供商，除非模型运行在本机；helper 本身在用户机器上运行，通过 127.0.0.1 通信（agent 与数据说明）。

平板扫描图在按已知尺寸校准前会标记为 UNCALIBRATED，校准后的比例可保存为扫描仪配置。README 中的精度数字来自一次结构光球杆扫描：中心距与 GOM Inspect 对比为 148.639 mm 对 148.64 mm，随机位移的扫描回到拟合位姿的误差在 0.9 µm 以内；这些是示例而非普遍保证（精度说明）。

逆向工程和由 agent 驱动的建模有明显边界：自由曲面输出的是拟合补片蒙皮而不是参数化模型；扫描看不到的内部特征（深腔、孔是否贯通）无法还原；公差不会细于扫描噪声的约三倍；agent 运行可能耗时很长，并消耗模型订阅可观的使用额度（能力边界）。

ScanRuler 采用 AGPL-3.0-only 许可。分发它或在网络上托管修改版本，需要以相同条款公开完整对应源码；闭源集成或不公开修改的托管可申请商业许可（许可证、商业许可）。贡献代码需要签署 CLA，内置字体和色图数据各自保留原许可。

网站上的一个 beta 工作区不在本仓库中，也不在本许可证覆盖范围内。

HotRepo 点评

ScanRuler 于 2026-11-02 进入 TypeScript 日榜第 5 名，该快照显示当日新增 256 Star，总数达到 658 Star、118 Fork。目前只有这一条榜单记录，能说明当天的上榜表现，不足以判断长期趋势。除在线演示外，仓库还包含可用的 MCP 集成和基于真实运行记录整理的逆向工程指南，代码本身值得进一步查看，而不应只把它当作一个网页应用。