借助适用于 Unity 的 ARCore Geospatial Creator，您可以在 Unity 编辑器中以新的 3D 图块格式显示 Google 地图数据，从而预览地理空间内容。这有助于您在构建应用时直观了解内容在现实世界中的放置位置。
Geospatial Creator 作为 ARCore 扩展程序的一部分提供，适用于 AR Foundation。本快速入门将介绍如何在 Unity 中使用 Geospatial Creator 将地理空间 AR 内容添加到 ARCore 地理空间示例应用。
如果您有想要使用的现有应用，而不是地理空间示例，则需要先按照我们的 Unity 地理空间开发者指南操作。为应用配置 Geospatial API 使用权限后，请跳至下方的添加必需的依赖项步骤，并从该步骤继续操作。
前提条件
按照 “ARCore Extensions for AR Foundation 入门”配置 Unity 环境，以创建 AR 体验。
虽然 ARCore 扩展程序支持较低版本的 Unity，但 Geospatial Creator 需要使用 Unity 2021.3 或更高版本。
API 授权
您需要设置 API 访问权限，才能使用 ARCore Geospatial API 和 Google Map Tiles API。
Google Map Tiles API
Map Tiles API 可提供受支持位置的 3D 仿真表示形式。我们将在 Unity 编辑器中使用这些图块来预览 AR 场景周围的区域。
如需启用该 API 并详细了解地图图块，请参阅 Map Tiles API 页面。
ARCore Geospatial API
您的应用会在运行时使用 ARCore Geospatial API 来创建地理空间锚点并与之互动。
如需启用 Geospatial API，请在应用中设置 ARCore API。您可以使用无密钥（推荐）或 API 密钥授权方法。
扩展地理空间示例应用
在本指南中，我们将向您展示如何使用 Geospatial Creator 将地理空间内容添加到 ARCore 地理空间示例应用。
配置地理空间示例
首先，熟悉 ARCore Geospatial 示例应用。在新的 Unity 项目中，打开 Unity 资源包管理器，然后选择 ARCore 扩展程序包。在“Package Manager”详情面板中，展开 Samples 并将“Geospatial Sample”导入您的 Unity 项目。
在运行应用之前，您必须在项目中启用 ARCore 和 Geospatial 功能。使用 Edit > Project Settings... > XR Plug-in Management。选中相应的复选框，以启用 Android 的 ARCore 插件提供程序和/或 iOS 的 ARKit 插件提供程序。
然后，依次选择修改 > 项目设置... > XR Plug-in Management，打开 ARCore Extensions 面板。确保选中“Geospatial”（您暂时无需启用 Geospatial Creator），然后输入您的 API 凭据。如需了解详情，请参阅有关启用地理空间 Unity API 的文档（针对 Android 和 iOS）。
对于使用 ARCore 的任何 Unity 应用，还需要设置一些其他特定于平台的 Player 设置。如需了解必需的更改，请参阅我们文档中的配置播放器设置部分。
此时，您的场景中除了运行地理空间示例所需的必要游戏对象之外，没有任何其他游戏对象。现在可以构建并运行应用了。如果配置正确，应用在运行时会显示设备的相机视图。随着您的移动，屏幕顶部显示的地理空间准确性会开始提高。通过点按屏幕，您可以创建地理空间锚点，这些锚点会在您四处移动时保留在原始位置。
接下来，我们将展示如何使用 Geospatial Creator 在 Unity 编辑器中创建和直观呈现复杂的 AR 内容。此内容将显示在应用中位于世界特定纬度 / 经度位置。
添加必需的依赖项
Geospatial Creator 使用名为 Cesium 的第三方 Unity 软件包在 Unity 编辑器的“场景”窗口中渲染 Google 地图图块。在启用 Geospatial Creator 功能之前，我们先将 Cesium 软件包添加到您的项目中。
建议您从 Cesium 的 GitHub 页面安装最新版本的 Cesium for Unity 软件包：
- 从 Cesium for Unity 的 GitHub 版本页面下载预编译
.tgz的最新版本。目前建议使用的 Cesium for Unity 软件包版本为 1.1.0。 - 点击 Unity 的“Window”菜单，然后选择“Package Manager”，打开 Unity 软件包管理器。
- 点击“+”图标，然后选择“从 tarball 添加软件包”。
- 选择在第 1 步中下载的 Cesium for Unity .tgz 文件。
- 系统可能会提示您安装其他依赖项，例如 Text Mesh Pro。
启用 Geospatial Creator
您现在可以启用 Geospatial Creator 了：
- 在“Build Settings”（构建设置）对话框中，确保所选平台为“Android”或“iOS”。Geospatial Creator 功能目前不适用于其他平台。
- 依次前往项目设置 > XR 插件管理 > ARCore 扩展。
- 如果您在之前的步骤中未设置 ARCore Android 和/或 iOS API 密钥，请务必立即设置。
- 同时启用“Geospatial”和“Geospatial Creator”切换开关。点击以启用“地理空间创建器”切换开关后，系统会显示一个非模态向导，用于确认您的项目是否与地理空间创建器兼容。
- 点击向导中的“完成”。
完成向导后，Unity 将触发脚本的编译。 等待重新编译完成，然后再继续。（如果您选择的平台不是“Android”或“iOS”，请立即切换到其中一个平台。）
添加带有地图图块的 Geospatial Creator Origin
您的场景需要包含一个且仅一个“地理空间创作者原点”对象。此对象用作将真实世界的纬度、经度和海拔高度值转换为 Unity 游戏坐标的参考点。
如需向场景中添加地理空间创建器原点，请依次选择 Game Object > XR > Geospatial Creator Origin。新创建的对象需要地理参考，该参考会将特定纬度、经度和海拔高度与游戏坐标中的原点位置相关联。在地理空间创建器原点的 Inspector 窗格中，点击 Add Cesium Georeference Component 按钮添加地理参考。
除了作为 AR 对象的参考点之外，Cesium 地理参考还会向场景中添加一个 Cesium 3D Tileset 对象。此对象将在编辑器的场景视图中渲染 Google 地图图块，让您直观了解 AR 内容将显示在世界上的哪个位置。在 Geospatial Creator Origin 的检查器中，有一个字段用于添加您之前设置的 Map Tiles API 密钥。设置此键后，您应该会在“场景”视图中看到地图图块加载。
现在，更改纬度、经度和高度字段，使其位于您希望 AR 内容显示在应用中的位置附近。
编辑器中的场景视图现在应显示原点指定纬度和经度处的地图图块。在运行时，我们假设您的应用将使用 AR 相机，因此 Geospatial Creator 已使用“EditorOnly”标记配置 Cesium 3D 地图图块集对象。因此，在游戏运行时，系统不会下载或渲染这些图块。您可以在 Cesium3DTileset 对象的检查器中更改此设置。如需详细了解 Cesium 的地理参考和 3D Tileset GameObject，请参阅 Cesium for Unity 文档。
添加和放置 Geospatial Creator Anchor
现在，您就可以在场景中放置 AR 内容了！点击 GameObject > XR > Geospatial Creator Anchor，将锚点添加到场景层次结构中。在锚点的检查器中，您可以指定确切的纬度、经度和高度。 对象的转换将立即更新为场景中的正确位置，您可以准确了解对象将出现在世界中的哪个位置。
在微调锚点的纬度和经度时，请选择附近的位置，以便在运行时验证其是否位于正确的位置。在设置 Geospatial Creator 锚点的海拔高度时，您有三种选择：
- 地形将锚点放置在指定纬度和经度的地面上。地面高度由运行时 Visual Positioning System 确定。如果您是 ARCore Geospatial API 的新手，“Terrain”是一个不错的选择，因为锚点将直接在地面上解析，具有很高的垂直精度。您可以在“海拔偏移量”字段中输入一个固定值（以米为单位），将锚点放置在地面上方或下方。例如，指定“1.0”的偏移量会导致锚点“漂浮”在地形上方 1 米处。
- 屋顶将锚点放置在指定纬度和经度的任何结构的顶部。与地形锚点类似，“海拔偏移”字段可让您以米为单位，相对于屋顶位置向上或向下移动锚点。
- WGS84 将锚点放置在基于 WGS84 坐标系的特定绝对海拔高度（以米为单位）处。以这种方式放置对象可能需要进行一些反复试验，因为 WSG84 中的高度“0”并不一定表示平均海平面，并且可能与 GPS 的海拔高度不一致。此外，虽然渲染的 3D 地块的纬度和经度非常精确，但尝试使用 3D 地块作为参考将对象放置在地面上可能会导致高达数米的高度误差。
如需详细了解不同类型的 ARCore 地理空间锚点，请参阅地理空间开发者指南。
地形锚点和屋顶锚点都有 WGS84 海拔高度字段。此值仅在编辑器模式下使用，用于设置场景视图中对象的高度。 地形和屋顶高度仅在运行时确定，因此 WGS84 海拔高度字段可让您在开发应用时直观呈现特定高度的锚点。在运行时，系统会忽略地形和屋顶锚点的 WGS84 海拔高度字段。
向锚点添加几何图形
如果您现在构建并运行应用，您将不会在支持 AR 的应用中看到锚点。这是因为没有几何图形附加到该锚点。我们来向锚点添加一个简单的 3D 图元：在场景层次结构中，右键点击您的 AR 地理空间创建器锚点对象。在上下文菜单中，依次选择 3D 对象 > 立方体。您应该会在场景视图中看到一个灰色立方体，它是锚点的子对象。 如果您决定在编辑器中移动对象的位置或旋转角度，建议移动根锚点对象，而不是子立方体图元。 这有助于减少从纬度 / 经度到游戏坐标的转换中的错误。
当然，您也可以向锚点添加更复杂的几何图形和任意组件及子级。
构建并运行应用
现在，您可以在现实世界中看到锚点了！尝试构建并运行应用，然后前往您希望看到立方体的位置。它在那里吗？ 恭喜，您现在可以利用 Geospatial Creator 构建更复杂的 AR 体验了！
如果您有任何问题，请参阅问题排查指南。
现在是添加具有不同几何形状的其他 AR Geospatial Creator Anchor 的好时机。不妨尝试使用多个屋顶和地形锚点及其偏移量。添加脚本以实现动画效果或与对象互动。
了解 Geospatial Creator 锚点和 ARGeospatialAnchor 类
在构建复杂的互动式 AR 体验时，了解 Geospatial Creator 锚点与 ARCore 的 ARGeospatialAnchor C# 类之间的关系很有帮助：
ARGeospatialAnchor 只能在运行时通过调用 ARAnchorManager 上的某个函数来创建，并且只能在 AR 会话稳定后创建。Geospatial Creator 锚点可以看作是场景中的一个占位符，等待 AR 会话准备好解析 ARGeospatialAnchor 对象。
会话准备就绪后，占位符会自动调用 ARAnchorManager 来创建和解析 ARGeospatialAnchor。
在运行时锚点解析完毕后，场景层次结构中的地理空间创建器锚点将作为子对象附加到新的 GameObject。这意味着，地理空间创建器锚点的任何组件或子级都将成为新 ARGeospatialAnchor GameObject 的子组件或孙级。例如，附加到地理空间创建器锚点的几何图元 transform 将继承自 ARGeospatialAnchor 的 transform，因此将放置在运行时 AR 会话中的预期位置。
如果您需要在运行时识别特定的 ARGeospatialAnchor GameObject，可以搜索场景中 name 属性与使用 Geospatial Creator 创建的锚点相匹配的对象。如果 AR 会话已初始化，则该对象的 parent 将是相应的 ARGeospatialAnchor 对象。
问题排查
为什么我的锚点会移动？
您可能会注意到，尤其是在应用首次启动时，锚点可能会缓慢“漂移”，甚至突然跳动几米。当 VPS 会话仍在确定和优化摄像头确切位置时，就会发生这种情况。随着水平和垂直精确度在多个帧中不断提高，锚点会重新绘制到更精确的位置，从而产生移动的错觉。您可能希望在位置信息精确度达到一定阈值之前，以不同的方式（或根本不）呈现对象。为此，您可以查询 ARCoreEarthManager.CameraGeospatialPose 属性，以确定当前帧更新的准确性。
为什么我的锚点显示在错误的海拔高度？
为地理空间创建器锚点使用“手动”海拔高度类型时，锚点的高度将根据 WGS84 设置（以米为单位）。在给定位置，地图图块中显示的地面高度与 Google 的视觉定位系统 (VPS) 报告的实际地面高度之间可能存在几米的差异。如果地理空间锚点在运行时似乎位于错误的位置，我们建议您使用示例应用中的调试叠加层亲自验证 VPS 高度。然后，您可以在 Unity 编辑器中更改海拔高度，使其与该位置的已知 VPS 高度相匹配。
地图图块在编辑器的“场景”视图中无法正常渲染
如果 Cesium3DTileset 似乎正在加载图块，但它们在场景视图中以纯品红色渲染，请将 Unity 的 Shader Graph 软件包添加到您的项目中。Cesium 需要此软件包，但使用 Unity 内置渲染器的项目默认情况下不包含此软件包。
如需添加 Shader Graph，请打开 Unity Package Manager（Window > Package Manager）。确保您正在浏览 Unity Package Registry 上提供的软件包，方法是选择“Package Manager”（资源包管理器）窗口顶部下拉菜单中的“Packages: Unity Registry”（资源包：Unity 注册表）。搜索 com.unity.shadergraph 软件包并安装最新版本。软件包加载完毕后，3D 图块应在“场景视图”中重新加载并正确渲染。
应用在运行时显示黑屏，而不是相机视图
默认情况下，Unity 的通用渲染管线 (URP) 未针对 AR 摄像头进行配置。如果您在运行时看到的是黑屏而不是摄像头输出，则需要将 AR Background Renderer Feature 添加到场景中的每个 URP 渲染器。
如需添加该功能，请在项目中搜索“renderer”。对于每个 URP 渲染器对象，请在检查器中点击“添加渲染器功能”按钮，然后添加 AR 背景渲染器。
为什么放置在远离原点的锚点看起来放置不正确？
由于浮点运算精度有限，从 WGS84 坐标到 Unity 游戏坐标的转换可能会出现误差，您可以通过确保原点靠近 AR 锚点来最大限度地减少这种误差。超过 20 公里的距离可能会导致不准确。如果您的 AR 体验跨越很长的距离，建议您使用多个场景，并在每个场景中设置唯一的锚点。