Stastyle/ScanAlign
GitHub: Stastyle/ScanAlign
一款将原始 3D 扫描网格文件对齐到 XYZ 轴和原点的 Windows 桌面应用，便于整洁地导入 CAD 软件。
Stars: 0 | Forks: 0
# ScanAlign
**Alpha v0.1** · 一款 Windows 桌面应用，可导入原始 3D 扫描文件 (OBJ · PLY · STL) 并将其对齐到世界 XYZ 轴及原点 —— 使它们能整洁、居中且方正地直接放入 Fusion 360（或任何 CAD 软件）中。
有关产品愿景请参阅 [PLAN.md](PLAN.md)，有关架构请参阅 [IMPLEMENTATION.md](IMPLEMENTATION.md)，有关当前局限性请参阅 [KNOWN_ISSUES.md](KNOWN_ISSUES.md)。
## 状态
处于早期 **alpha** 阶段。完整的 pipeline 已实现端到端运行 —— 加载 → 选择工具 → 设置基准 → 实时预览 → 提交 → 导出 —— 并且由 **92 个自动化测试**（`dotnet build` 和 `dotnet test` 均通过）覆盖。预期仍存在一些粗糙的边缘，特别是在拾取精度方面；请参阅 [KNOWN_ISSUES.md](KNOWN_ISSUES.md)。
## 环境要求
- Windows 10 / 11
- [.NET 8 SDK](https://dotnet.microsoft.com/download) (`winget install Microsoft.DotNet.SDK.8`)
## 构建、测试、运行
```
dotnet build # build everything
dotnet test # run the test suite (92 tests)
dotnet run --project src/ScanAlign.App # launch the app
# 直接打开文件（也可通过将文件拖拽到 .exe 上来实现）：
dotnet run --project src/ScanAlign.App -- samples/tilted-cube.obj
```
一个示例扫描文件（一个模拟原始扫描仪导出的倾斜且偏离原点的立方体）位于 [samples/tilted-cube.obj](samples/tilted-cube.obj)。
## 对齐扫描件
1. **打开**一个扫描文件 (OBJ/PLY/STL)，或在命令行中传入它。
2. 在左侧边栏中选择一种**对齐工具**：
| 工具 | 功能描述 |
|------|--------------|
| **3点平面** | 点击平面上 3 个点，使其平行于世界平面。 |
| **最佳拟合平面** | 点击面上多个点 —— 对有噪点的扫描件具有鲁棒性。 |
| **2点 / 2孔直线** | 将两个特征之间的连线对齐到某个轴。 |
| **点 → 原点** | 将拾取的点移动到 (0,0,0)。 |
| **圆心 → 原点** | 点击圆/凹槽周围的点；拟合出的圆心（对聚类具有鲁棒性）将移动到原点。 |
| **圆心至圆心连线** | 两个拟合出的圆心 → 形成一条吸附到轴上的直线。 |
| **3-2-1 夹具定位** | 主面 + 次边 + 原点 —— 完全约束零件。 |
| **PCA 自动** | 根据零件的主轴一键定向。 |
| **降至底面** | 将最低点放置在 Z = 0 上。 |
3. 在视图窗口的模型上点击点。检查器会实时显示提议方案、残差以及最终生成的 transform；半透明的预览会展示其落点位置。
4. 在检查器中设置：
- **吸附至** — 目标对准哪个平面/轴（附带各自的自然语言描述）。
- **原点** — 零件 datum 的落点位置。
- **放置于轴/平面上** — *位于*目标上还是仅与它*平行*。
- **翻转 X / Y / Z** — 如果零件朝向错误，可添加绕任意轴 180° 的旋转。
- 对于 **3-2-1**：提供一个 **次边 → 轴** 选择器。
5. **提交**（或按 Enter 键）。重复使用更多工具以完全约束零件。
根据需要使用 **撤销 / 重做 / 重置**；每一步都列在 **History** 下。
6. **导出** — 对齐结果将被固化到一个带有溯源 header 的新 OBJ/PLY/STL 文件中。
**视口：** 左键拖拽旋转 · 右键/中键拖拽平移 · 滚轮缩放 · 左键点击添加 datum（只有模型是可点击的 —— 网格或坐标轴不可点击）。坐标轴颜色遵循 Fusion 规则：**X 红，Y 绿，Z 蓝**。
**键盘快捷键：** `Ctrl+O` 打开 · `Ctrl+S` 导出 · `Ctrl+Z/Y` 撤销/重做 · `Enter` 提交 · `Esc` 清除拾取 · `Del`/`Backspace` 移除上一个拾取点。
## 架构（简述）
- `ScanAlign.Core` — 纯几何、I/O、求解器、对齐工具、测量。无 UI 依赖。格式和工具通过反射发现，因此添加新功能只需添加一个类。
- `ScanAlign.App` — WPF (MVVM) 外壳，原生 WPF 3D 视口，编排（`SceneService`）。
- `ScanAlign.Tests` — xUnit；使用具有已知 ground truth 的黄金几何数据进行测试。
## 许可证
[MIT](LICENSE) © 2026 Stas Meirovich。免费供个人和商业使用；您可以修改和重新分发它，前提是保留版权声明。
## 作者
由 **Stas Meirovich** 创建。
标签：3D建模, CAD, .NET 8, WPF, 桌面应用