3d重建ios原生

关键词：iOS 3D 扫描、iPhone 3D 重建、Object Capture、PhotogrammetrySession、RealityKit、USDZ、SwiftUI、本机三维重建、离线 3D 建模、AR 模型预览。

 

## 项目用途

 

Rebuilder3D 的目标是验证并实现一套纯 iOS 本机 3D 重建流程：

 

- 使用 iPhone 相机围绕物体多角度拍摄。

- 使用 Apple Object Capture 引导用户采集物体照片。

- 在本机生成 3D 模型。

- 输出 `model.usdz`，可用于 AR Quick Look、RealityKit 预览和系统分享。

- 全流程本地运行，不需要云端服务器，不需要上传照片。

 

适合的使用场景：

 

- 小型商品、摆件、模型、工艺品的 3D 扫描原型。

- 学习 Apple Object Capture 和 RealityKit Photogrammetry。

- 构建离线 3D 扫描 App 的 MVP。

- 生成可在 iPhone / iPad 上预览和分享的 USDZ 模型。

 

## 开发环境

 

推荐开发环境：

 

- macOS：建议使用较新的 macOS 版本。

- Xcode：当前工程已用 Xcode 26.2 验证构建。

- iPhoneOS SDK：当前本机 SDK 为 26.2。

- Swift：Swift 5。

- UI 框架：SwiftUI。

- 最低部署版本：iOS 17.0。

- 网络要求：无。扫描和重建均在本机完成。

 

注意：需要真机验证，模拟器只能用于编译和普通 UI 检查。

 

## 核心功能

 

- 新建本机扫描任务。

- 展示 Apple 原生物体扫描界面。

- 支持检测物体、开始拍摄、完成扫描。

- 拍摄过程中按最高每秒 2 张的节奏请求照片。

- 当系统提示当前状态不适合拍照时自动跳过当前节拍。

- 扫描结束后使用本机重建。

- 重建前检查有效照片数量，少于 30 张会提示补拍。

- 重建失败时会尝试使用更保守配置自动重试一次。

- 生成 USDZ 模型并支持本地预览。

- 模型预览页提供关闭和分享入口。

- 扫描结果保存在 App 的 Application Support 目录中。

 

## 运行方法

 

在 macOS 上打开工程：

 

```bash

open Rebuilder3D.xcodeproj

```

 

中文说明：使用 Xcode 打开项目后，选择 iPhone 12 Pro Max 或其他支持的真机运行。首次启动时需要允许相机权限。

 

## 使用方法

 

1. 打开 App。

2. 点击右上角 `+` 新建扫描任务。

3. 将物体放在稳定桌面上，保持柔和、均匀的光线。

4. 点击 `检测物体`，让系统识别扫描目标。

5. 点击 `开始拍摄`，缓慢绕物体移动手机。

6. 尽量覆盖物体正面、侧面、背面、顶部和边缘。

7. 拍摄足够照片后点击 `完成扫描`。

8. 进入本机重建流程，等待生成 `model.usdz`。

9. 生成完成后点击预览，查看或分享 3D 模型。

 

建议每个物体保留 70 到 150 张有效照片。照片数量越少，重建失败或细节缺失的概率越高。

 

## 拍摄建议

 

为了获得更稳定的 iPhone 3D 重建效果，建议：

 

- 使用纹理明显、边缘清晰的物体。

- 避免透明玻璃、镜面金属、纯白、纯黑、毛发和会移动的物体。

- 保持物体不动，移动手机绕物体拍摄。

- 移动速度要慢，保证相邻照片有足够重叠。

- 光线要均匀，避免强阴影和过曝。

- 背景不要过于杂乱。

- 不要让手、身体或其他杂物遮挡物体。

 

## 技术架构

 

主要目录：

 

```text

Rebuilder3D/

  App/

    Rebuilder3DApp.swift

  Models/

    ScanJob.swift

  Services/

    ScanLibrary.swift

    CaptureViewModel.swift

    ReconstructionController.swift

  Views/

    HomeView.swift

    CaptureScreen.swift

    ReconstructionProgressView.swift

    QuickLookPreview.swift

```

 

核心模块说明：

 

- `CaptureViewModel`：管理 Object Capture 扫描状态、反馈信息、拍摄节拍和取消逻辑。

- `CaptureScreen`：展示原生 Object Capture 扫描界面和拍摄控制。

- `ReconstructionController`：管理 `PhotogrammetrySession` 本机重建流程。

- `ScanLibrary`：管理扫描任务目录、元数据和本地结果。

- `QuickLookPreview`：用于预览生成的 USDZ 模型。

 

## 输出文件

 

每个扫描任务会生成独立目录，主要包含：

 

- 原始采集图片目录。

- Object Capture checkpoint。

- Photogrammetry checkpoint。

- 输出模型目录。

- `model.usdz` 三维模型文件。

- `scan.json` 扫描任务元数据。

 

## 常见问题

 

### 为什么模拟器不能完整测试？

 

Object Capture 和本机 Photogrammetry 依赖真实设备相机、传感器和系统能力，模拟器不能完成真实物体扫描和三维重建。

 

### 为什么需要很多照片？

 

Apple 原生 Photogrammetry 属于多视角照片重建，系统需要通过大量重叠照片估计相机位姿、生成点云、构建网格并贴图。照片太少会导致对齐失败、模型缺面或重建失败。

 

### 遇到 `CoreOC.PhotogrammetrySession.Error error 6` 怎么办？

 

这是 Apple Object Capture 内部重建错误。项目已加入一次保守配置重试。如果仍然失败，建议重新扫描，增加不同角度照片，降低移动速度，改善光线，并避免反光、透明或纯色物体。

 

### 能不能完全离线使用？

 

可以。当前版本只依靠 iOS 原生能力，不连接服务器，不上传图片。本机完成拍摄、重建、预览和分享。

 

## 当前限制

 

- 目前主要输出 USDZ 模型。

- 高精度测量、工业扫描、3D 打印级拓扑不是当前 MVP 目标。

- 重建质量高度依赖物体材质、拍摄角度、照片数量和光照条件。

 

## 适合人群

 

- 想开发 iOS 3D 扫描 App 的开发者。

- 想验证 iPhone 离线三维重建流程的产品原型团队。

- 想把真实物体转换为 USDZ / AR 预览模型的移动端开发者。