Unity ARFoundation入门：从零实现平面检测与物体放置的AR应用-拓冰建站

1. 项目概述与核心价值

最近几年，AR（增强现实）技术已经从科幻概念走进了我们的手机，从各种滤镜特效到宜家的家具摆放应用，它正在改变我们与数字世界交互的方式。对于很多开发者来说，AR听起来很酷，但总觉得门槛很高，涉及复杂的计算机视觉、3D图形学和传感器融合，让人望而却步。其实，借助像Unity的ARFoundation这样的成熟框架，入门AR开发并没有想象中那么困难。今天，我就以一个老开发者的身份，带你亲手搭建一个最基础的AR应用：打开摄像头，识别现实世界中的平面（比如桌面、地板），然后通过点击屏幕，把一个虚拟的立方体“放置”到识别出的平面上。这个“Hello World”级别的项目，麻雀虽小五脏俱全，涵盖了AR应用最核心的流程。完成它，你不仅能获得巨大的成就感，更能透彻理解ARFoundation的工作流，为后续开发更复杂的AR体验打下坚实的自信基础。

这个项目适合所有对AR感兴趣的Unity开发者，无论你是游戏程序员想拓展技能边界，还是应用开发者希望为产品增加炫酷的AR功能，甚至是学生想做一个有趣的毕业设计，都可以从这里开始。我们不需要从头研究SLAM（同步定位与地图构建）算法，ARFoundation已经为我们封装好了这些底层能力，我们要做的就是理解其框架，并学会如何“使用”它。整个过程就像搭积木，关键在于理解每一块“积木”的作用和它们之间的连接方式。

2. 环境准备与项目初始化

2.1 Unity版本与ARFoundation包导入

工欲善其事，必先利其器。ARFoundation是Unity官方推出的跨平台AR开发框架，它抽象了ARKit（iOS）和ARCore（Android）的底层接口，让我们可以用一套代码开发兼容两大主流移动平台的AR应用。因此，第一步是确保你的Unity版本与之兼容。

我强烈推荐使用Unity 2021 LTS或2022 LTS版本。长期支持版意味着更高的稳定性，对于生产环境至关重要。你可以在Unity Hub中轻松安装这些版本。创建项目时，选择“3D（URP）”模板。为什么是URP（通用渲染管线）而不是内置管线？因为URP在移动设备上性能更优，且ARFoundation对URP的支持已经非常成熟，这是目前移动端开发的主流选择。

项目创建好后，我们需要打开Package Manager（窗口 -> 包管理器）。确保在“Packages:”下拉菜单中选择“Unity Registry”。然后，搜索并安装以下核心包：

AR Foundation: 这是框架的核心。
ARCore XR Plugin(针对Android设备): 如果你主要面向安卓手机。
ARKit XR Plugin(针对iOS设备): 如果你主要面向iPhone/iPad。
ARCore/ARKit Face Tracking等可选包，本项目暂不需要。

安装时要注意版本兼容性。一个稳妥的做法是，在Package Manager中点击“AR Foundation”，在右侧详情页查看其“Dependencies”（依赖）和“Samples”（示例），它会列出推荐配套的其他包版本。通常直接安装最新稳定版即可。安装完成后，Unity可能会提示你重启编辑器，照做就行。

注意：如果你的目标是发布到iOS平台，还需要在Unity中设置正确的Bundle Identifier，并在苹果开发者账号中配置相应的权限。安卓平台则需要确保AndroidManifest.xml中包含了相机等必要权限。这些属于平台发布的通用流程，ARFoundation的官方文档有详细说明。

2.2 场景基础设置：AR Session与AR Session Origin

理解ARFoundation的两个核心组件是入门的关键。你可以把它们想象成AR体验的“导演”和“舞台经理”。

回到Unity场景，首先删除默认的Main Camera。在AR中，相机是由设备的后置摄像头实时画面驱动的，我们不需要传统的虚拟相机。

然后，在Hierarchy面板右键，选择XR -> AR Session。这个AR Session组件就是我们的“导演”。它负责管理整个AR生命周期：启动摄像头、与底层ARKit/ARCore服务通信、处理跟踪状态（比如设备是否在移动、跟踪是否丢失）。一个场景中通常只需要一个AR Session。

接着，再次右键，选择XR -> AR Session Origin。这个AR Session Origin是“舞台经理”和“坐标原点”。它的作用是：

管理虚拟内容：所有你希望出现在AR世界中的3D物体（GameObject），都应该作为AR Session Origin的子物体。
处理空间映射：它将设备检测到的真实世界坐标（以米为单位）转换到Unity的虚拟世界坐标中。AR Session Origin自身的位置和旋转代表了设备在AR会话开始时的初始位置和朝向。

