1. 项目概述为什么我们需要空间网格如果你正在用 Unity 开发 PICO 上的 MR混合现实应用那么“空间网格”这个概念绝对是你绕不开的核心技术。简单来说空间网格就是让虚拟世界“理解”并“贴合”真实世界的桥梁。它通过头戴设备的传感器实时扫描你所在的物理空间——比如你家的客厅、办公室的桌面、房间的墙壁——并将这些物理表面的几何形状以三维网格的形式重建出来提供给 Unity 引擎使用。这听起来可能有点抽象我举个最直接的例子你想开发一个 MR 应用让一只虚拟的宠物猫在你的真实地板上行走或者让一个虚拟的台灯稳稳地放在你的真实书桌上。如果没有空间网格你只能把虚拟物体放在一个预设的、固定的虚拟坐标上它和真实世界毫无关系体验非常“出戏”。而有了空间网格你的应用就能知道“地板在哪里”、“桌面的高度和倾斜度是多少”从而让虚拟物体与真实环境发生真实的遮挡、碰撞和贴合关系沉浸感瞬间拉满。PICO 作为国内主流的 VR/MR 设备其 SDK 对空间网格提供了原生支持。而 Unity 作为最流行的实时内容创作引擎两者结合为我们开发者提供了一个强大且相对易用的 MR 开发平台。本指南的目的就是带你从零开始打通从 PICO 设备获取空间网格数据到在 Unity 中实际应用这些数据的完整链路避开我踩过的那些坑快速做出有说服力的 MR 原型或产品。2. 核心需求解析与方案选型在动手写代码之前我们必须先想清楚我们的 MR 应用到底需要空间网格来做什么不同的需求对应的技术方案和实现复杂度差异巨大。2.1 常见应用场景与对应需求根据我的项目经验空间网格的应用主要分为以下几个层次环境理解与可视化这是最基本的需求。应用需要“看到”环境并将网格渲染出来通常用于扫描阶段让用户知道哪些区域已被识别。例如扫描时显示半透明的网格提示用户正在建模。物理交互这是 MR 体验的核心。虚拟物体需要与真实环境发生物理交互比如子弹打在墙上留下弹痕、球在地面弹跳、虚拟角色靠在真实的沙发上。这需要将空间网格转换为 Unity 的物理碰撞体如MeshCollider。遮挡渲染为了实现虚拟物体被真实物体遮挡的效果例如虚拟的恐龙走到真实的书桌后面身体的一部分应该被遮挡。这需要将空间网格作为深度信息写入渲染管线通常涉及 URP通用渲染管线或自定义 Shader 的修改。空间锚定与持久化在特定位置如一面墙放置一个虚拟物品希望用户下次进入同一空间时物品还在原处。这需要将虚拟物体的坐标与空间网格的特定特征点或区域进行绑定。2.2 PICO Unity Integration SDK 方案解析PICO 官方提供了PICO Unity Integration SDK这是最推荐、也是最稳定的开发方案。它封装了底层 XR 子系统如 OpenXR的复杂性提供了更友好的 Unity 原生 API。对于空间网格该 SDK 主要提供了两种获取方式静态网格在应用启动时或用户触发时进行一次性的环境扫描生成一个完整的、固定的空间网格。适用于环境相对固定、不需要实时更新的场景如家具摆放应用。优点是性能开销小网格质量高。动态网格在应用运行期间持续扫描环境网格会随着用户移动和视角变化而实时更新和新增。适用于需要应对环境变化如人走过、门被打开的沉浸式游戏或工具。优点是灵活性高但性能开销较大且网格可能不断变化对物理和渲染逻辑提出更高要求。我的选型建议对于新手或大多数消费级应用从静态网格开始。它的 API 更简单状态更可控更容易调试。等你完全掌握了静态网格的数据流和处理方式后再根据项目需求评估是否引入动态网格。很多精彩的 MR 体验仅靠高质量的静态网格就足以实现。3. 开发环境搭建与核心配置工欲善其事必先利其器。一个正确配置的开发环境能避免 80% 的诡异问题。3.1 软硬件清单与版本控制硬件PICO 4 或 PICO Neo3 系列设备一台。务必开启开发者模式设置-通用-关于本机连续点击软件版本号并启用 USB 调试。一台性能足够的 Windows PC建议配备独立显卡用于 Unity 编辑和实机调试。一条高质量的 USB 3.0 数据线用于连接设备和电脑。软件Unity Hub Unity Editor我强烈建议使用Unity 2022.3 LTS版本。LTS长期支持版经过了充分测试与各种 SDK 的兼容性最好能极大减少因 Unity 版本问题导致的崩溃或功能异常。避免使用最新的非 LTS 版本除非 SDK 明确要求。PICO Unity Integration SDK前往 PICO 开发者平台官网在下载中心获取最新版本的 SDK。下载后是一个.unitypackage文件。Android Build Support模块在 Unity Hub 中安装 Unity 时务必勾选Android Build Support下的Android SDK NDK Tools以及OpenJDK。这是打包 APK 到安卓设备PICO的必备组件。3.2 创建项目与导入 SDK 的避坑指南创建项目通过 Unity Hub 创建一个新的 3D 项目Core 或 URP 模板均可本指南以 URP 为例因为未来做遮挡渲染更方便。项目名称和位置按自己习惯设置即可。导入 SDK在 Unity 编辑器中双击下载好的PICO_Unity_Integration_SDK_X.X.X.unitypackage文件会弹出导入窗口。这里有一个关键步骤不要无脑点击Import。展开列表仔细检查。通常SDK 会包含示例场景、插件、文档等。对于初次使用建议全部导入以确保功能完整。导入过程中Unity 可能会提示“更新旧的 API”或“重启编辑器”按提示操作即可。配置 Player Settings导入完成后SDK 通常会弹出一个配置向导窗口。如果没有你可以在菜单栏找到PXR_SDK - Platform Tools。目标设备选择你拥有的设备型号如 PICO 4。渲染模式选择Single Pass Instanced。这是 VR/MR 应用的标准渲染模式比传统的多通道渲染性能高出一倍。深度提交务必勾选Enable Depth Submission。这个选项对于后续实现空间网格的遮挡渲染至关重要它允许 Unity 将深度信息提交给系统合成层。空间网格开关在Features或XR Plugin Management中找到 PICO XR Plugin 的设置确保Spatial Mapping或Mesh Tracking功能被启用。3.3 配置 URP 管线以支持 MR 渲染如果你使用的是 URP 模板还需要进行额外配置以确保渲染兼容性。在 Project 窗口找到PXR_SDK - Runtime - Resources下的PXR_URP_Renderer渲染器资产。打开你的 URP 资产通常位于Settings文件夹名为UniversalRP-HighQuality或类似在Renderer List中将默认的渲染器替换为PXR_URP_Renderer。检查PXR_URP_Renderer的Renderer Features确保包含了PXR_Overlay等必要的特性。这一步是为了正确处理 PICO 系统的叠加层和性能优化。完成以上步骤你的基础开发环境就搭建好了。接下来我们将进入核心的代码实战环节。4. 空间网格数据获取实战理论说再多不如一行代码。让我们在 Unity 中创建一个最简单的场景来获取并显示空间网格。4.1 创建场景与基础脚本在 Unity 场景中删除默认的Main Camera。从PXR_SDK - Prefabs文件夹中将PXR_Manager预制体拖入场景。这个预制体是 PICO SDK 运行的总控制器会自动创建所需的相机和控制器。创建一个空的 GameObject命名为SpatialMeshManager。我们将把管理逻辑挂在这里。创建一个新的 C# 脚本命名为PicoSpatialMeshDemo并将其挂载到SpatialMeshManager上。4.2 编写静态网格扫描与生成代码打开PicoSpatialMeshDemo.cs脚本我们将实现一个基础的静态网格扫描流程。using UnityEngine; using Pico.Platform; using Pico.Platform.Models; using Pico.Platform.Space; using System.Collections.Generic; public class PicoSpatialMeshDemo : MonoBehaviour { // 用于存储生成的网格物体 private ListGameObject _meshGameObjects new ListGameObject(); // 网格渲染材质通常为半透明用于可视化 public Material meshVisualizationMaterial; void Start() { // 1. 初始化 PICO SDK 核心服务 // 这一步通常在 PXR_Manager 中完成但确保它已执行 if (!CoreService.Initialized) { Debug.LogError(PICO CoreService not initialized. Check PXR_Manager.); return; } Debug.Log(PicoSpatialMeshDemo Started.); // 2. 开始空间网格扫描示例延迟2秒后开始 Invoke(nameof(StartMeshScan), 2.0f); } void StartMeshScan() { Debug.Log(Starting Spatial Mesh Scan...); // 配置扫描参数 var scanConfig new SpatialMappingConfig { // 扫描模式Static 静态网格 SceneType SpatialMappingSceneType.Static, // 扫描范围建议根据应用场景调整太大影响性能 BoundingBoxSize new Vector3(10, 3, 10), // 10m x 3m x 10m 的立方体范围 // 网格分辨率三角形目标边长米值越小精度越高数据量越大 TriangleSize 0.1f, // 是否保存到本地文件用于持久化 SaveToLocal false }; // 启动扫描 var task SpatialMappingService.StartSceneCapture(scanConfig); task.OnComplete OnSceneCaptureComplete; } void OnSceneCaptureComplete(MessageSpaceSceneCaptureResult msg) { if (msg.IsError) { Debug.LogError($Scene Capture Failed: {msg.Error.Message}); return; } Debug.Log(Scene Capture Completed Successfully!); var result msg.Data; // 3. 获取扫描到的网格数据 var loadTask SpatialMappingService.GetSceneMesh(result.SceneId); loadTask.OnComplete OnSceneMeshLoaded; } void OnSceneMeshLoaded(MessageSpaceSceneMesh msg) { if (msg.IsError) { Debug.LogError($Load Scene Mesh Failed: {msg.Error.Message}); return; } Debug.Log(Scene Mesh Data Loaded.); var sceneMesh msg.Data; // 4. 将 PICO 的网格数据转换为 Unity 的 Mesh 并渲染 ProcessAndVisualizeMesh(sceneMesh); } void ProcessAndVisualizeMesh(SpaceSceneMesh sceneMesh) { // 清理之前生成的网格物体 foreach (var go in _meshGameObjects) { Destroy(go); } _meshGameObjects.Clear(); // 遍历场景网格中的所有子网格块ScanResultBlock foreach (var block in sceneMesh.Blocks) { // 创建新的 GameObject 来承载这个网格块 GameObject meshGo new GameObject($SpatialMeshBlock_{block.BlockId}); meshGo.transform.SetParent(this.transform); // 添加 MeshFilter 和 MeshRenderer 组件 MeshFilter meshFilter meshGo.AddComponentMeshFilter(); MeshRenderer meshRenderer meshGo.AddComponentMeshRenderer(); // 将 PICO 的顶点、索引数据转换为 Unity Mesh Mesh unityMesh new Mesh(); // 注意PICO SDK返回的顶点数据可能是右手坐标系需要转换为Unity的左手系。 // 这里假设SDK已处理如果模型朝向不对可能需要手动转换顶点坐标。 unityMesh.vertices block.Positions; // Vector3[] 顶点数组 unityMesh.triangles block.Indices; // int[] 三角形索引数组 // 如果有法线信息可以赋值某些扫描模式可能不包含 if (block.Normals ! null block.Normals.Length block.Positions.Length) { unityMesh.normals block.Normals; } else { unityMesh.RecalculateNormals(); // 重新计算法线 } // 计算包围盒和切线可选 unityMesh.RecalculateBounds(); meshFilter.mesh unityMesh; meshRenderer.material meshVisualizationMaterial; _meshGameObjects.Add(meshGo); } Debug.Log($Generated {_meshGameObjects.Count} mesh blocks.); } }4.3 关键参数详解与性能权衡在SpatialMappingConfig中有几个参数对结果影响巨大TriangleSize这是最重要的参数之一单位是米。它决定了生成网格的精度。设为0.05f会得到非常精细的网格适合需要高精度碰撞或贴图的场景但数据量会呈指数级增长可能导致加载缓慢甚至内存溢出。设为0.2f则网格粗糙但性能极佳。我的经验是对于大多数室内场景和物理交互0.1f是一个很好的平衡点既能看清家具轮廓又不会给性能带来太大压力。BoundingBoxSize定义了扫描的边界框。不要盲目设得太大只扫描你应用真正需要的区域。比如一个桌面级应用范围设为(2, 1, 2)足矣。减少范围能显著提升扫描速度和降低数据处理开销。SceneTypeStatic与Dynamic的选择。如之前所述新手务必从Static开始。Dynamic模式需要处理持续的数据流和网格更新逻辑复杂得多。实操心得在编辑器模式下你可以先使用一个较大的TriangleSize如0.15f进行快速迭代测试验证核心逻辑。在最终打包到真机前再调整为更精细的值。同时记得在ProcessAndVisualizeMesh方法中对生成的GameObject设置合理的 Layer便于后续的射线检测或摄像机剔除管理。5. 从可视化到物理交互仅仅看到网格还不够我们的目标是让虚拟物体能与它互动。这就需要将空间网格转换为物理碰撞体。5.1 为空间网格添加 Mesh Collider修改上面的ProcessAndVisualizeMesh方法在创建MeshRenderer的同时为每个网格块添加MeshCollider。void ProcessAndVisualizeMesh(SpaceSceneMesh sceneMesh) { // ... [清理旧网格的代码保持不变] ... foreach (var block in sceneMesh.Blocks) { GameObject meshGo new GameObject($SpatialMeshBlock_{block.BlockId}); meshGo.transform.SetParent(this.transform); meshGo.layer LayerMask.NameToLayer(SpatialMesh); // 建议设置专用层 MeshFilter meshFilter meshGo.AddComponentMeshFilter(); MeshRenderer meshRenderer meshGo.AddComponentMeshRenderer(); // 创建 Unity Mesh Mesh unityMesh new Mesh(); unityMesh.vertices block.Positions; unityMesh.triangles block.Indices; // ... [计算法线等代码] ... unityMesh.RecalculateBounds(); meshFilter.mesh unityMesh; meshRenderer.material meshVisualizationMaterial; // 核心步骤添加 Mesh Collider MeshCollider meshCollider meshGo.AddComponentMeshCollider(); meshCollider.sharedMesh unityMesh; // 根据需求设置 Collider 属性 meshCollider.convex false; // 空间网格通常是非凸的必须设为 false _meshGameObjects.Add(meshGo); } }现在你的空间网格就拥有了物理属性。你可以在场景中放置一个带有Rigidbody的 Cube运行程序扫描环境后将这个 Cube 拖拽到真实桌面扫描出的网格对应的虚拟位置松手后它应该会受重力影响掉落在“桌面”上并停住。5.2 性能优化Mesh Collider 的陷阱与解决方案直接为每个网格块添加MeshCollider虽然简单但在网格复杂三角形数量多时物理引擎的计算开销会非常大可能导致严重的卡顿。这是新手最容易踩的坑。优化方案使用简化碰撞体或分层碰撞生成简化网格不要用渲染用的精细网格直接做碰撞体。可以使用 Unity 的MeshSimplifier插件或开源库或者自己在代码中生成一个精度更低TriangleSize更大的专用碰撞网格。使用 Primitive Colliders 近似对于规则表面用BoxCollider、SphereCollider、CapsuleCollider来近似往往效率更高。你可以写一个算法分析网格块的形状用少数几个基本碰撞体来拟合它。例如一面墙可以用一个薄薄的BoxCollider代替。分层碰撞策略不是所有网格都需要参与精细碰撞。对于地面一个简单的BoxCollider足矣。对于玩家需要交互的特定物体如桌面、沙发才使用相对精细的MeshCollider。可以通过分析网格的法线垂直向上的是地面垂直向侧面的是墙壁或位置信息来自动化这一过程。// 伪代码示例根据法线判断并添加简单碰撞体 void AddOptimizedCollider(GameObject go, Mesh mesh) { // 计算网格的平均法线需遍历顶点法线 Vector3 avgNormal CalculateAverageNormal(mesh); if (avgNormal.y 0.8f) // 大致朝上认为是地面 { BoxCollider col go.AddComponentBoxCollider(); col.center mesh.bounds.center; col.size mesh.bounds.size; } else if (Mathf.Abs(avgNormal.y) 0.3f) // 大致垂直认为是墙壁 { // 墙壁也可以用Box但可能更薄 BoxCollider col go.AddComponentBoxCollider(); col.center mesh.bounds.center; col.size new Vector3(mesh.bounds.size.x, mesh.bounds.size.y, 0.1f); // 很薄 } else // 其他复杂形状使用MeshCollider但用简化网格 { Mesh simplifiedMesh SimplifyMesh(mesh, 0.5f); // 简化50% MeshCollider col go.AddComponentMeshCollider(); col.sharedMesh simplifiedMesh; } }6. 实现遮挡渲染让虚拟融入现实物理交互有了但视觉上虚拟物体还是“飘”在现实世界上。要实现虚拟物体被真实物体遮挡需要用到深度提交和渲染管线配置。6.1 理解深度提交原理在 MR 中头显的摄像头会持续拍摄真实世界视频透视。我们的虚拟场景则通过 Unity 渲染。要将两者合成系统需要知道每个像素点是真实世界的更近还是虚拟物体的更近。这就是深度信息的作用。当我们启用了Enable Depth Submission后Unity 在渲染虚拟场景时不仅会输出颜色图像还会输出对应的深度图。PICO 系统在合成最终画面时会对比虚拟深度和通过空间网格估算出的真实环境深度从而决定哪个像素应该被显示。如果真实桌子空间网格的深度值比虚拟的杯子小离眼睛更近那么杯子在桌子后面的部分就会被正确遮挡。6.2 在 URP 中配置遮挡材质仅仅提交深度还不够我们需要确保空间网格本身在渲染时也写入深度但不一定写入颜色因为我们不想看到一个有颜色的网格挡住所有东西。创建专用的遮挡材质在 Project 窗口右键Create - Material命名为SpatialMeshOcclusion。将它的 Shader 改为PICO XR/URP/Spatial Mesh Occlusion这个 Shader 通常由 PICO SDK 提供。如果找不到可以使用 URP 自带的UnlitShader然后进行以下关键设置Surface Type设置为Transparent。Blending设置为AlphaSrcBlendZero,DstBlendOne。这个混合模式意味着不输出任何颜色Zero只保留源像素的 Alpha 和深度。但更关键的是下一步。最重要的是在Depth Write上打勾但将Depth Test设置为Less Equal。同时关闭Color Write Mask即 RGB 通道全不勾选。这样这个材质渲染的网格只会向深度缓冲区写入深度值而不影响最终屏幕颜色。应用遮挡材质修改我们的PicoSpatialMeshDemo脚本提供两个材质选项一个用于可视化半透明一个用于纯遮挡。public Material meshVisualizationMaterial; // 半透明可视化材质 public Material meshOcclusionMaterial; // 纯遮挡材质 private bool useOcclusionMode false; // 切换开关 void ProcessAndVisualizeMesh(SpaceSceneMesh sceneMesh) { // ... Material materialToUse useOcclusionMode ? meshOcclusionMaterial : meshVisualizationMaterial; meshRenderer.material materialToUse; // ... }测试遮挡效果运行程序扫描房间。切换到遮挡模式将useOcclusionMode设为 true。此时空间网格应该“消失”了因为它不输出颜色。然后将一个红色的 Cube 放在虚拟的“墙面”后面。当你移动视角让 Cube 位于真实墙面被扫描的网格区域后方时Cube 被遮挡的部分应该不可见。如果 Cube 始终完整显示说明深度测试或深度提交未正确生效需要检查 Player Settings 中的Enable Depth Submission和材质的深度设置。注意事项遮挡渲染对性能有额外消耗并且要求空间网格的深度信息足够准确。如果网格扫描质量差有空洞或抖动遮挡会出现闪烁或错误。在移动端设备上需要权衡视觉精度和性能。通常用于遮挡的网格可以使用比可视化网格更低的精度更大的TriangleSize。7. 常见问题排查与性能优化实录在实际开发中你一定会遇到各种问题。下面是我总结的“血泪”清单。7.1 网格扫描失败或数据为空现象调用StartSceneCapture后回调失败或者GetSceneMesh返回的Blocks列表为空。排查步骤检查权限在 PICO 设备上首次使用需要授予应用“空间数据访问”权限。确保你的应用已获得授权。可以在代码中监听权限回调。检查光照空间扫描依赖设备的 SLAM同步定位与地图构建功能在光线过暗或纹理特征极少如纯白墙壁的环境下SLAM 可能失效导致扫描失败。确保在光线充足、纹理丰富的环境下进行扫描。检查设备朝向扫描初期需要缓慢移动设备让摄像头捕捉到不同角度的环境特征。静止不动或移动过快都会导致扫描失败。查看日志连接设备到电脑在 Unity Editor 的Console窗口或使用adb logcat查看 PICO SDK 输出的详细错误信息。7.2 网格显示位置错乱或抖动现象生成的网格飘在空中或者随着头显移动而轻微抖动。原因与解决坐标系未转换PICO 返回的网格数据可能基于其自身的坐标系如右手系、Y轴向上而 Unity 是左手系、Y轴向上。虽然 SDK 通常做了处理但如果发现严重错位可能需要手动转换顶点坐标例如对 Z 轴取反。世界锚定问题确保你的PXR_Manager或场景原点在世界中稳定。在 MR 应用中虚拟世界的原点最好与设备的初始位置或某个空间锚点对齐。可以研究 PICO SDK 中的Space服务使用SpaceBinding来将虚拟物体持久化到特定空间位置这也有助于稳定全局坐标系。7.3 应用性能严重下降卡顿现象扫描完成后应用帧率FPS骤降。性能瓶颈分析Draw Call 激增每个网格块GameObject都会产生至少一个 Draw Call。如果扫描出上百个网格块Draw Call 数会爆炸。解决方案使用Mesh.CombineMeshes方法将相邻或材质相同的多个小网格合并成一个大网格能大幅减少 Draw Call。ListMeshFilter meshFilters new ListMeshFilter(); // ... 收集所有需要合并的 MeshFilter ... CombineInstance[] combine new CombineInstance[meshFilters.Count]; for (int i 0; i meshFilters.Count; i) { combine[i].mesh meshFilters[i].sharedMesh; combine[i].transform meshFilters[i].transform.localToWorldMatrix; meshFilters[i].gameObject.SetActive(false); // 合并后禁用原物体 } Mesh combinedMesh new Mesh(); combinedMesh.CombineMeshes(combine); // 创建一个新的GameObject来使用这个合并后的大Mesh物理计算开销如前所述复杂的MeshCollider是性能杀手。务必使用 5.2 节提到的优化方案。网格数据量过大TriangleSize设置过小会导致顶点和三角形数量巨大不仅占用内存也增加 GPU 渲染负担。永远根据实际需要选择最低可接受的精度。动态网格更新如果使用动态网格模式每帧都可能需要处理网格更新和重建CPU 开销极大。除非必要否则使用静态网格。7.4 打包到设备后功能异常现象在 Unity Editor 里运行正常打包成 APK 安装到 PICO 后扫描不工作或渲染异常。排查清单检查 SDK 版本兼容性确认你使用的 PICO SDK 版本与 Unity 版本、PICO 设备系统版本兼容。有时需要更新到最新的 SDK。检查 Player Settings 中的 XR Plug-in Management确保PICO XR Plugin已被正确添加且勾选。打包时Unity 有时会丢失这些设置。检查清单文件AndroidManifest.xmlPICO SDK 可能会自动添加必要的权限如android.permission.SPATIAL_MAPPING。如果手动修改过清单文件可能破坏了这些配置。对比 SDK 导入前后的清单文件。检查图形 API在 Player Settings - Other Settings 中确保Graphics APIs列表里Vulkan在 OpenGL ES3 之上或者只使用 Vulkan。PICO 设备对 Vulkan 的支持通常更好。但注意某些 Unity 版本或 Shader 与 Vulkan 可能存在兼容性问题如果遇到渲染问题可以尝试切换回 OpenGL ES3。开发 MR 应用是一个不断在效果和性能之间寻找平衡的过程。从最简单的可视化开始逐步增加物理、遮挡等特性并持续进行性能剖析使用 Unity Profiler 和 PICO 自带的 Metrics HUD 工具才能打造出既沉浸又流畅的体验。希望这份实战指南能为你铺平道路祝你开发顺利。
1. 项目概述为什么我们需要空间网格如果你正在用 Unity 开发 PICO 上的 MR混合现实应用那么“空间网格”这个概念绝对是你绕不开的核心技术。简单来说空间网格就是让虚拟世界“理解”并“贴合”真实世界的桥梁。它通过头戴设备的传感器实时扫描你所在的物理空间——比如你家的客厅、办公室的桌面、房间的墙壁——并将这些物理表面的几何形状以三维网格的形式重建出来提供给 Unity 引擎使用。这听起来可能有点抽象我举个最直接的例子你想开发一个 MR 应用让一只虚拟的宠物猫在你的真实地板上行走或者让一个虚拟的台灯稳稳地放在你的真实书桌上。如果没有空间网格你只能把虚拟物体放在一个预设的、固定的虚拟坐标上它和真实世界毫无关系体验非常“出戏”。而有了空间网格你的应用就能知道“地板在哪里”、“桌面的高度和倾斜度是多少”从而让虚拟物体与真实环境发生真实的遮挡、碰撞和贴合关系沉浸感瞬间拉满。PICO 作为国内主流的 VR/MR 设备其 SDK 对空间网格提供了原生支持。而 Unity 作为最流行的实时内容创作引擎两者结合为我们开发者提供了一个强大且相对易用的 MR 开发平台。本指南的目的就是带你从零开始打通从 PICO 设备获取空间网格数据到在 Unity 中实际应用这些数据的完整链路避开我踩过的那些坑快速做出有说服力的 MR 原型或产品。2. 核心需求解析与方案选型在动手写代码之前我们必须先想清楚我们的 MR 应用到底需要空间网格来做什么不同的需求对应的技术方案和实现复杂度差异巨大。2.1 常见应用场景与对应需求根据我的项目经验空间网格的应用主要分为以下几个层次环境理解与可视化这是最基本的需求。应用需要“看到”环境并将网格渲染出来通常用于扫描阶段让用户知道哪些区域已被识别。例如扫描时显示半透明的网格提示用户正在建模。物理交互这是 MR 体验的核心。虚拟物体需要与真实环境发生物理交互比如子弹打在墙上留下弹痕、球在地面弹跳、虚拟角色靠在真实的沙发上。这需要将空间网格转换为 Unity 的物理碰撞体如MeshCollider。遮挡渲染为了实现虚拟物体被真实物体遮挡的效果例如虚拟的恐龙走到真实的书桌后面身体的一部分应该被遮挡。这需要将空间网格作为深度信息写入渲染管线通常涉及 URP通用渲染管线或自定义 Shader 的修改。空间锚定与持久化在特定位置如一面墙放置一个虚拟物品希望用户下次进入同一空间时物品还在原处。这需要将虚拟物体的坐标与空间网格的特定特征点或区域进行绑定。2.2 PICO Unity Integration SDK 方案解析PICO 官方提供了PICO Unity Integration SDK这是最推荐、也是最稳定的开发方案。它封装了底层 XR 子系统如 OpenXR的复杂性提供了更友好的 Unity 原生 API。对于空间网格该 SDK 主要提供了两种获取方式静态网格在应用启动时或用户触发时进行一次性的环境扫描生成一个完整的、固定的空间网格。适用于环境相对固定、不需要实时更新的场景如家具摆放应用。优点是性能开销小网格质量高。动态网格在应用运行期间持续扫描环境网格会随着用户移动和视角变化而实时更新和新增。适用于需要应对环境变化如人走过、门被打开的沉浸式游戏或工具。优点是灵活性高但性能开销较大且网格可能不断变化对物理和渲染逻辑提出更高要求。我的选型建议对于新手或大多数消费级应用从静态网格开始。它的 API 更简单状态更可控更容易调试。等你完全掌握了静态网格的数据流和处理方式后再根据项目需求评估是否引入动态网格。很多精彩的 MR 体验仅靠高质量的静态网格就足以实现。3. 开发环境搭建与核心配置工欲善其事必先利其器。一个正确配置的开发环境能避免 80% 的诡异问题。3.1 软硬件清单与版本控制硬件PICO 4 或 PICO Neo3 系列设备一台。务必开启开发者模式设置-通用-关于本机连续点击软件版本号并启用 USB 调试。一台性能足够的 Windows PC建议配备独立显卡用于 Unity 编辑和实机调试。一条高质量的 USB 3.0 数据线用于连接设备和电脑。软件Unity Hub Unity Editor我强烈建议使用Unity 2022.3 LTS版本。LTS长期支持版经过了充分测试与各种 SDK 的兼容性最好能极大减少因 Unity 版本问题导致的崩溃或功能异常。避免使用最新的非 LTS 版本除非 SDK 明确要求。PICO Unity Integration SDK前往 PICO 开发者平台官网在下载中心获取最新版本的 SDK。下载后是一个.unitypackage文件。Android Build Support模块在 Unity Hub 中安装 Unity 时务必勾选Android Build Support下的Android SDK NDK Tools以及OpenJDK。这是打包 APK 到安卓设备PICO的必备组件。3.2 创建项目与导入 SDK 的避坑指南创建项目通过 Unity Hub 创建一个新的 3D 项目Core 或 URP 模板均可本指南以 URP 为例因为未来做遮挡渲染更方便。项目名称和位置按自己习惯设置即可。导入 SDK在 Unity 编辑器中双击下载好的PICO_Unity_Integration_SDK_X.X.X.unitypackage文件会弹出导入窗口。这里有一个关键步骤不要无脑点击Import。展开列表仔细检查。通常SDK 会包含示例场景、插件、文档等。对于初次使用建议全部导入以确保功能完整。导入过程中Unity 可能会提示“更新旧的 API”或“重启编辑器”按提示操作即可。配置 Player Settings导入完成后SDK 通常会弹出一个配置向导窗口。如果没有你可以在菜单栏找到PXR_SDK - Platform Tools。目标设备选择你拥有的设备型号如 PICO 4。渲染模式选择Single Pass Instanced。这是 VR/MR 应用的标准渲染模式比传统的多通道渲染性能高出一倍。深度提交务必勾选Enable Depth Submission。这个选项对于后续实现空间网格的遮挡渲染至关重要它允许 Unity 将深度信息提交给系统合成层。空间网格开关在Features或XR Plugin Management中找到 PICO XR Plugin 的设置确保Spatial Mapping或Mesh Tracking功能被启用。3.3 配置 URP 管线以支持 MR 渲染如果你使用的是 URP 模板还需要进行额外配置以确保渲染兼容性。在 Project 窗口找到PXR_SDK - Runtime - Resources下的PXR_URP_Renderer渲染器资产。打开你的 URP 资产通常位于Settings文件夹名为UniversalRP-HighQuality或类似在Renderer List中将默认的渲染器替换为PXR_URP_Renderer。检查PXR_URP_Renderer的Renderer Features确保包含了PXR_Overlay等必要的特性。这一步是为了正确处理 PICO 系统的叠加层和性能优化。完成以上步骤你的基础开发环境就搭建好了。接下来我们将进入核心的代码实战环节。4. 空间网格数据获取实战理论说再多不如一行代码。让我们在 Unity 中创建一个最简单的场景来获取并显示空间网格。4.1 创建场景与基础脚本在 Unity 场景中删除默认的Main Camera。从PXR_SDK - Prefabs文件夹中将PXR_Manager预制体拖入场景。这个预制体是 PICO SDK 运行的总控制器会自动创建所需的相机和控制器。创建一个空的 GameObject命名为SpatialMeshManager。我们将把管理逻辑挂在这里。创建一个新的 C# 脚本命名为PicoSpatialMeshDemo并将其挂载到SpatialMeshManager上。4.2 编写静态网格扫描与生成代码打开PicoSpatialMeshDemo.cs脚本我们将实现一个基础的静态网格扫描流程。using UnityEngine; using Pico.Platform; using Pico.Platform.Models; using Pico.Platform.Space; using System.Collections.Generic; public class PicoSpatialMeshDemo : MonoBehaviour { // 用于存储生成的网格物体 private ListGameObject _meshGameObjects new ListGameObject(); // 网格渲染材质通常为半透明用于可视化 public Material meshVisualizationMaterial; void Start() { // 1. 初始化 PICO SDK 核心服务 // 这一步通常在 PXR_Manager 中完成但确保它已执行 if (!CoreService.Initialized) { Debug.LogError(PICO CoreService not initialized. Check PXR_Manager.); return; } Debug.Log(PicoSpatialMeshDemo Started.); // 2. 开始空间网格扫描示例延迟2秒后开始 Invoke(nameof(StartMeshScan), 2.0f); } void StartMeshScan() { Debug.Log(Starting Spatial Mesh Scan...); // 配置扫描参数 var scanConfig new SpatialMappingConfig { // 扫描模式Static 静态网格 SceneType SpatialMappingSceneType.Static, // 扫描范围建议根据应用场景调整太大影响性能 BoundingBoxSize new Vector3(10, 3, 10), // 10m x 3m x 10m 的立方体范围 // 网格分辨率三角形目标边长米值越小精度越高数据量越大 TriangleSize 0.1f, // 是否保存到本地文件用于持久化 SaveToLocal false }; // 启动扫描 var task SpatialMappingService.StartSceneCapture(scanConfig); task.OnComplete OnSceneCaptureComplete; } void OnSceneCaptureComplete(MessageSpaceSceneCaptureResult msg) { if (msg.IsError) { Debug.LogError($Scene Capture Failed: {msg.Error.Message}); return; } Debug.Log(Scene Capture Completed Successfully!); var result msg.Data; // 3. 获取扫描到的网格数据 var loadTask SpatialMappingService.GetSceneMesh(result.SceneId); loadTask.OnComplete OnSceneMeshLoaded; } void OnSceneMeshLoaded(MessageSpaceSceneMesh msg) { if (msg.IsError) { Debug.LogError($Load Scene Mesh Failed: {msg.Error.Message}); return; } Debug.Log(Scene Mesh Data Loaded.); var sceneMesh msg.Data; // 4. 将 PICO 的网格数据转换为 Unity 的 Mesh 并渲染 ProcessAndVisualizeMesh(sceneMesh); } void ProcessAndVisualizeMesh(SpaceSceneMesh sceneMesh) { // 清理之前生成的网格物体 foreach (var go in _meshGameObjects) { Destroy(go); } _meshGameObjects.Clear(); // 遍历场景网格中的所有子网格块ScanResultBlock foreach (var block in sceneMesh.Blocks) { // 创建新的 GameObject 来承载这个网格块 GameObject meshGo new GameObject($SpatialMeshBlock_{block.BlockId}); meshGo.transform.SetParent(this.transform); // 添加 MeshFilter 和 MeshRenderer 组件 MeshFilter meshFilter meshGo.AddComponentMeshFilter(); MeshRenderer meshRenderer meshGo.AddComponentMeshRenderer(); // 将 PICO 的顶点、索引数据转换为 Unity Mesh Mesh unityMesh new Mesh(); // 注意PICO SDK返回的顶点数据可能是右手坐标系需要转换为Unity的左手系。 // 这里假设SDK已处理如果模型朝向不对可能需要手动转换顶点坐标。 unityMesh.vertices block.Positions; // Vector3[] 顶点数组 unityMesh.triangles block.Indices; // int[] 三角形索引数组 // 如果有法线信息可以赋值某些扫描模式可能不包含 if (block.Normals ! null block.Normals.Length block.Positions.Length) { unityMesh.normals block.Normals; } else { unityMesh.RecalculateNormals(); // 重新计算法线 } // 计算包围盒和切线可选 unityMesh.RecalculateBounds(); meshFilter.mesh unityMesh; meshRenderer.material meshVisualizationMaterial; _meshGameObjects.Add(meshGo); } Debug.Log($Generated {_meshGameObjects.Count} mesh blocks.); } }4.3 关键参数详解与性能权衡在SpatialMappingConfig中有几个参数对结果影响巨大TriangleSize这是最重要的参数之一单位是米。它决定了生成网格的精度。设为0.05f会得到非常精细的网格适合需要高精度碰撞或贴图的场景但数据量会呈指数级增长可能导致加载缓慢甚至内存溢出。设为0.2f则网格粗糙但性能极佳。我的经验是对于大多数室内场景和物理交互0.1f是一个很好的平衡点既能看清家具轮廓又不会给性能带来太大压力。BoundingBoxSize定义了扫描的边界框。不要盲目设得太大只扫描你应用真正需要的区域。比如一个桌面级应用范围设为(2, 1, 2)足矣。减少范围能显著提升扫描速度和降低数据处理开销。SceneTypeStatic与Dynamic的选择。如之前所述新手务必从Static开始。Dynamic模式需要处理持续的数据流和网格更新逻辑复杂得多。实操心得在编辑器模式下你可以先使用一个较大的TriangleSize如0.15f进行快速迭代测试验证核心逻辑。在最终打包到真机前再调整为更精细的值。同时记得在ProcessAndVisualizeMesh方法中对生成的GameObject设置合理的 Layer便于后续的射线检测或摄像机剔除管理。5. 从可视化到物理交互仅仅看到网格还不够我们的目标是让虚拟物体能与它互动。这就需要将空间网格转换为物理碰撞体。5.1 为空间网格添加 Mesh Collider修改上面的ProcessAndVisualizeMesh方法在创建MeshRenderer的同时为每个网格块添加MeshCollider。void ProcessAndVisualizeMesh(SpaceSceneMesh sceneMesh) { // ... [清理旧网格的代码保持不变] ... foreach (var block in sceneMesh.Blocks) { GameObject meshGo new GameObject($SpatialMeshBlock_{block.BlockId}); meshGo.transform.SetParent(this.transform); meshGo.layer LayerMask.NameToLayer(SpatialMesh); // 建议设置专用层 MeshFilter meshFilter meshGo.AddComponentMeshFilter(); MeshRenderer meshRenderer meshGo.AddComponentMeshRenderer(); // 创建 Unity Mesh Mesh unityMesh new Mesh(); unityMesh.vertices block.Positions; unityMesh.triangles block.Indices; // ... [计算法线等代码] ... unityMesh.RecalculateBounds(); meshFilter.mesh unityMesh; meshRenderer.material meshVisualizationMaterial; // 核心步骤添加 Mesh Collider MeshCollider meshCollider meshGo.AddComponentMeshCollider(); meshCollider.sharedMesh unityMesh; // 根据需求设置 Collider 属性 meshCollider.convex false; // 空间网格通常是非凸的必须设为 false _meshGameObjects.Add(meshGo); } }现在你的空间网格就拥有了物理属性。你可以在场景中放置一个带有Rigidbody的 Cube运行程序扫描环境后将这个 Cube 拖拽到真实桌面扫描出的网格对应的虚拟位置松手后它应该会受重力影响掉落在“桌面”上并停住。5.2 性能优化Mesh Collider 的陷阱与解决方案直接为每个网格块添加MeshCollider虽然简单但在网格复杂三角形数量多时物理引擎的计算开销会非常大可能导致严重的卡顿。这是新手最容易踩的坑。优化方案使用简化碰撞体或分层碰撞生成简化网格不要用渲染用的精细网格直接做碰撞体。可以使用 Unity 的MeshSimplifier插件或开源库或者自己在代码中生成一个精度更低TriangleSize更大的专用碰撞网格。使用 Primitive Colliders 近似对于规则表面用BoxCollider、SphereCollider、CapsuleCollider来近似往往效率更高。你可以写一个算法分析网格块的形状用少数几个基本碰撞体来拟合它。例如一面墙可以用一个薄薄的BoxCollider代替。分层碰撞策略不是所有网格都需要参与精细碰撞。对于地面一个简单的BoxCollider足矣。对于玩家需要交互的特定物体如桌面、沙发才使用相对精细的MeshCollider。可以通过分析网格的法线垂直向上的是地面垂直向侧面的是墙壁或位置信息来自动化这一过程。// 伪代码示例根据法线判断并添加简单碰撞体 void AddOptimizedCollider(GameObject go, Mesh mesh) { // 计算网格的平均法线需遍历顶点法线 Vector3 avgNormal CalculateAverageNormal(mesh); if (avgNormal.y 0.8f) // 大致朝上认为是地面 { BoxCollider col go.AddComponentBoxCollider(); col.center mesh.bounds.center; col.size mesh.bounds.size; } else if (Mathf.Abs(avgNormal.y) 0.3f) // 大致垂直认为是墙壁 { // 墙壁也可以用Box但可能更薄 BoxCollider col go.AddComponentBoxCollider(); col.center mesh.bounds.center; col.size new Vector3(mesh.bounds.size.x, mesh.bounds.size.y, 0.1f); // 很薄 } else // 其他复杂形状使用MeshCollider但用简化网格 { Mesh simplifiedMesh SimplifyMesh(mesh, 0.5f); // 简化50% MeshCollider col go.AddComponentMeshCollider(); col.sharedMesh simplifiedMesh; } }6. 实现遮挡渲染让虚拟融入现实物理交互有了但视觉上虚拟物体还是“飘”在现实世界上。要实现虚拟物体被真实物体遮挡需要用到深度提交和渲染管线配置。6.1 理解深度提交原理在 MR 中头显的摄像头会持续拍摄真实世界视频透视。我们的虚拟场景则通过 Unity 渲染。要将两者合成系统需要知道每个像素点是真实世界的更近还是虚拟物体的更近。这就是深度信息的作用。当我们启用了Enable Depth Submission后Unity 在渲染虚拟场景时不仅会输出颜色图像还会输出对应的深度图。PICO 系统在合成最终画面时会对比虚拟深度和通过空间网格估算出的真实环境深度从而决定哪个像素应该被显示。如果真实桌子空间网格的深度值比虚拟的杯子小离眼睛更近那么杯子在桌子后面的部分就会被正确遮挡。6.2 在 URP 中配置遮挡材质仅仅提交深度还不够我们需要确保空间网格本身在渲染时也写入深度但不一定写入颜色因为我们不想看到一个有颜色的网格挡住所有东西。创建专用的遮挡材质在 Project 窗口右键Create - Material命名为SpatialMeshOcclusion。将它的 Shader 改为PICO XR/URP/Spatial Mesh Occlusion这个 Shader 通常由 PICO SDK 提供。如果找不到可以使用 URP 自带的UnlitShader然后进行以下关键设置Surface Type设置为Transparent。Blending设置为AlphaSrcBlendZero,DstBlendOne。这个混合模式意味着不输出任何颜色Zero只保留源像素的 Alpha 和深度。但更关键的是下一步。最重要的是在Depth Write上打勾但将Depth Test设置为Less Equal。同时关闭Color Write Mask即 RGB 通道全不勾选。这样这个材质渲染的网格只会向深度缓冲区写入深度值而不影响最终屏幕颜色。应用遮挡材质修改我们的PicoSpatialMeshDemo脚本提供两个材质选项一个用于可视化半透明一个用于纯遮挡。public Material meshVisualizationMaterial; // 半透明可视化材质 public Material meshOcclusionMaterial; // 纯遮挡材质 private bool useOcclusionMode false; // 切换开关 void ProcessAndVisualizeMesh(SpaceSceneMesh sceneMesh) { // ... Material materialToUse useOcclusionMode ? meshOcclusionMaterial : meshVisualizationMaterial; meshRenderer.material materialToUse; // ... }测试遮挡效果运行程序扫描房间。切换到遮挡模式将useOcclusionMode设为 true。此时空间网格应该“消失”了因为它不输出颜色。然后将一个红色的 Cube 放在虚拟的“墙面”后面。当你移动视角让 Cube 位于真实墙面被扫描的网格区域后方时Cube 被遮挡的部分应该不可见。如果 Cube 始终完整显示说明深度测试或深度提交未正确生效需要检查 Player Settings 中的Enable Depth Submission和材质的深度设置。注意事项遮挡渲染对性能有额外消耗并且要求空间网格的深度信息足够准确。如果网格扫描质量差有空洞或抖动遮挡会出现闪烁或错误。在移动端设备上需要权衡视觉精度和性能。通常用于遮挡的网格可以使用比可视化网格更低的精度更大的TriangleSize。7. 常见问题排查与性能优化实录在实际开发中你一定会遇到各种问题。下面是我总结的“血泪”清单。7.1 网格扫描失败或数据为空现象调用StartSceneCapture后回调失败或者GetSceneMesh返回的Blocks列表为空。排查步骤检查权限在 PICO 设备上首次使用需要授予应用“空间数据访问”权限。确保你的应用已获得授权。可以在代码中监听权限回调。检查光照空间扫描依赖设备的 SLAM同步定位与地图构建功能在光线过暗或纹理特征极少如纯白墙壁的环境下SLAM 可能失效导致扫描失败。确保在光线充足、纹理丰富的环境下进行扫描。检查设备朝向扫描初期需要缓慢移动设备让摄像头捕捉到不同角度的环境特征。静止不动或移动过快都会导致扫描失败。查看日志连接设备到电脑在 Unity Editor 的Console窗口或使用adb logcat查看 PICO SDK 输出的详细错误信息。7.2 网格显示位置错乱或抖动现象生成的网格飘在空中或者随着头显移动而轻微抖动。原因与解决坐标系未转换PICO 返回的网格数据可能基于其自身的坐标系如右手系、Y轴向上而 Unity 是左手系、Y轴向上。虽然 SDK 通常做了处理但如果发现严重错位可能需要手动转换顶点坐标例如对 Z 轴取反。世界锚定问题确保你的PXR_Manager或场景原点在世界中稳定。在 MR 应用中虚拟世界的原点最好与设备的初始位置或某个空间锚点对齐。可以研究 PICO SDK 中的Space服务使用SpaceBinding来将虚拟物体持久化到特定空间位置这也有助于稳定全局坐标系。7.3 应用性能严重下降卡顿现象扫描完成后应用帧率FPS骤降。性能瓶颈分析Draw Call 激增每个网格块GameObject都会产生至少一个 Draw Call。如果扫描出上百个网格块Draw Call 数会爆炸。解决方案使用Mesh.CombineMeshes方法将相邻或材质相同的多个小网格合并成一个大网格能大幅减少 Draw Call。ListMeshFilter meshFilters new ListMeshFilter(); // ... 收集所有需要合并的 MeshFilter ... CombineInstance[] combine new CombineInstance[meshFilters.Count]; for (int i 0; i meshFilters.Count; i) { combine[i].mesh meshFilters[i].sharedMesh; combine[i].transform meshFilters[i].transform.localToWorldMatrix; meshFilters[i].gameObject.SetActive(false); // 合并后禁用原物体 } Mesh combinedMesh new Mesh(); combinedMesh.CombineMeshes(combine); // 创建一个新的GameObject来使用这个合并后的大Mesh物理计算开销如前所述复杂的MeshCollider是性能杀手。务必使用 5.2 节提到的优化方案。网格数据量过大TriangleSize设置过小会导致顶点和三角形数量巨大不仅占用内存也增加 GPU 渲染负担。永远根据实际需要选择最低可接受的精度。动态网格更新如果使用动态网格模式每帧都可能需要处理网格更新和重建CPU 开销极大。除非必要否则使用静态网格。7.4 打包到设备后功能异常现象在 Unity Editor 里运行正常打包成 APK 安装到 PICO 后扫描不工作或渲染异常。排查清单检查 SDK 版本兼容性确认你使用的 PICO SDK 版本与 Unity 版本、PICO 设备系统版本兼容。有时需要更新到最新的 SDK。检查 Player Settings 中的 XR Plug-in Management确保PICO XR Plugin已被正确添加且勾选。打包时Unity 有时会丢失这些设置。检查清单文件AndroidManifest.xmlPICO SDK 可能会自动添加必要的权限如android.permission.SPATIAL_MAPPING。如果手动修改过清单文件可能破坏了这些配置。对比 SDK 导入前后的清单文件。检查图形 API在 Player Settings - Other Settings 中确保Graphics APIs列表里Vulkan在 OpenGL ES3 之上或者只使用 Vulkan。PICO 设备对 Vulkan 的支持通常更好。但注意某些 Unity 版本或 Shader 与 Vulkan 可能存在兼容性问题如果遇到渲染问题可以尝试切换回 OpenGL ES3。开发 MR 应用是一个不断在效果和性能之间寻找平衡的过程。从最简单的可视化开始逐步增加物理、遮挡等特性并持续进行性能剖析使用 Unity Profiler 和 PICO 自带的 Metrics HUD 工具才能打造出既沉浸又流畅的体验。希望这份实战指南能为你铺平道路祝你开发顺利。
双梁正问题 【 torch 实战】（Python代码实现）)
