您可以使用 Unity 適用的 ARCore Geospatial Creator，以全新的 3D 圖塊格式顯示 Google 地圖資料，在 Unity 編輯器中預覽地理空間內容。這項功能可協助您在建構應用程式時，預覽內容在現實世界中的位置。
Geospatial Creator 隨附於 AR Foundation 的 ARCore Extensions。本快速入門導覽課程將說明如何在 Unity 中使用 Geospatial Creator，將地理空間 AR 內容新增至 ARCore 地理空間範例應用程式。
如果您想使用現有應用程式，而非地理空間範例，請先按照 Unity 適用的地理空間開發人員指南操作。為應用程式設定 Geospatial API 後，請跳至下方的「新增必要依附元件」步驟，並從該處繼續操作。
必要條件
請按照「ARCore Extensions for AR Foundation 入門指南」的說明，設定 Unity 環境來建立 AR 體驗。
雖然 ARCore Extensions 支援舊版 Unity，但 Geospatial Creator 必須使用 Unity 2021.3 以上版本。
API 授權
如要使用 ARCore Geospatial API 和 Google 地圖圖塊 API，您必須設定 API 存取權。
Google Map Tiles API
Map Tiles API 提供支援地點的 3D 擬真成像表示法。我們會在 Unity 編輯器中使用這些圖塊，預覽 AR 場景周圍的區域。
請參閱 Map Tiles API 頁面，啟用 API 並進一步瞭解 Map Tiles。
ARCore Geospatial API
應用程式會在執行階段使用 ARCore Geospatial API，建立及互動地理空間錨點。
如要啟用 Geospatial API，請在應用程式中設定 ARCore API。您可以使用「免金鑰」(建議) 或「API 金鑰」授權方法。
擴充地理空間範例應用程式
本指南將說明如何使用 Geospatial Creator，將地理空間內容新增至 ARCore Geospatial 範例應用程式。
設定地理空間範例
首先，請熟悉 ARCore Geospatial Sample 應用程式。在新的 Unity 專案中，開啟 Unity Package Manager 並選取 ARCore Extensions 套件。在「Package Manager」詳細資料面板中展開「Samples」，然後將 Geospatial Sample 匯入 Unity 專案。
執行應用程式前，您必須在專案中啟用 ARCore 和地理空間功能。使用「編輯」>「專案設定...」> XR Plug-in Management。勾選適當的方塊，為 Android 啟用 ARCore 外掛程式供應商，以及/或是為 iOS 啟用 ARKit 外掛程式供應商。
然後依序前往「Edit」>「Project Settings...」> XR Plug-in Management，開啟「ARCore Extensions」面板。確認已勾選「地理空間」(您還不需要啟用 Geospatial Creator)，然後輸入 API 憑證。詳情請參閱「啟用 Geospatial Unity API」說明文件中的 Android 和 iOS 部分。
如果 Unity 應用程式使用 ARCore，則必須進行其他幾項平台專屬的 Player 設定。如需瞭解必要變更，請參閱文件中的「設定 Player 設定」一節。
此時，場景中除了執行 Geospatial Sample 所需的物件外，沒有其他遊戲物件。現在很適合建構及執行應用程式。如果設定正確，應用程式在執行階段會顯示裝置的攝影機畫面。移動時，畫面頂端顯示的地理空間準確度會開始提升。輕觸螢幕即可建立地理空間錨點，這些錨點會保留在原始位置，不會隨著你移動而改變。
接著，我們將說明如何使用 Geospatial Creator，在 Unity 編輯器中建立及顯示精密的 AR 內容。這類內容會顯示在應用程式中，位於世界各地的特定經緯度位置。
新增必要的依附元件
Geospatial Creator 會使用名為 Cesium 的第三方 Unity 套件，在 Unity 編輯器的「Scene」視窗中算繪 Google 地圖圖塊。啟用地理空間建立工具功能前，請先將 Cesium 套件新增至專案。
建議您從 Cesium 的 GitHub 頁面安裝最新版 Cesium for Unity 套件：
- 從 GitHub 版本頁面下載最新版的 Cesium for Unity 預先編譯
.tgz。目前建議使用的 Cesium for Unity 套件版本為 1.1.0。 - 開啟 Unity 的「Window」選單，然後選取「Package Manager」，即可開啟 Unity Package Manager。
- 按一下「+」圖示，然後選擇「Add package from tarball」(從 tarball 新增套件)。
- 選取步驟 1 下載的 Cesium for Unity .tgz 檔案。
- 系統可能會提示您安裝其他依附元件，例如 Text Mesh Pro。
啟用 Geospatial Creator
現在可以啟用地理空間創作者：
- 在「Build Settings」對話方塊中，確認所選平台為「Android」或「iOS」。目前其他平台無法使用 Geospatial Creator 功能。
- 依序前往「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」。
- 如果您在先前的步驟中未設定 ARCore Android 和/或 iOS API 金鑰，請務必現在設定。
- 啟用「地理空間」和「Geospatial Creator」切換按鈕。按一下啟用「地理空間建立工具」切換按鈕後，系統會顯示非模式精靈，確認專案是否與地理空間建立工具相容。
- 按一下精靈中的「完成」。
完成精靈後，Unity 會觸發指令碼的編譯作業。 請等待重新編譯完成，再繼續操作。(如果選取的平台不是「Android」或「iOS」，請立即切換至其中一個平台)。
使用地圖圖塊新增 Geospatial Creator Origin
場景必須只有一個「Geospatial Creator Origin」物件。這個物件會做為參考點，將真實世界的經緯度和海拔高度值轉換為 Unity 遊戲座標。
如要在場景中新增 Geospatial Creator Origin，請依序選取「Game Object」>「XR」>「Geospatial Creator Origin」。新建立的物件需要地理參考，將特定經緯度與海拔高度連結至遊戲座標中的原點位置。在 Geospatial Creator Origin 的「檢查器」窗格中，按一下「新增 Cesium 地理參考元件」按鈕，即可新增地理參考。
除了做為 AR 物件的參考點，Cesium Georeference 還會在場景中新增 Cesium 3D Tileset 物件。這個物件會在編輯器的場景檢視畫面中算繪 Google 地圖圖塊，讓您準確瞭解 AR 內容在世界上的顯示位置。在 Geospatial Creator Origin 的檢查器中，有一個欄位可供您新增先前設定的 Map Tiles API 金鑰。設定這個金鑰後，您應該會在「場景」檢視畫面中看到地圖圖塊載入。
現在請變更經度、緯度和高度欄位，將位置設在您希望 AR 內容顯示在應用程式中的位置附近。
現在，編輯器中的場景檢視畫面應該會顯示原點指定經緯度的地圖圖塊。在執行階段，我們假設您的應用程式會使用 AR 相機，因此 Geospatial Creator 已使用「EditorOnly」標記設定 Cesium 3D Map Tileset 物件。因此，遊戲不會在執行階段下載或算繪圖塊。這項設定可透過 Cesium3DTileset 物件的檢查器變更。如要進一步瞭解 Cesium 的地理參考和 3D Tileset GameObject，請參閱 Cesium for Unity 說明文件。
新增及放置地理空間創作者錨點
現在可以將 AR 內容放置在場景中！依序點選「GameObject」>「XR」>「Geospatial Creator Anchor」，將錨點新增至場景階層。在錨點的檢查器中，您可以指定確切的緯度、經度和高度。物件的變形會立即更新為場景中的正確位置，您也可以準確查看物件在世界中的顯示位置。
微調錨點的緯度和經度時，請選擇附近的位置，以便在執行階段驗證錨點是否位於正確位置。設定地理空間創作者錨點的海拔高度時，有三種做法：
- Terrain 會將錨點放在指定經緯度的地面上。視覺定位系統會在執行階段決定地面層級。如果您是 ARCore Geospatial API 的新手，「Terrain」是不錯的選擇，因為錨點會直接在地面上解析，垂直準確度高。「海拔高度偏移」欄位可讓您以公尺為單位，將錨點固定在地面以上或以下。舉例來說，如果將偏移量指定為「1.0」，錨點就會「浮動」在地形上方一公尺處。
- 屋頂：將錨定點放置在指定經緯度任何建築物的頂端。與地形錨點類似，「海拔高度偏移」欄位可讓您以公尺為單位，相對於屋頂位置向上或向下移動錨點。
- WGS84 會根據 WGS84 座標系統，將錨點放置在特定絕對高度 (以公尺為單位)。以這種方式放置物件可能需要經過一些試誤，因為 WSG84 中的「0」高度不一定代表平均海平面，可能與 GPS 的海拔高度不符。此外，雖然算繪的 3D 圖塊經緯度非常準確，但如果嘗試以 3D 圖塊做為參考，將物件放置在地面層級，可能會導致高度誤差達數公尺。
如要進一步瞭解不同類型的 ARCore 地理空間錨點，請參閱地理空間開發人員指南。
地形和屋頂錨點都有 WGS84 海拔高度欄位。這個值僅用於編輯器模式，可設定場景檢視區中物件的高度。地形和屋頂高度只會在執行階段決定，因此您可以在開發應用程式時，透過「WGS84 Altitude」(WGS84 海拔高度) 欄位，以特定高度顯示錨點。在執行階段，系統會忽略地形和屋頂錨點的「WGS84 Altitude」(WGS84 海拔高度) 欄位。
將幾何圖形新增至錨點
現在建構及執行應用程式時，您不會在啟用 AR 的應用程式中看到錨點，因為錨點未附加任何幾何圖形。讓我們在錨點中加入簡單的 3D 原始物件：在場景階層中，對 AR Geospatial Creator Anchor 物件按一下滑鼠右鍵。在內容選單中，選擇「3D 物件」>「立方體」。場景檢視畫面中應該會顯示灰色立方體，做為錨點的子項。 如果您決定在編輯器中移動物件的位置或旋轉角度，建議移動根錨點物件，而非子項 Cube 原始物件。這有助於減少將經緯度轉換為遊戲座標時發生的錯誤。
當然，您也可以在錨點中新增更複雜的幾何圖形、任意元件和子項。
建構並執行應用程式
現在可以看看現實世界中的錨點了！請嘗試建構及執行應用程式，然後移動到您預期會看到立方體的位置。是否已顯示在畫面上？ 恭喜！您已準備好使用 Geospatial Creator 建構更複雜的 AR 體驗！
如有任何問題，請參閱疑難排解指南。
現在正是好時機，可使用不同幾何圖形新增其他 AR Geospatial Creator Anchors。請嘗試使用多個屋頂和地形錨點及其偏移量。新增指令碼，為物件加入動畫效果或啟用互動功能。
瞭解 Geospatial Creator Anchors 和 ARGeospatialAnchor 類別
建構複雜的互動式 AR 體驗時，瞭解地理空間建立工具錨點與 ARCore 的 ARGeospatialAnchor C# 類別之間的關係，有助於開發作業：
ARGeospatialAnchor
只能在執行階段透過叫用 ARAnchorManager 上的其中一個函式建立，且只能在 AR 會話穩定後建立。您可以將 Geospatial Creator Anchor 視為場景中的預留位置，等待 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 高度相符。
地圖圖塊無法在編輯器的場景檢視畫面中正確算繪
如果 Cesium3DTileset 似乎正在載入圖塊，但這些圖塊在場景檢視畫面中以實心洋紅色呈現，請將 Unity 的 Shader Graph 套件新增至專案。Cesium 需要這個套件，但使用 Unity 內建算繪器的專案預設不會包含這個套件。
如要新增 Shader Graph，請開啟 Unity Package Manager (依序選取「Window」>「Package Manager」)。請在套件管理工具視窗頂端的下拉式選單中選取「Packages: Unity Registry」，確保您正在瀏覽 Unity 套件登錄檔提供的套件。搜尋 com.unity.shadergraph 套件並安裝最新版本。載入套件後，3D 圖塊應會重新載入，並在場景檢視畫面中正確算繪。
應用程式在執行階段顯示黑畫面，而非攝影機畫面
Unity 的通用算繪管線 (URP) 預設不會為 AR 攝影機設定。如果在執行階段看到黑畫面，而非攝影機輸出內容，請在場景中為每個 URP 算繪器新增 AR Background Renderer Feature。
如要新增這項功能，請在專案中搜尋「renderer」。針對每個 URP 算繪器物件，按一下檢查器中的「Add Renderer Feature」按鈕，然後新增 AR Background Renderer。
為什麼遠離原點的錨點似乎放置錯誤？
由於浮點算術精確度，從 WGS84 座標轉換為 Unity 遊戲座標時可能會發生錯誤，因此請確保原點靠近 AR 錨點，盡量減少這類錯誤。如果距離超過 20 公里，可能會導致結果不準確。如果 AR 體驗涵蓋長距離，建議使用多個場景，每個場景都有專屬錨點。