使用 Google 地圖平台的地理空間建立工具和 Places API 建構應用程式

1. 事前準備

Unity 中的 Geospatial Creator 採用 ARCore 和 Google 地圖平台的擬真 3D 圖塊，可讓您在 Unity 編輯器中，針對特定經緯度快速建構及顯示擴增實境 (AR) 體驗。這樣可以大幅縮短為應用程式建構單一地理位置 AR 場景的時間，但如果想在不同地點建立多個類似的體驗，該怎麼做呢？您也可以在 Geospatial Creator 中使用 C# API 執行這項操作。

在本程式碼研究室中，您將編寫 C# 程式碼，使用 Geospatial Creator 和 Google 地圖平台的 Places API，透過初始範本建立多個地理空間體驗。在編譯成應用程式之前，您可以在 Unity 編輯器中探索及微調產生的體驗。

書本高度適中

必要條件

課程內容

  • 瞭解如何在 Geospatial Creator 中使用 API，在多個地點建立及顯示一個地理位置體驗。
  • 瞭解如何使用 Google 地圖平台的 Places API 尋找地點位置。
  • 如何在裝置上執行 AR 體驗。

軟硬體需求

2. 設定環境

如要使用 Geospatial Creator，您必須設定授權，才能存取擬真 3D 圖塊、Google Cloud 上的 ARCore 服務，以及 Google 地圖平台的 Places API。

設定 Google Cloud 專案

本程式碼研究室需要已啟用計費功能的 Google Cloud 專案，才能存取 Google 的伺服器 API。這個程式碼研究室需要設定帳單資訊，但只有當專案的費用超出免付費服務配額時，系統才會收取費用。

如要在 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 編輯器中顯示。

  • 如要啟用 Map Tiles API，請按一下下列按鈕，然後選取「啟用」：

啟用 ARCore API

Google Cloud 上的 ARCore API 可讓您在目標裝置上存取 ARCore Geospatial API。

  • 如要啟用 ARCore API，請按一下下列按鈕，然後選取「啟用」：

啟用 Places API

Google 地圖平台的 Places API 可讓您取得超過 2 億個地點的位置資料，您將在程式碼研究室中使用這些資料尋找相關地點。這項 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 選用建構工具。
  3. 在 Unity Hub 中，依序按下「Add」>「Add project from disk」。
  4. 在「Hierarchy」(階層) 面板中，選取「AR Geospatial Creator Origin」(AR 地理空間建立工具來源)。
  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. 建立第一個錨點

在本程式碼研究室中，您將建立可在多個位置使用的 AR 錨點。以加州舊金山的公共圖書館為例，但您可隨意使用您附近的地點。

關於 Geospatial Creator 的 Origin 元件

使用 Geospatial Creator 建構的每個 Unity 場景都必須有一個 Geospatial Creator Origin。這個遊戲物件是將真實世界中的經緯度和海拔高度值轉換為 Unity 遊戲座標的參考點。

範例專案包含 Geospatial Creator Origin，可使用 Cesium 在編輯器的 Scene 檢視畫面中算繪擬真 3D 圖塊，讓您準確掌握 AR 內容在現實世界中的顯示位置。

移動原點

將 Geospatial Creator 原點移至舊金山主圖書館分館的經緯度。

如要使用 Geospatial Creator 內建的 Places API 整合功能，自動將原點重新定位到正確位置，請按照下列步驟操作：

  1. 在「Hierarchy」(階層) 面板中，選取「Geospatial Creator Origin」遊戲物件。
  2. 在「檢查器」面板中，按一下「搜尋位置」。
  3. 在搜尋對話方塊中輸入 San Francisco Public Library。第一個結果應為 Larkin Street 100 號。
  4. 按一下「套用至物件」，將搜尋結果套用至來源。您應該會看到來源的經緯度更新為新座標。

建築物在視野範圍內

在場景中新增 Geospatial Creator 錨點

