使用 Google Maps Platform 的 Geospatial Creator 和 Places API 构建

1. 准备工作

Unity 中的 Geospatial Creator 由 ARCore 和 Google Maps Platform 中的仿真 3D 图块提供支持，让您可以在 Unity 编辑器中快速构建和直观呈现特定纬度和经度的增强现实 (AR) 体验。这可以大大缩短为应用构建单个地理定位 AR 场景所需的时间，但如果您想在不同位置创建多个类似体验，该怎么办？您也可以使用 Geospatial Creator 中的 C# API 来实现此目的。

在此 Codelab 中，您将编写 C# 代码，使用 Geospatial Creator 和 Google Maps Platform 中的 Places API，通过初始模板创建多个地理空间体验。在编译为应用之前，您可以在 Unity 编辑器中探索并微调生成的效果。

书本处于正确的高度

前提条件

学习内容

  • 如何在 Geospatial Creator 中使用 API 在多个位置创建和直观呈现一个地理定位体验。
  • 如何使用 Google Maps Platform 的 Places API 查找地点的位置。
  • 如何在设备上运行 AR 体验。

所需条件

2. 设置您的环境

如需使用 Geospatial Creator，您需要设置授权，以便访问 Google Cloud 上的仿真 3D 图块、ARCore 服务以及 Google Maps Platform 的 Places API。

设置 Google Cloud 项目

此 Codelab 需要一个启用了结算功能的 Google Cloud 项目，才能访问 Google 的服务器 API。您需要为此 Codelab 设置结算功能，但只有当项目超过免费服务的配额时才需要付费。

如需在 Google Cloud 中设置项目，请按以下步骤操作：

  1. 在 Google Cloud 控制台中创建一个项目。创建 Google Cloud 项目
  2. 在项目名称文本框中输入合适的名称，例如“ARCore Geospatial Project”，然后选择任意位置。
  3. 点击创建。
  4. 在 Google Cloud 控制台的项目选择器页面中，点击创建项目。
  5. 请参阅启用结算功能，并查看仿真 3D 图块的价格和 Places API（新）的价格。

启用 Map Tiles API

Map Tiles API 提供仿真 3D 图块，这些图块可在 Unity 编辑器中显示。

启用 ARCore API

借助 Google Cloud 上的 ARCore API，您可以在目标设备上访问 ARCore Geospatial API。

  • 如需启用 ARCore API，请点击以下按钮，然后选择启用：

启用 Places API

借助 Google Maps Platform 的 Places API，您可以获取超过 2 亿个地点的地理位置数据，您将在 Codelab 中使用这些数据来查找相关地点。此 API 可提供地点的搜索结果和地理坐标。

  • 如需启用 Places API，请点击以下按钮，然后选择启用：

为您的项目创建 API 密钥

如需使用 API 密钥身份验证来向远程 Google Cloud 服务验证应用的身份，请按以下步骤操作：

  1. 在 Google Cloud 控制台中的 API 和服务下，选择凭据。
  2. 在页面顶部，点击创建凭据，然后选择 API 密钥。
  3. 请记下此密钥，因为需要在接下来的步骤中使用。

设置软件

如需开始使用 Geospatial Creator 软件，请按照以下步骤操作：

  1. 克隆此代码库。
  2. 下载 Unity Hub 并使用它来安装 Unity 版本 2022.3。确保您安装的是 Android 或 iOS 可选 build 工具。
  3. 在 Unity Hub 中，依次按添加 > 从磁盘添加项目。
  4. 在 Hierarchy 面板中，选择 AR Geospatial Creator Origin。
  5. 在 Google Maps Tile API Key 文本框中，插入 API 密钥，然后按 Enter（在 macOS 上按 return）。将 API 密钥插入到 Geospatial Creator Origin 中
  6. 在 Edit > Project Settings > XR Plug-in Management > ARCore Extensions 中，针对 Android 或 iOS 使用 API 密钥身份验证，然后插入 API 密钥。
  7. 在 File > Build Settings 中，将目标平台切换为 Android 或 iOS。

3. 创建您的第一个锚点

