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 上打开工程：

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 重建效果，建议：

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

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

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

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

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

• 背景不要过于杂乱。

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

技术架构

主要目录：

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 预览模型的移动端开发者。