选中AR Session Origin，你会发现它下面自动带了一个AR Camera。这个AR Camera组件会接管渲染，将摄像头画面作为背景，并将虚拟物体正确地合成上去。至此，AR框架的骨架就搭建好了。你可以点击运行，如果一切正常，在Unity编辑器的Game视图中，你应该能看到一个模拟的设备摄像头画面（可能是测试图案），这表示AR子系统已经初步就绪。

3. 核心功能实现：平面检测与可视化

3.1 理解平面检测与`ARPlaneManager`

AR应用要让人感觉虚拟物体“放在”真实世界上，第一步就是让设备理解真实世界的几何结构。平面检测（Plane Detection）就是这个过程的基石。设备通过摄像头和惯性传感器，识别出像桌面、地板、墙面这样大面积的、平坦的表面。

在ARFoundation中，ARPlaneManager组件负责管理平面检测功能。我们为AR Session Origin游戏对象添加这个组件。在Inspector面板中，找到AR Session Origin，点击“Add Component”，搜索并添加AR Plane Manager。

添加后，我们需要配置两个关键部分：

Plane Prefab: 这是用于可视化检测到的平面的预制体。当系统识别出一个平面时，它会实例化这个Prefab来代表该平面。通常，我们会创建一个简单的、半透明的Quad（平面）作为Prefab，并附上ARPlane组件。
Plane Detection Mode: 检测模式。通常我们选择Horizontal（水平面，如地板、桌子）或Vertical（垂直面，如墙壁）。对于我们的“放置物体到地面”场景，选择Horizontal即可。你也可以选择Both来同时检测水平和垂直面。

3.2 创建并配置平面可视化Prefab

现在我们来制作那个用于可视化的Prefab。在Project面板中右键，创建 -> 3D Object -> Quad。将其重命名为“PlaneVisualizer”。调整其Scale，比如设为(0.1, 0.1, 0.1)，因为真实世界的平面可能很大，默认的Quad(1x1)太小。然后，我们创建一个材质球赋给它。

为了让平面看起来直观又不遮挡视线，我习惯创建一个半透明、带网格线的材质。创建一个新的材质（比如叫PlaneMat），Shader选择“Universal Render Pipeline/Lit”。将Surface Type改为“Transparent”，Base Map颜色调成一个淡淡的蓝色或绿色，并设置较低的Alpha值（如0.3）。你还可以在Detail Map（细节贴图）上使用一个网格纹理，让平面看起来像网格。

接着，为这个PlaneVisualizer游戏对象添加ARPlane组件。这个组件是ARFoundation用来与检测到的平面数据绑定的。最后，将这个PlaneVisualizer从Hierarchy拖到Project面板，生成一个Prefab，然后就可以把Hierarchy中的原始对象删除了。

回到AR Plane Manager组件，将我们刚创建的PlaneVisualizerPrefab拖拽到Plane Prefab字段中。至此，平面检测的配置就完成了。运行项目，用鼠标在Game视图（模拟摄像头画面）上移动，你应该能看到当“模拟设备”检测到“平面”时，会出现我们设计的半透明网格平面。在真机上，你需要缓慢移动手机，让摄像头扫描房间的地面或桌面，就能看到平面被实时识别并可视化出来。

4. 交互实现：点击屏幕放置立方体

4.1 射线检测与AR交互的坐标系转换

AR中的交互，核心是将二维的屏幕触摸点，映射到三维的AR世界坐标中。这个过程通过射线检测（Raycast）来完成。但AR的射线检测有其特殊性：它不仅要检测虚拟物体，更要能检测到由AR系统跟踪的真实世界特征，比如我们刚刚检测到的平面。

ARFoundation提供了ARRaycastManager组件来专门处理这件事。它为我们在AR环境中进行射线检测提供了高性能的接口。我们为AR Session Origin添加这个组件。

接下来，我们需要一个脚本来处理用户的点击输入。创建一个C#脚本，命名为PlaceObjectOnPlane。这个脚本的核心逻辑是：

监听用户的触摸输入。
当用户点击屏幕时，从点击的屏幕位置发出一条射线。
使用ARRaycastManager进行射线检测，判断这条射线是否击中了AR系统跟踪的平面。
如果击中，获取击中点的世界坐标和旋转（通常旋转与平面对齐）。
在这个位置实例化我们的虚拟物体（立方体）。

4.2 编写物体放置脚本

下面是PlaceObjectOnPlane.cs脚本的一个基础实现框架，我加入了大量注释来解释每一步：

