在 Unity 中开始使用 Geospatial Creator

借助适用于 Unity 的 ARCore Geospatial Creator，您可以通过以新的 3D 图块格式显示 Google 地图数据在 Unity 编辑器中预览 Geospatial 内容。这有助于您在构建应用时直观地了解内容在现实世界中的放置位置。

Geospatial Creator 作为 ARCore Extensions for AR 基础扩展的一部分提供。本快速入门将向您介绍如何使用 Unity 中的 Geospatial Creator 将地理空间 AR 内容添加到 ARCore Geospatial 示例应用。

如果您想要使用现有应用而不是 Geospatial 示例，则需要先遵循我们的 Unity Geospatial 开发者指南。将您的应用配置为使用 Geospatial API 后，请跳至下面的添加必需的依赖项步骤，然后继续操作。

前提条件

请按照“ARCore Extensions for AR 基础入门”中的说明配置 Unity 环境，以打造 AR 体验。

虽然 ARCore Extensions 支持较低版本的 Unity，但 Geospatial Creator 要求使用 Unity 2021.3 或更高版本。

API 授权

您需要设置 API 访问权限才能使用 ARCore Geospatial API 和 Google Map Tiles API。

Google 地图图块 API

Map Tiles API 可提供受支持位置的 3D、仿真表示形式。我们将在 Unity 编辑器中使用这些图块来预览 AR 场景周围的区域。

请参阅 Map Tiles API 页面以启用该 API 并详细了解地图图块。

ARCore Geospatial API

您的应用在运行时使用 ARCore Geospatial API 来创建地理空间锚点并与之互动。

如需启用 Geospatial API，请在您的应用中设置 ARCore API。您可以使用无密钥（推荐）或 API 密钥授权方法。

扩展 Geospatial 示例应用

在本指南中，我们将介绍如何使用 Geospatial Creator 将地理空间内容添加到 ARCore Geospatial 示例应用。

配置地理空间样本

首先，熟悉 ARCore Geospatial 示例应用。在新的 Unity 项目中，打开 Unity Package Manager 并选择 ARCore Extensions 软件包。在“软件包管理器详情”面板中，展开示例，然后将 Geospatial 示例导入您的 Unity 项目中。

在运行应用之前，您必须在项目中启用 ARCore 和地理空间功能。使用 Edit > Project Settings... > XR 插件管理。选中相应的复选框，以启用 ARCore 插件提供程序（Android 版）和/或 ARKit 插件提供程序（iOS 版）。

然后，从 Edit > Project Settings... > XR plug-in Management 中，打开 ARCore Extensions 面板。确保已选中“Geospatial”（您目前不需要启用 Geospatial Creator），然后输入您的 API 凭据。如需了解详情，请参阅适用于 Android 和 iOS 的“启用 Geospatial Unity API”文档。

使用 ARCore 的任何 Unity 应用还需要一些其他特定于平台的 Player 设置。如需了解所需的更改，请参阅文档的配置播放器设置部分。

此时，除了运行地理空间样本所需的对象之外，您的场景中没有任何游戏对象。现在是构建和运行应用的好时机。如果配置正确，应用将在运行时显示设备的相机视图。随着移动，屏幕顶部显示的地理空间准确度将开始提高。通过点按屏幕，您将创建地理空间锚点，当您四处移动时，这些锚点将会保留在其原始位置。

接下来，我们将介绍如何使用 Geospatial Creator 在 Unity Editor 中创建和可视化复杂的 AR 内容。此内容将出现在应用中世界上特定的纬度 / 经度位置。

添加所需的依赖项

Geospatial Creator 使用名为 Cesium 的第三方 Unity 软件包，在 Unity Editor 的“Scene”窗口中渲染 Google 地图图块。在启用 Geospatial Creator 功能之前，我们将 Cesium 软件包添加到您的项目中。

我们建议从 Cesium 的 GitHub 页面安装最新版本的 Cesium for Unity 软件包：

1. 从 GitHub 版本页面下载最新版本的 Cesium for Unity .tgz 预编译版本。目前推荐的适用于 Unity 的 Cesium 软件包版本是 1.1.0。
2. 点击 Unity 的“Window”菜单，然后选择“Package Manager”，打开 Unity Package Manager。
3. 点击“+”图标，然后选择“Add package from tarball”。
4. 选择在第 1 步中下载的 Cesium for Unity .tgz 文件。
5. 系统可能会提示您安装其他依赖项，例如 Text Mesh Pro。

启用 Geospatial Creator

现在，您可以启用 Geospatial Creator：

1. 在“Build Settings”（构建设置）对话框中，确保您选择的平台是“Android”或“iOS”。Geospatial Creator 功能目前不适用于其他平台。
2. 依次转到 Project Settings > XR plug-in Management > ARCore Extensions。
3. 如果您在之前的步骤中未设置 ARCore Android 和/或 iOS API 密钥，请务必立即设置。
4. 同时启用“Geospatial”和“Geospatial Creator”切换开关。点击以启用 Geospatial Creator 切换开关后，将显示一个非模态向导，以确认您的项目与 Geospatial Creator 兼容。
5. 在向导中点击“完成”。