在此 Codelab 中，您将创建一个可在多个位置使用的 AR 锚点。您可以使用加利福尼亚州旧金山的公共图书馆作为示例，但也可以随意使用您附近的地点。

Geospatial Creator 的 Origin 组件简介

使用 Geospatial Creator 构建的每个 Unity 场景都需要一个 Geospatial Creator 原点。此游戏对象是用于将真实世界的纬度、经度和海拔高度值转换为 Unity 游戏坐标的参考点。

示例项目包含一个 Geospatial Creator Origin，该 Origin 使用 Cesium 在编辑器的 Scene 视图中渲染仿真 3D 图块，让您可以直观地了解 AR 内容将显示在世界上的哪个位置。

移动原点

将 Geospatial Creator 的原点移至旧金山主图书馆分馆的纬度和经度。

如需使用 Geospatial Creator 与 Places API 的内置集成功能自动将原点重新定位到正确的位置，请按照以下步骤操作：

  1. 在 Hierarchy 面板中，选择 Geospatial Creator Origin 游戏对象。
  2. 在检查器面板中，点击搜索位置。
  3. 在搜索对话框中，输入 San Francisco Public Library。第一条结果应是 100 Larkin Street。
  4. 点击应用于对象，将搜索结果应用于来源。您应该会看到原点的纬度和经度更新为新坐标。

建筑物在画面中

向场景中添加 Geospatial Creator 锚点

现在，我们已经创建了一个 Origin，接下来可以使用 GameObject > XR > AR Geospatial Creator Anchor 添加一个 Geospatial Creator 锚点。默认情况下，锚点将与原点位于同一位置。

使用此锚点来定位我们的 3D AR 内容。示例项目中包含一本书的 3D 模型。

如需将图书放置在场景中，请按以下步骤操作：

  1. 在 Project 面板中，将 Book 模型拖动到 Editor 视图窗格中。
  2. 在 Hierarchy 面板中，确保 Book 是您之前创建的锚点的子级。地理空间创建器锚点的任何子游戏对象都将相对于该锚点定位。
  3. 在 Hierarchy 面板中，选择 Book。将其位置值设置为 0、0、0。

图书已添加到场景中

在编辑器视图中查看此模型时，很明显存在问题：锚点的默认海拔高度低于图书馆的屋顶表面，而它应该漂浮在屋顶上方。

虽然您可以在编辑器中移动对象以找到大致的 WGS84 海拔高度，但最好在这种情况下将地理空间锚点配置为屋顶锚点，以便其海拔高度相对于其上方的建筑物屋顶自动固定。

  • 为此，请打开锚点的检查器面板，并将 Altitude Type 属性设置为 Rooftop。

检查器面板

完成此操作后，请注意锚点的海拔高度在编辑器视图中不会发生变化。这是因为，在为屋顶锚点和地形锚点解析锚点时，锚点的高度是在运行时确定的。如需在 Scene 视图中直观呈现屋顶上的锚点，您可以使用贴靠到地块按钮。这会将锚点的海拔高度设置为与 Scene 视图中的图块相匹配，同时不会影响运行时已解析锚点的海拔高度。

  • 若要让模型悬浮在图书馆屋顶上方，而不是放置在屋顶上，请将 Altitude relative to rooftop 参数更改为屋顶上方 15 米。

模型现在可以很好地悬浮在库上方了！

书本处于正确的高度

您的项目现在拥有完整的地理空间 AR 场景，包括所有必需的 AR 系统组件、地理空间创建器原点和一个附加了模型的锚点。

接下来，在其他图书馆位置制作重复的锚点。

4. 使用 Places API 查找新的锚点位置

借助 Google Maps Platform 的 Places API，您可以获取超过 2 亿个地点的地理位置数据。在此 Codelab 中，您将使用此 API 在旧金山查找其他公共图书馆的分馆，并使用这些结果为接下来的 10 个搜索结果生成 Geospatial Creator 锚点。

  • 首先，依次点击 Assets > Scripts > Editor，然后打开“AnchorDuplicator.cs”文件。此文件提供了一些样板代码，可帮助您开始使用 Places API 并解析其结果。

