Unity 的 ARCore Geospatial Creator 可讓您在 Unity 編輯器中預覽地理空間內容，使用新的 3D 圖塊格式顯示 Google 地圖資料。這可協助您在建構應用程式時，透過視覺化方式呈現內容將出現在真實世界中的哪個位置。
地理空間建立者提供適用於 AR 基礎的 ARCore 擴充功能。本快速入門導覽課程將說明如何使用 Unity 的地理空間建立者，在 ARCore 地理空間範例應用程式中加入地理空間 AR 內容。
如果您要使用的現有應用程式，而非地理空間範例，那麼您首先必須遵守 Unity 的地理空間開發人員指南。在應用程式設定好地理空間 API 的使用後，請跳到下方的「新增必要的依附元件」步驟，繼續完成後續步驟。
必備條件
按照「Getting started with ARCore Extensions for AR Foundation」的說明設定 Unity 環境，打造 AR 體驗。
雖然 ARCore 擴充功能支援舊版 Unity，但地理空間創作者需要使用 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 地理空間 API
應用程式會在執行階段使用 ARCore Geospatial API 建立地圖，並與地理空間錨點互動。
如要啟用地理空間 API，請在應用程式中設定 ARCore API。您可以選擇使用無金鑰 (建議) 或 API 金鑰授權方法。
擴充地理空間範例應用程式
本指南將說明如何使用地理空間建立者，在 ARCore 地理空間範例應用程式中加入地理空間內容。
設定地理空間樣本
首先，建議您熟悉 ARCore 地理空間範例應用程式。請在新的 Unity 專案中開啟 Unity 套件管理員，然後選取 ARCore Extensions 套件。在「Package Manager」詳細資料面板中，展開「Samples」，並將地理空間範例匯入您的 Unity 專案。
執行應用程式前，您必須在專案中啟用 ARCore 和地理空間功能。使用「Edit」>「Project Settings...」> XR 外掛程式管理。勾選適當的方塊，以啟用 Android 的 ARCore 外掛程式供應商和/或 iOS 的 ARKit 外掛程式供應商。
接著，從「Edit」>「Project Settings」... > XR 外掛程式管理，開啟「ARCore Extensions」面板。確認已勾選「地理空間建立者」選項 (目前還不必啟用地理空間建立者)，然後輸入您的 API 憑證。詳情請參閱 Android 版和 iOS 版「啟用地理空間 Unity API」說明文件。
使用 ARCore 的任何 Unity 應用程式都必須要有其他幾項平台專屬的播放器設定。如需必要變更資訊，請參閱文件的「設定播放器設定」一節。
目前，場景中沒有任何遊戲物件，而且執行地理空間樣本的必備項目除外。建議您現在建構並執行應用程式。如果已正確設定，應用程式就會在執行階段顯示裝置的相機檢視畫面。移動時，螢幕頂端顯示的地理空間準確度將會開始改善。透過輕觸畫面，您可以建立地理空間錨點，此錨點會一直停留在原本的位置，您四處移動。
接下來，我們會說明如何在 Unity 編輯器中，使用地理空間建立者建立精細的 AR 內容，並以視覺化方式呈現。這類內容會顯示在應用程式中特定的經緯度位置。
新增必要的依附元件
地理空間建立者使用名為 Cesium 的第三方 Unity 套件，在 Unity 編輯器的場景視窗中算繪 Google 地圖圖塊。啟用地理空間建立者功能之前，請先在專案中加入 Cesium 套件。
建議您從 Cesium 的 GitHub 頁面安裝最新版的 Unity 適用的 Cesium 套件：
- 從 GitHub 版本頁面下載最新版本的 Cesium 預先編譯的
.tgz版本。目前建議使用的 Unity 套件 Cesium 版本為 1.1.0。 - 按一下 Unity 的「Window」選單，然後選取「Package Manager」，開啟 Unity 套件管理員。
- 按一下「+」圖示，然後選擇「Add package from tarball」。
- 選取您在步驟 1 下載的 Cesium for Unity .tgz 檔案。
- 系統可能會提示您安裝其他依附元件，例如文字網格 Pro。
啟用地理空間建立者
您現在可以啟用地理空間建立者了：
- 在「Build Settings」對話方塊中，確認您選取的平台為「Android」或「iOS」。其他平台目前無法使用地理空間建立者功能。
- 依序前往「Project Settings」 >「XR Plug-in Management」 >「ARCore Extensions」。
- 若您未在之前的步驟中設定 ARCore Android 和/或 iOS API 金鑰，請務必立即執行。
- 啟用「地理空間」和「地理空間建立者」切換按鈕。點選啟用「地理空間建立者」切換按鈕後，畫面會顯示非強制回應精靈，以確認您的專案與地理空間建立者相容。
- 按一下精靈中的「完成」。
完成精靈後，Unity 會觸發指令碼編譯。等待重新編譯完成再繼續操作。(如果您選取的平台不是「Android」或「iOS」，請立即改用其中一個平台)。
使用地圖圖塊新增地理空間建立者來源
您的場景只需要一個「地理空間創作者來源」物件。這個物件會做為參考點，將實際的緯度、經度和高度值轉換為 Unity 遊戲座標。
如要在場景中新增地理空間建立者來源，請依序選取「Game Object」>「XR」>「地理空間創作者來源」。新建立的物件需要使用地理參照，將特定經緯度和高度連結至遊戲座標中的起點位置。在地理空間創作者來源的「Inspector」窗格中，按一下「Add Cesium Georeference 元件」按鈕，新增地理參照。
除了做為 AR 物件的參考點之外，Cesium Georeference 還會在場景中加入 Cesium 3D Tileset 物件。這個物件會在編輯器的場景檢視畫面中算繪 Google 地圖圖塊，方便您透過視覺化方式瞭解 AR 內容在世界上的確切顯示位置。地理空間建立者來源檢查器有一個欄位，可用來新增您先前設定的地圖圖塊 API 金鑰。設定這個索引鍵後，地圖圖塊應該就會載入「場景」檢視畫面中。
接著，將經緯度欄位變更為想在應用程式中顯示 AR 內容的位置。
編輯器中的場景檢視現在應會根據起點指定的經緯度顯示地圖圖塊。在執行階段，我們假設您的應用程式將使用 AR 相機，因此地理空間建立者已使用「EditorOnly」標記設定 Cesium 3D 地圖圖塊物件物件。因此，不會在遊戲執行階段下載或轉譯資訊方塊。這項設定可以透過 Cesium3DTileset 物件的檢查器變更。如要進一步瞭解 Cesium 的地理參照和 3D Tileset GameObjects，請參閱 Unity 的 Cesium 說明文件。
新增及放置地理空間建立者錨點
您現在可以將 AR 內容放入場景中！依序點選「GameObject」>「XR」>「Geospace Creator Anchor」，在場景階層中新增錨點。在錨點檢查器中，您可以指定確切的緯度、經度和高度。物件的轉換將立即更新為場景中的正確位置，而您可以確實瞭解物件在世界中的顯示位置。
在微調錨點的經緯度時，請選擇一個較靠近的位置，以便在執行階段驗證該位置的正確位置。設定地理空間建立者錨點的海拔高度時，您有三種選項可供選擇：
- 地形：將錨點放置在指定經緯度的地面上。地面高度由視覺定位系統在執行階段決定。如果您是第一次使用 ARCore 的地理空間 API，建議選擇「地形」，因為錨點可直接在地面上直接解析，且垂直準確率很高。「海拔高度偏移」欄位可讓您將錨點置於地面上或低於地面的固定量 (以公尺為單位)。舉例來說，指定「1.0」的偏移值會導致錨點在地形上方「浮動」一公尺。
- Rooftop 將錨點相對於任何結構體頂端的指定經緯度，就像地形錨點一樣，「海拔高度偏移」欄位可讓您根據屋頂位置 (以公尺為單位) 將錨點向上或向下移動。
- WGS84 會根據 WGS84 座標系統，將錨點放置在特定的絕對高度 (以公尺為單位)。以這種方式放置物件可能需要經過一些試驗和錯誤，因為在 WSG84 中，高度為「0」時，不一定表示海平面，且可能與 GPS 的高度不符。此外，雖然轉譯的 3D 圖塊的經緯度相當準確，但如果嘗試將物件做為參考，將物件置於地面等級，可能會導致高度誤差最多數公尺。
如要進一步瞭解不同類型的 ARCore 地理空間錨點，請參閱「地理空間開發人員指南」。
地形和屋頂錨點都有「WGS84 海拔高度」欄位。這個值僅用於編輯器模式，以在場景檢視畫面中設定物件的高度。地形和屋頂高度只會在執行階段決定，因此「WGS84 Altitude」欄位可讓您在開發應用程式時以視覺化方式呈現錨點。在執行階段，系統會忽略地形和頂樓錨點的 WGS84 Altitude 欄位。
新增幾何圖形至錨點
如果您現在建構並執行應用程式，啟用 AR 的應用程式時不會看到錨定標記。這是因為應用程式未附加任何幾何圖形。讓我們在錨點加入簡易的 3D 原始物件：在場景階層中，在 AR 地理空間創作者錨定物件上按一下滑鼠右鍵。在內容選單中選擇「3D 物件」>「Cube」。場景檢視畫面中會顯示灰色方塊，用來當做錨定標記的子項。如果您決定在編輯器中移動物件的位置或旋轉，建議您移動根 Anchor 物件，而非子項 Cube 原始物件。這有助於減少從經緯度到遊戲座標的轉譯錯誤。
當然，您也可以在錨點中加入更複雜的幾何圖形、任意元件和子項。
建構並執行應用程式
快在現實世界中查看你的錨點！請嘗試建構並執行應用程式，然後移至您希望看到方塊的位置。那裡嗎？ 恭喜，您已準備好使用地理空間創作者功能建構更複雜的 AR 體驗！
如有任何問題，請參閱疑難排解指南。
現在是新增其他幾何圖形的 AR 地理空間創作者錨定標記的絕佳時機。請嘗試使用多個屋頂和地形錨點及其偏移值。新增指令碼，為物件建立動畫或啟用互動功能。
瞭解地理空間建立者錨點和 ARGeospatialAnchor 類別
建構複雜且互動式的 AR 體驗時，建議您先瞭解地理空間建立者錨點與 ARCore 的 ARGeospatialAnchor C# 類別之間的關係：
只能在執行階段透過在 ARAnchorManager 叫用其中一個函式的方式建立 ARGeospatialAnchor，而且只能在 AR 工作階段穩定後建立。地理空間創作者錨定標記可視為場景中的預留位置，等待 AR 工作階段準備好解析 ARGeospatialAnchor 物件。工作階段準備就緒後，預留位置會自動呼叫 ARAnchorManager 來建立並解析 ARGeospatialAnchor。
執行階段錨點解析後，場景階層中的地理空間建立者錨定標記會立即附加為新 GameObject 的子項。這表示地理空間創作者錨點的所有元件或子項都會成為新 ARGeospatialAnchor GameObject 的子元件或子元件。舉例來說，附加至地理空間創作者錨定標記的幾何圖形原始 transform 會沿用 ARGeospatialAnchor 的 transform，因此會放在執行階段 AR 工作階段中預期的位置。
如果您需要在執行階段識別特定 ARGeospatialAnchor GameObjects，可以搜尋物件 name 屬性與使用地理空間建立者建立的錨點相符的物件。如果 AR 工作階段初始化，該物件的 parent 將是對應的 ARGeospatialAnchor 物件。
疑難排解
為什麼我的錨點會移動？
您可能會注意到，尤其在應用程式首次啟動時，錨點可能會出現緩慢的「偏移」，甚至突然跳躍數公尺。當 VPS 工作階段仍在判斷及修正相機的精確位置時，就會發生此情況。隨著水平和垂直的精確度在多幅頁框上有所提升，錨點會在更準確的位置重新繪製，就產生移動的錯覺。您可能希望以不同方式 (或完全不呈現) 物件，直到位置精確度達到特定門檻為止。如要這麼做，您可以查詢 ARCoreEarthManager.CameraGeospatialPose 屬性，判斷目前影格更新的準確率。
為什麼我的錨點出現在錯誤的高度？
在地理空間建立者錨點使用「手動」高度類型時，系統會根據 WGS84 設定錨點的高度 (以公尺為單位)。Google 的影像定位系統 (VPS) 回報的地圖圖塊與實際地面高度之間可能會有最多數公尺，如果地理空間錨定標記在執行階段的位置似乎有誤，建議您使用偵錯重疊圖像親自驗證 VPS 高度。接著，您可以在 Unity 編輯器中變更高度，使其符合該位置的已知 VPS 高度。
在編輯器的場景檢視畫面中，地圖圖塊無法正確算繪
如果 Cesium3DTileset 似乎會載入圖塊，但這些圖塊在場景檢視畫面中的固體洋紅色套件中呈現，請在專案中新增 Unity 的著色器圖形套件。Cesium 需要這個套件，但使用 Unity 內建轉譯器的專案預設不包含這個套件。
如要新增著色器圖表，請開啟 Unity 套件管理員 (「Window」>「Package Manager」)。請在「Package Manager」視窗頂端的下拉式選單中選取「Packages: Unity Registry」，確保瀏覽 Unity Package Registry 中可用的套件。搜尋 com.unity.shadergraph 套件並安裝最新版本。套件載入後，3D 圖塊應會在場景檢視畫面中重新載入並正確轉譯。
應用程式會在執行階段顯示黑色畫面，而非相機檢視畫面
根據預設，Unity 的通用算繪管道 (URP) 未設定為 AR 相機。如果您在執行階段看到畫面是黑色畫面，而非相機輸出內容，就必須將 AR Background Renderer Feature 新增至場景中的每個 URP 轉譯器。
如要新增地圖項目，請在專案中搜尋「Renderer」。針對每個 URP 轉譯器物件，按一下檢查器中的「Add Renderer Feature」按鈕，然後新增 AR 背景轉譯器。
為什麼與原始位置距離較遠的錨點位置沒有錯誤？
從 WGS84 座標轉換成 Unity 遊戲座標時，會因為浮點計算精確度而發生錯誤，只要確保起點在 AR 錨點附近，就能最小化。如果距離超過 20 公里，可能會導致不準確。如果 AR 體驗橫跨長距離，建議您在每個場景中使用多個場景，並在當中設定不重複的錨點。