向导完成后，Unity 将触发脚本的编译。请等待重新编译完成，然后再继续。（如果您选择的平台不是“Android”或“iOS”，请立即切换到其中一个平台。）

使用地图图块添加 Geospatial Creator Origin

您的场景只需要一个“Geospatial Creator Origin”对象。此对象可用作将真实纬度、经度和海拔值转换为 Unity 游戏坐标的参考点。

如需向场景添加 Geospatial Creator Origin，请依次选择 Game Object > XR > Geospatial Creator Origin。新创建的对象需要一个地理参考，将特定的纬度、经度和海拔与起点在游戏坐标中的位置相关联。在 Geospatial Creator Origin 的 Inspector 窗格中，点击 Add Cesium Georeference Component 按钮以添加地理参考。

除了作为 AR 对象的参考点外，Cesium 地理参考还会向场景中添加 Cesium 3D Tileset 对象。此对象将在编辑器的 Scene View 中渲染 Google 地图图块，让您能够准确直观地呈现您的 AR 内容在世界上的哪些位置显示。Geospatial Creator Origin 的检查器中有一个字段，用于添加您之前设置的 Map Tiles API 密钥。设置此键后，您应该会在“场景”视图中看到地图图块加载。

现在，将纬度、经度和高度字段更改为您希望在应用中显示 AR 内容的位置附近。

编辑器中的“Scene”视图现在应该会按原点的指定纬度和经度显示地图图块。在运行时，我们假设您的应用将使用 AR 相机，因此 Geospatial Creator 已经使用“EditorOnly”标记配置了 Cesium 3D 地图图块集对象。因此，系统不会在运行时下载或渲染功能块。您可以通过 Cesium3DTileset 对象的检查器对此进行更改。如需详细了解 Cesium 的 Georeference 和 3D Tileset GameObject，请参阅 Cesium for Unity 文档。

添加并放置 Geospatial Creator Anchor

现在，您就可以在场景中添加 AR 内容了！依次点击 GameObject > XR > Geospatial Creator Anchor，将锚点添加到场景层次结构中。通过 Anchor 的检查器，您可以指定确切的纬度、经度和高度。对象的转换会立即更新到场景中的正确位置，您可以看到对象将在现实世界中出现的确切位置。

在微调锚点的纬度和经度时，请选择附近的地点，以便在运行时验证锚点是否位于正确的位置。在设置 Geospatial Creator Anchor 的海拔高度时，有三种选项可供选择：

• Terrain 将锚点放置在地平面上指定的纬度和经度处。地平面由视觉定位系统在运行时确定。如果您刚开始接触 ARCore 的 Geospatial API，“Terrain”是一个不错的选择，因为锚点将直接在地面上解析，并且垂直准确性很高。通过“Altitude Offset”（海拔高度偏移）字段，您可以按固定距离（以米为单位）将锚点放置在地平面之上或之下。例如，指定偏移值“1.0”会导致锚点“悬浮”在地形上方一米处。
• Rooftop 相对于任何结构顶部给定纬度和经度来放置锚点。与地形锚点一样，“海拔高度偏移”字段可让您相对于屋顶位置向上或向下移动锚点（以米为单位）。
• WGS84 会根据 WGS84 坐标系将锚点放置在特定的绝对高度（以米为单位）。以这种方式放置对象可能需要进行一些试验和试错，因为 WSG84 中的高度为“0”并不一定表示平均海平面，并且可能与 GPS 的海拔高度不匹配。此外，虽然渲染的 3D 图块的纬度和经度非常准确，但尝试使用 3D 图块作为参考来将对象放置在地面上可能会导致高达几米的高度误差。

如需详细了解不同类型的 ARCore 地理空间锚点，请参阅地理空间开发者指南。

地形和屋顶锚点都有 WGS84 Altitude 字段。此值仅在编辑器模式下使用，用于在场景视图中设置对象的高度。地形和屋顶高度仅在运行时确定，因此您可以在开发应用时通过 WGS84 Altitude 字段直观呈现锚点的特定高度。在运行时，对于地形和屋顶锚点，WGS84 Altitude 字段会被忽略。

向锚点添加几何图形

如果您现在构建并运行应用，就不会在支持 AR 的应用中看到锚点。这是因为它未附加任何几何图形。我们来为锚点添加一个简单的 3D 基元：在场景层次结构中，右键点击 AR Geospatial Creator Anchor 对象。从上下文菜单中选择 3D 对象 > 立方。作为锚点的子级，您应该会在场景视图中看到一个灰色立方体。如果您决定在编辑器中移动对象的位置或旋转角度，建议您移动根 Anchor 对象，而不是子级 Cube 基元。这有助于减少从纬度 / 经度转换到游戏坐标时出现的错误。