現在有了 Origin，請使用「GameObject」>「XR」>「AR Geospatial Creator Anchor」新增 Geospatial Creator 錨點。根據預設，錨點會與原點共用位置。

使用這個錨點放置 3D AR 內容。範例專案隨附書籍的 3D 模型。

如要在場景中放置書籍，請按照下列步驟操作：

  1. 在「Project」面板中，將「Book」模型拖曳至「Editor」檢視窗格。
  2. 在「Hierarchy」面板中，確認「Book」是您先前建立的錨點子項。地圖空間建立工具錨點的任何子項遊戲物件，都會相對於錨點定位。
  3. 在「階層」面板中選取「書籍」。將位置值設為 0、0、0。

書籍會新增到場景

在編輯器檢視畫面中查看這個模型時，很明顯有問題：錨點的預設高度低於圖書館的屋頂表面，但應該要高於屋頂。

雖然您可以在編輯器中移動物件，找出大致的 WGS84 海拔高度，但建議您在此情況下將地理空間錨點設為屋頂錨點，讓系統自動修正錨點相對於上方建築物屋頂的海拔高度。

  • 如要這麼做，請開啟錨點的檢查器面板，並將 Altitude Type 屬性設為 Rooftop。

檢查器面板

完成後請注意，錨點的高度不會在編輯器檢視畫面中變更。這是因為系統會在執行階段解析錨點時，判斷屋頂和地形錨點的錨點海拔高度。如要在 Scene 檢視畫面中查看屋頂上的錨點，請使用「對齊圖塊」按鈕。這會將錨點的海拔高度設為與 Scene 檢視區塊中的圖塊相符，但不會影響執行階段已解析錨點的海拔高度。

  • 如要讓模型懸浮在圖書館屋頂上方，而非放在屋頂上，請將 Altitude relative to rooftop 參數變更為屋頂上方 15 公尺。

模型現在會順利浮動在程式庫上方！

書本高度適中

現在專案中已有完整的地理空間 AR 場景，包括所有必要的 AR 系統元件、地理空間建立工具原點，以及一個附有模型的錨點。

接著，在其他程式庫位置複製錨點。

4. 使用 Places API 尋找新的錨點位置

Google 地圖平台的 Places API 可讓您取得超過 2 億個地點的位置資料。在本程式碼研究室中，您將使用這項 API 尋找舊金山其他公共圖書館分館，並使用這些結果為接下來的十個搜尋結果產生 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 程式碼研究室中，按一下「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 中的新「Create New Anchors from Places Response」(從地點回應建立新錨點) 選單項目建立錨點。
  3. 您應該會在「Hierarchy」窗格中看到多個錨點。

確認錨點位置

如要確認所有資產都已錨定在正確位置，請按照下列步驟操作：

  1. 在「Hierarchy」(階層) 窗格中，按一下新增的錨點。
  2. 按 F 鍵。
  3. 檢查 Scene 檢視區塊中的錨點。
  4. 如果錨點位置不正確，請按一下「Snap to Tile」，或手動變更 Latitude、Longitude 或 Editor Override Altitude 值。

6. 在 AR 中查看資產

如要在支援 ARCore 的 Android 或 iOS 裝置上以 AR 檢視資產，請按照下列步驟操作：

  1. 依序點選「File」>「Build Settings」，然後選取「Android」或「iOS」建構平台。
  2. 按一下「切換平台」。
  3. 確認開發裝置已連線，並已設定為開發用途。
  4. 按一下「Build and run」(建構並執行)。
  5. 確認應用程式可在裝置上執行。
  6. 前往錨定內容的位置。如果您未變更範例，這些地點就是舊金山的公共圖書館。

查看 AR 體驗

7. 結語

恭喜！您使用 Geospatial Creator 和 Google 地圖平台 Places API，以初始範本建立多個地理空間體驗，並編寫 Unity 應用程式。希望這些知識有助於擴大地理空間創作者內容的觸及範圍！

瞭解詳情