使用 Places API 进行身份验证

  1. 在 AnchorDuplicator 类中找到以下代码行：
    private const string API_KEY = "<YOUR_API_KEY_HERE>";
  2. 将 <YOUR_API_KEY_HERE> 替换为在设置步骤中获取的密钥。

针对搜索字词查询 Places API

完成 Places API 授权设置后，您就可以编写代码来发起 POST 请求了。

  • 为此，请找到 CreatePlacesRequest 方法并使用以下方法定义：
    string postBody = "{ \"textQuery\": \"" + searchTerm + "\", " + 
                    "   \"locationBias\": { \"circle\": { " +
                    "      \"center\": { \"latitude\": " + lat + ", \"longitude\": " + lon + " }, " +
                    "      \"radius\": 10000 }" +
                    "   }" +
                    "}";

string url = "https://places.googleapis.com/v1/places:searchText";

UnityWebRequest request = UnityWebRequest.Post(url, postBody, "application/json");
request.SetRequestHeader("X-Goog-Api-Key", apiKey);
request.SetRequestHeader("X-Goog-FieldMask", "places.displayName,places.location");

return request;
    现在，当调用 CreatePlacesRequest 方法时，系统会发出请求，在以 lat 和 lon 为圆心的圆内搜索 searchTerm。

测试您的工作

在继续操作之前，您需要验证对 Places API 的调用是否成功。

  1. 在 Unity 编辑器中运行函数：
    1. 在 Google AR Codelab 中，点击 Run Places Request。
    2. 打开 Unity 控制台。您应该会看到结果显示出来。地点显示在控制台中

5. 以编程方式向地点添加锚点

现在，您已验证 Places API 可以找到结果，接下来请在结果指定的每个位置创建新的 Geospatial Creator 锚点。

创建菜单项

  1. 在 AnchorDuplicator 类中，找到 CreateNewAnchorsFromPlaces 方法并使用以下方法定义：
    if (_places == null)
{
    Debug.LogError("Cannot create anchors: Places has not been initialized.");
    return;
}

// You start with only one anchor in the scene, which you want to copy:
var prototypeAnchorObject = GameObject
    .FindObjectOfType<ARGeospatialCreatorAnchor>()
    .gameObject;

foreach (var place in _places)
{
    var newAnchorObject = GameObject.Instantiate(prototypeAnchorObject);
    var anchor = newAnchorObject.GetComponent<ARGeospatialCreatorAnchor>();
    anchor.Latitude = place.location.latitude;
    anchor.Longitude = place.location.longitude;

    newAnchorObject.name = place.displayName.text;
}
    此菜单项会检查之前启动的请求，并使用场景中的第一个 ARGeospatialCreatorAnchor 作为创建锚点的原型，Places API 结果中的每个地点对应一个锚点。
  2. 使用 Google AR Codelab 中的新菜单项根据地点响应创建新锚点来创建锚点。
  3. 您应该会在 Hierarchy 窗格中看到多个锚点。

验证锚点的位置

如需在运行应用之前验证所有素材资源是否都锚定在正确的位置，请按以下步骤操作：

  1. 在层次结构窗格中，点击已添加的锚点。
  2. 按 F。
  3. 检查 Scene 视图中的锚点。
  4. 如果锚点不在正确的位置，请点击贴靠到地块，或手动更改 Latitude、Longitude 或 Editor Override Altitude 值。

6. 在 AR 中查看作品

如需在支持 ARCore 的 Android 或 iOS 设备上以 AR 模式查看资源，请按以下步骤操作：

  1. 点击 File > Build Settings，然后选择 Android 或 iOS 构建平台。
  2. 点击 Switch platform。
  3. 确保您的开发设备已连接并针对开发进行了配置。
  4. 点击 Build and Run。
  5. 确认应用可在设备上运行。
  6. 前往您锚定内容的位置。如果您未更改示例，则这些地点是旧金山的公共图书馆。

查看 AR 体验

7. 总结

恭喜！您编写了一个 Unity 应用，该应用使用 Geospatial Creator 和 Google Maps Platform Places API，通过初始模板创建多个地理空间体验。我们希望您能利用这些知识来扩大 Geospatial Creator 内容的覆盖面！

了解详情