当然，您可以向锚点添加更复杂的几何图形以及任意组件和子级。

构建并运行应用

是时候在现实世界中看到您的锚点了！尝试构建并运行您的应用，然后移到您希望看到立方体的位置。有没有？ 恭喜！您可以使用 Geospatial Creator 构建更复杂的 AR 体验！

如果您有任何问题，请参阅问题排查指南。

现在是添加具有不同几何图形的其他 AR Geospatial Creator Anchor 的好时机。尝试使用多个屋顶和地形锚点及其偏移量进行实验。添加脚本，为对象添加动画或启用与对象的互动。

了解 Geospatial Creator Anchors 和 ARGeospatialAnchor 类

在构建复杂的交互式 AR 体验时，了解 Geospatial Creator Anchors 与 ARCore 的 ARGeospatialAnchor C# 类之间的关系会很有帮助：

ARGeospatialAnchor 只能在运行时通过调用 ARAnchorManager 上的某个函数来创建，并且只能在 AR 会话稳定后才能创建。地理空间创作者锚点可以视为场景中存在的占位符，用于等待 AR 会话准备好解析 ARGeospatialAnchor 对象。会话准备就绪后，占位符将自动调用 ARAnchorManager 以创建并解析 ARGeospatialAnchor。

解析运行时锚点后，场景层次结构中的 Geospatial Creator Anchor 会立即将自身作为子项附加到新的 GameObject。这意味着，Geospatial Creator Anchor 的任何组件或子级都将成为新的 ARGeospatialAnchor GameObject 的子组件或孙级。例如，附加到 Geospatial Creator Anchor 的几何图形基元的 transform 将继承自 ARGeospatialAnchor 的 transform，因此将被放置在运行时 AR 会话中的预期位置。

如果您需要在运行时识别特定的 ARGeospatialAnchor GameObject，则可以在场景中搜索其 name 属性与使用 Geospatial Creator 创建的锚点匹配的对象。如果初始化 AR 会话，则该对象的 parent 将是相应的 ARGeospatialAnchor 对象。

问题排查

为什么我的锚点会移动？

您可能会注意到，尤其是在应用首次启动时，锚点可能会看起来缓慢“偏移”，甚至突然跳动好几米。当 VPS 会话仍在确定和优化摄像头的精确位置时，就会发生这种情况。随着多个帧的水平和垂直准确性提高，锚点会在更准确的位置重新绘制，从而产生移动的假象。在位置信息精确度达到特定阈值之前，您可能想以不同方式（或者完全不渲染）该对象。为此，您可以查询 ARCoreEarthManager.CameraGeospatialPose 属性来确定当前帧更新的准确率。

为什么我的锚点显示在错误的海拔高度？

对 Geospatial Creator Anchors 使用“手动”海拔高度类型时，将根据 WGS84 设置锚点的海拔（以米为单位）。在给定位置，地图图块中显示的表观地平面与 Google 视觉定位系统 (VPS) 报告的实际地平面之间可能存在几米的差异。如果地理空间锚点在运行时似乎位置不正确，我们建议您使用示例应用中的调试叠加层亲自验证 VPS 高度。然后，您可以在 Unity 编辑器中更改海拔高度，以匹配该位置的已知 VPS 高度。

地图图块无法在编辑器的“Scene”视图中正确渲染

如果 Cesium3DTileset 似乎正在加载图块，但它们在场景视图中以纯品红色渲染，请将 Unity 的 Shader Graph 软件包添加到您的项目中。Cesium 需要此软件包，但默认情况下，使用 Unity 内置渲染程序的项目不包含此软件包。

如需添加 Shader Graph，请打开 Unity Package Manager (Window > Package Manager)。确保您正在浏览 Unity Package Registry 提供的软件包，方法是从 Package Manager 窗口顶部的下拉菜单中选择“Packages: Unity Registry”。搜索 com.unity.shadergraph 软件包并安装最新版本。软件包加载后，3D 图块应重新加载并在场景视图中正确渲染。

应用在运行时显示黑屏，而不是相机视图

默认情况下，系统不会为 AR 相机配置 Unity 的通用渲染管道 (URP)。如果您在运行时看到黑屏而不是相机输出，则需要向场景中的每个 URP 渲染程序添加 AR Background Renderer Feature。

如需添加该功能，请在项目中搜索“renderer”。对于每个 URP Renderer 对象，请点击检查器中的“Add Renderer Feature”按钮，然后添加 AR 后台渲染程序。

为什么看上去远离原点放置的锚点放置得不正确？

由于浮点数算术精确度，从 WGS84 坐标到 Unity 游戏坐标的转换可能会出错，您可以通过确保您的原点位于 AR 锚点附近来最大限度地降低这一结果。距离超过 20 公里可能会导致不准确。如果您的 AR 体验要跨越长距离，我们建议您使用多个场景，并为每个场景中使用一个唯一的锚点。