using System.Collections.Generic; using UnityEngine; using UnityEngine.XR.ARFoundation; using UnityEngine.XR.ARSubsystems; public class PlaceObjectOnPlane : MonoBehaviour { // 将要放置的物体Prefab public GameObject placedPrefab; // 用于管理AR射线检测 private ARRaycastManager arRaycastManager; // 存储当前在场景中放置的物体实例（用于管理，比如限制同时只存在一个） private GameObject spawnedObject; void Start() { // 获取同一游戏对象上的ARRaycastManager组件 arRaycastManager = GetComponent<ARRaycastManager>(); if (arRaycastManager == null) { Debug.LogError("ARRaycastManager not found on this GameObject."); } } void Update() { // 确保只在没有UI被点击时处理（避免与UI按钮冲突） if (Input.touchCount > 0 && Input.GetTouch(0).phase == TouchPhase.Began) { // 获取第一个触摸点的位置 Vector2 touchPosition = Input.GetTouch(0).position; // 进行AR射线检测 List<ARRaycastHit> hits = new List<ARRaycastHit>(); if (arRaycastManager.Raycast(touchPosition, hits, TrackableType.PlaneWithinPolygon)) { // Raycast成功，hits列表包含了所有击中的平面信息 // 通常我们取第一个击中点 Pose hitPose = hits[0].pose; // 如果之前没有放置过物体，则实例化一个新的 if (spawnedObject == null) { spawnedObject = Instantiate(placedPrefab, hitPose.position, hitPose.rotation); } else { // 如果已经存在物体，则移动它到新的位置（可选逻辑，这里选择移动） spawnedObject.transform.position = hitPose.position; spawnedObject.transform.rotation = hitPose.rotation; } } } } }

将这个脚本挂载到AR Session Origin游戏对象上。然后在Inspector面板中，将你准备好的一个立方体Prefab（或者任何你想放置的3D模型Prefab）拖拽到脚本的Placed Prefab字段。

4.3 创建可放置的物体Prefab

在Project中创建一个Cube，为其添加一个好看的材质，然后将其拖成Prefab。这个Prefab就是我们将要放置在AR世界中的物体。你可以发挥创意，把它换成任何模型，比如一个花瓶、一个卡通角色，或者一个信息标签。

5. 功能优化与视觉反馈

5.1 添加放置指示器

直接点击放置可能让用户感到不确定，不知道物体会出现在哪里。一个良好的用户体验是提供一个视觉指示器（比如一个半透明的物体轮廓或一个光标），它跟随射线与平面的交点移动，当用户点击时，指示器位置就是最终物体的放置位置。

我们可以创建一个简单的指示器Prefab，比如一个半透明的绿色圆圈或一个方框。然后修改PlaceObjectOnPlane脚本：

增加一个GameObject placementIndicator变量。
在Update函数中，持续进行射线检测。如果检测到平面，就显示指示器，并将其位置和旋转设置为击中点的Pose。
只有当指示器显示（即射线检测到平面）时，才响应触摸点击事件进行放置。
放置物体后，可以隐藏指示器，或者让其继续为下一次放置做准备。

这大大提升了交互的直观性和精准度。

5.2 平面检测的优化与过滤

在实际使用中，设备可能会同时检测到多个平面，或者一个很大的平面被分割成多个小平面。我们的射线检测TrackableType.PlaneWithinPolygon会检测到所有平面。有时我们需要更精细的控制，比如只允许放置在水平面（地板、桌子）上，而不是墙面。

ARRaycastHit对象包含了被击中平面的详细信息，我们可以通过hit.trackable获取到对应的ARPlane组件，进而判断其alignment（对齐方式）是Horizontal还是Vertical。在点击放置前加入这个判断，可以过滤掉垂直的墙面。

此外，对于已经放置了物体的平面，你可能希望禁止重复放置，或者对平面的大小进行筛选（只允许在大于一定面积的平面上放置）。这些逻辑都可以通过访问ARPlane组件的属性（如size）来实现，让应用的行为更符合设计预期。

6. 真机测试与性能调优

6.1 安卓与iOS平台构建设置

在编辑器里运行顺畅，不代表在真机上没问题。构建到移动设备是必须的一步。

对于Android：

进入File -> Build Settings，选择Android平台，点击“Switch Platform”。
点击“Player Settings”，在Player设置中：
- Other Settings->Identification：
  - Package Name：填写一个唯一的反向域名标识符（如com.YourCompany.YourAppName）。
- Other Settings->Configuration：
  - Scripting Backend：选择IL2CPP。
  - Target Architectures：勾选ARM64（现代安卓设备必须）。
- XR Plug-in Management：确保ARCore已启用。
连接安卓手机，开启USB调试模式。在Build Settings中点击“Build And Run”。

对于iOS：

切换平台到iOS。
Player Settings中：
- Other Settings->Identification：
  - Bundle Identifier：格式同安卓包名。
  - Target minimum iOS Version：设置为支持ARKit的版本（如14.0或更高）。
- Other Settings->Configuration：
  - Scripting Backend：选择IL2CPP。
  - Target Architectures：勾选ARM64。
- XR Plug-in Management：确保ARKit已启用。
你需要一台Mac电脑和Xcode来完成最终的编译和签名。

6.2 常见问题与性能排查

真机测试时，你可能会遇到以下典型问题：

黑屏或闪退：
- 权限问题：确保应用清单（Android）或Info.plist（iOS）中正确声明了相机权限。Unity ARFoundation通常会自动处理，但最好确认。
- 设备不支持： ARCore/ARKit需要特定的硬件和系统版本支持。在代码启动AR Session前，可以进行功能支持性检查（ARSession.CheckAvailability()）。
- 图形API：在Player Settings的Graphics设置中，确保第一个使用的图形API是OpenGLES3（安卓）或Metal（iOS）。Vulkan或MoltenVK可能存在问题。
平面检测不稳定或缓慢：
- 光照条件： AR在光线充足、纹理丰富的环境下表现最好。在纯白墙面或昏暗环境下，特征点提取困难，会导致检测失败。
- 移动速度：缓慢平稳地移动设备，让摄像头有足够的时间采集和分析图像。
- 性能开销：过于复杂的平面可视化Prefab（高面数、复杂Shader）会消耗性能。我们的半透明网格Quad是非常轻量的选择。
虚拟物体抖动或漂移：
- 这是AR跟踪中的正常现象，尤其是在设备移动或光照变化时。ARFoundation会不断优化其空间映射。可以通过一些技巧缓解，比如将虚拟物体的锚点（Pivot）设置在底部中心，使其看起来像是“站”在平面上，而不是“浮”在平面中心。
- 对于静态放置的物体，可以考虑使用ARAnchor。ARAnchor是ARFoundation中一种特殊的对象，它尝试在物理世界中标记一个点，即使设备重新定位，也会尽力保持该点与真实世界的相对位置稳定。你可以将放置的物体与一个ARAnchor关联，而不是直接放在平面击中点上。
发热与耗电：
- 同时使用摄像头、惯性传感器和进行实时计算机视觉计算是非常耗电的。在应用设计上，可以考虑在不需AR时暂停Session（ARSession.enabled = false），或者提供省电模式，降低平面检测的频率和范围。

7. 项目扩展思路与进阶方向

完成基础功能后，你可以从这个项目出发，探索AR更广阔的世界：

2D图像识别与跟踪：使用AR Tracked Image Manager。让应用识别特定的图片（如海报、产品手册），然后在图片上方叠加播放视频、展示3D模型或弹出交互界面。这是很多营销和教育类AR应用的核心。
3D物体识别：使用AR Tracked Object Manager。这需要预先扫描一个真实物体（比如一个玩具、一个机器零件）生成3D模型数据库。应用可以在摄像头中实时识别出这个真实物体，并与之进行交互。难度和计算开销更高，但效果非常震撼。
人脸AR：使用AR Face Manager。可以实时检测人脸，并在人脸上添加面具、妆容、特效等。这是各种社交滤镜的基础。
环境探针与光照估计：使用AR Environment Probe和光照估计API。让虚拟物体的光影与真实环境的光照条件相匹配，比如根据环境光的颜色和强度来调整虚拟物体的材质，使其看起来更加逼真，仿佛真的是场景的一部分。
点云与特征点可视化：启用AR Point Cloud Manager，可以看到设备摄像头提取的稀疏特征点云。这能帮助你直观理解AR系统是如何“看到”和理解世界的，对于调试非常有帮助。
多平面管理与交互：实现更复杂的放置逻辑，比如物体只能放在特定类型的平面上，或者物体放置后可以与平面进行物理交互（受重力影响、可以被推动等），这需要结合Unity的物理引擎。

这个“检测平面+点击放置立方体”的项目，就像学会骑自行车时保持平衡的那一瞬间。它看似简单，却让你掌握了ARFoundation最核心的“输入（摄像头/传感器）-> 感知（平面检测）-> 交互（射线点击）-> 输出（渲染虚拟物体）”闭环。理解了这套流程，再去看那些复杂的AR功能，你会发现它们都是在这个闭环上的叠加和深化。动手实现一遍，遇到问题去查文档、看社区讨论，这个过程积累的经验和信心，远比读十篇教程更有价值。AR开发的大门，现在已经为你敞开了。