Unreal 中的 Azure Spatial Anchors

Azure Spatial Anchors 是 Microsoft Mixed Reality 服務，可讓擴增實境裝置探索、共用及保存實體世界中的錨點。 以下文件提供將 Azure Spatial Anchors 服務整合到 Unreal 專案中的指示。 如果您要尋找更多資訊，請參閱 Azure Spatial Anchors 服務。

注意

如果您以 iOS 或 Android 作為目標，則 Unreal Engine 4.26 現在有適用於 ARKit 和 ARCore 支援的外掛程式。

重要

本機錨點會儲存在裝置上，而 Azure Spatial Anchors 會儲存在雲端。 如果您要將錨點儲存在裝置本機上，我們有本機空間錨點文件，可協助您逐步完成此程序。 請注意，您在同一個專案中可以有本機和 Azure 錨點，而不會發生衝突。

必要條件

若要完成本指南，請確定您：

• 已安裝 Microsoft OpenXR 外掛程式，可從 Unreal Marketplace 或 GitHub取得。
• 已安裝 Unreal 4.25 版或更新版本
• 在 Unreal 中設定了 HoloLens 2 專案
• 請參閱 Azure Spatial Anchors 概觀
• C++ 和 Unreal 的基本知識

取得 Azure Spatial Anchors 帳戶資訊

在您的專案中使用 Azure Spatial Anchors 之前，您必須：

• 建立空間錨點資源並複製下列帳戶欄位。 這些值用來向您的應用程式帳戶驗證使用者：
  • 帳戶識別碼
  • 帳戶金鑰

如需詳細資訊，請參閱 Azure Spatial Anchors 驗證文件。

注意

Unreal 4.25 中的 Azure Spatial Anchors 不支援 Azure AD 驗證權杖，但這項功能的支援將會在後續版本中推出。

啟用功能和許可權

HoloLens

開啟 [專案設定 > HoloLens ]，並啟用 網際網路用戶端 功能：

Android

若要讓 Android 應用程式顯示許可權對話方塊並允許位置功能，必須先呼叫 要求 Android 許可權 函式，才能嘗試啟動 Azure Spatial Anchor 會話：

建立輸入許可權的區域變數，並填入：

• android.permission.ACCESS_WIFI_STATE
• android.permission.CHANGE_WIFI_STATE
• android.permission.INTERNET
• android.permission.BLUETOOTH
• android.permission.BLUETOOTH_ADMIN
• android.permission.ACCESS_COARSE_LOCATION
• android.permission.ACCESS_FINE_LOCATION
• android.permission.CAMERA

最後，開啟[專案設定 > Android]，然後在 [進階 APK 封裝] 下的 [額外許可權] 欄位中設定相同的許可權：

iOS

若要建置 iOS 的應用程式，您必須在 Mac 上使用 Unreal。 若要使用 Apple 開發人員帳戶進行封裝，請開啟 [專案設定 > iOS ]，然後向下捲動至 [ 建 置] 區段。 啟用 [ 自動簽署 ] 核取方塊，並以您的 小組識別碼填入 IOS 小組 識別碼。

您可以登入 developer.apple.com，流覽至 [ 成員資格 ] 索引標籤並搜尋 [小組識別碼]，以尋找您的小組識別碼。

若要顯示許可權對話方塊並允許 iOS 裝置存取位置資訊，必須先呼叫Init 位置服務和啟動位置服務函式，才能嘗試啟動 Azure Spatial Anchor 會話：

新增 Azure Spatial Anchors 外掛程式

提示

使用適用于 Unreal 的 Azure Spatial Anchors 時，有 Azure Spatial Anchors 外掛程式和平臺特定外掛程式 (WMR、ARKit、ARCore、OpenXR) 。 您一次應該只啟用一個平臺特定外掛程式。

HoloLens

在 Unreal 編輯器中啟用 Azure Spatial Anchors 外掛程式，方法如下：

1. 按一下 [編輯 > 外掛程式 ]，然後搜尋 [Azure Spatial Anchors ] 和 [適用于 WMR 的 Azure Spatial Anchors]。
2. 在兩個外掛程式中選取 [已啟用] 核取方塊，以允許存取您應用程式中的 Azure Spatial Anchors 藍圖程式庫。

完成後，請重新啟動 Unreal 編輯器，讓外掛程式變更生效。 專案現在已準備好使用 Azure Spatial Anchors。

Android

在 Unreal 編輯器中啟用 Azure Spatial Anchors 外掛程式，方法如下：

1. 按一下 [編輯 > 外掛程式 ]，然後搜尋 Azure Spatial Anchors 和 Azure Spatial AnchorsFor ARCore。
2. 在兩個外掛程式中選取 [已啟用] 核取方塊，以允許存取您應用程式中的 Azure Spatial Anchors 藍圖程式庫。

完成後，請重新啟動 Unreal 編輯器，讓外掛程式變更生效。 專案現在已準備好使用 Azure Spatial Anchors。

iOS

在 Unreal 編輯器中啟用 Azure Spatial Anchors 外掛程式，方法如下：

1. 按一下 [編輯 > 外掛程式 ]，然後搜尋 Azure Spatial Anchors 和 Azure Spatial AnchorsFor ARKit。
2. 在兩個外掛程式中選取 [已啟用] 核取方塊，以允許存取您應用程式中的 Azure Spatial Anchors 藍圖程式庫。

3. 同時搜尋行動位置服務和行動位置服務 - IOS 實作
4. 選取這兩個外掛程式中的 [已啟用] 核取方塊，以允許 iOS 裝置存取目前的位置。

完成後，請重新啟動 Unreal 編輯器，讓外掛程式變更生效。 專案現在已準備好使用 Azure Spatial Anchors。

啟動空間錨點工作階段

Azure Spatial Anchors 工作階段可讓用戶端應用程式與 Azure Spatial Anchors 服務進行通訊。 您必須建立並啟動 Azure Spatial Anchors 工作階段，才能建立、保存和共用 Azure Spatial Anchors：

1. 針對您在應用程式中使用的 Pawn 開啟藍圖。
2. 為 [帳戶識別碼] 和 [帳戶金鑰] 新增兩個字串變數，然後從您的 Azure Spatial Anchors 帳戶指派對應的值，以驗證工作階段。

啟動 Azure Spatial Anchors 工作階段，方法如下：

1. 檢查 [AR 工作階段] 是否正在 HoloLens 應用程式中執行，因為直到 AR 工作階段執行，才能啟動 Azure Spatial Anchors 工作階段。 如果您尚未設定工作階段，請建立 AR 工作階段資產。
2. 新增 [啟動 Azure Spatial Anchors 工作階段] 自訂事件並加以設定，如下列螢幕擷取畫面所示。
   • 建立工作階段時，依預設不會啟動工作階段，這可讓您使用 Azure Spatial Anchors 服務設定工作階段以進行驗證。

3. 設定 Azure Spatial Anchors 會話，以提供 帳戶識別碼、 帳戶金鑰、 帳戶網域和 課程當地語系化設定。 所有核取方塊都應該在課程當地語系化設定中啟用，讓 Azure 空間錨點服務可以使用感應器資料來找出錨點。

4. 啟動 Azure Spatial Anchors 工作階段，讓應用程式能夠建立及尋找 Azure Spatial Anchors。

當您不再使用該服務時，在事件圖形藍圖中清除 Azure Spatial Anchors 資源是很好的作法：

1. 停止 Azure Spatial Anchors 工作階段。 工作階段將不再執行，但其相關聯的資源仍會存在於 Azure Spatial Anchors 外掛程式中。

2. 終結 Azure Spatial Anchors 工作階段，以清除 Azure Spatial Anchors 外掛程式仍知道的任何 Azure Spatial Anchors 工作階段資源。

您的事件圖形藍圖看起來應該類似下列螢幕擷取畫面：

建立錨點

Azure Spatial Anchors 代表擴增實境應用程式空間中的實體世界姿態，會將擴增實境內容連結至實體位置。 Azure Spatial Anchors 也可以在不同的使用者間共用。 此共用可讓在不同裝置上繪製的擴增實境內容放置於實體世界中的相同位置。

若要建立新的 Azure Spatial Anchors：

1. 檢查 Azure Spatial Anchors 工作階段是否正在執行。 若沒有任何正在執行的 Azure Spatial Anchors 工作階段，應用程式就無法建立或保存 Azure Spatial Anchors。

2. 建立或取得應保存其位置的 Unreal 場景元件 。
   • 在下圖中，[需要錨點的場景元件] 元件會當作變數使用。 需要 Unreal 場景元件才能建立 AR Pin 和 Azure Spatial Anchors 的應用程式世界轉換。

若要為 Unreal 場景元件建構並儲存 Azure Spatial Anchors：

1. 針對 Unreal 場景元件呼叫 Pin 元件，並指定場景元件的 [世界轉換] 作為用於 AR Pin 的世界轉換。
   • Unreal 會使用 AR Pin 來追蹤應用程式空間中的 AR 點，其用來建立 Azure Spatial Anchors。 在 Unreal 中，AR Pin 類似於 HoloLens 上的空間錨點。

2. 使用新建立的 AR Pin 呼叫 [建立雲端錨點]。
   • 「建立雲端錨點」會在本機建立 Azure Spatial Anchors，但不在 Azure Spatial Anchors 服務中。 在透過服務建立 Azure Spatial Anchors 之前，可以設定 Azure Spatial Anchors 的參數 (例如到期日)。

3. 設定 Azure Spatial Anchors 到期。 此函式的 Lifetime 參數可讓開發人員以秒為單位指定服務應維護錨點的時間長度。
   • 例如，為期一週的到期日會採用 60秒 x 60 分鐘 x 24 小時 x 7 天 = 604,800 秒的值。

設定錨點參數之後，請將錨點宣告為準備好儲存。 在下列範例中，新建立的 Azure Spatial Anchors 會新增至需要儲存的一組 Azure Spatial Anchors。 此集合會宣告為 Pawn 藍圖的變數。

儲存錨點

使用您的參數設定 Azure Spatial Anchors 之後，請呼叫 [儲存雲端錨點]。 「儲存雲端錨點」會對 Azure Spatial Anchors 服務宣告錨點。 當「儲存雲端錨點」的呼叫成功時，Azure Spatial Anchors 可供 Azure Spatial Anchors 服務的其他使用者使用。

注意

「儲存雲端錨點」是非同步函式，只能在遊戲執行緒事件 (例如 EventTick) 上呼叫。 「儲存雲端錨點」可能不會顯示為自訂藍圖函式中可用的藍圖函式。 不過，其應可在 Pawn 事件圖形藍圖編輯器中使用。

在下列範例中，Azure Spatial Anchors 會在輸入事件回呼期間儲存在集合中。 然後錨點會儲存在 EventTick 上。 視您的 Azure Spatial Anchors 工作階段所建立的空間資料量而定，儲存 Azure Spatial Anchors 可能會進行多次嘗試。 這就是為何檢查儲存呼叫是否成功是個好主意。

若未儲存錨點，請將其重新新增至仍需要儲存的錨點集合。 未來的 EventTicks 會繼續嘗試儲存錨點，直到成功儲存為止。

儲存錨點後，AR Pin 的轉換可作為參考轉換，以便將內容放在您的應用程式中。 其他使用者可以偵測此錨點，並針對實體世界中的不同裝置對齊 AR 內容。

刪除錨點

您可藉由呼叫 [刪除雲端錨點]，從 Azure Spatial Anchors 服務刪除錨點。

注意

「刪除雲端錨點」是潛伏的函式，只能在遊戲執行緒事件 (例如 EventTick) 上呼叫。 「刪除雲端錨點」可能不會顯示為自訂藍圖函式中可用的藍圖函式。 不過，其應可在 Pawn 事件圖形藍圖編輯器中使用。

在下列範例中，錨點會在自訂輸入事件上標示要刪除。 然後會在 EventTick 上嘗試刪除。 如果錨點刪除失敗，請將 Azure Spatial Anchors 新增至標示要刪除的錨點集合，然後在稍後的 EventTick 上再次嘗試。

您的事件圖形藍圖現在看起來應該類似下列螢幕擷取畫面：

尋找既有的錨點

具有 Azure Spatial Anchors 服務的對等節點可以建立現有的錨點：

1. 針對您想要偵測的錨點，取得 Azure Spatial Anchors 識別碼。
   • 在先前的 Azure Spatial Anchors 工作階段中，可以為相同裝置所建立的錨點取得錨點識別碼。 其也可透過與 Azure Spatial Anchors 服務互動的對等裝置來建立及共用。

2. 將 AzureSpatialAnchorsEvent 元件新增至您的 Pawn 藍圖。
   • 此元件可讓您訂閱各種 Azure Spatial Anchors 事件，例如找到 Azure Spatial Anchors 時所呼叫的事件。

3. 針對 [AzureSpatialAnchorsEvent] 元件訂閱 [ASAAnchor 找出的委派]。
   • 委派可讓應用程式知道何時找到與 Azure Spatial Anchors 帳戶相關聯的新錨點。
   • 透過事件回呼，使用 Azure Spatial Anchors 工作階段所建立對等節點的 Azure Spatial Anchors，預設不會建立 AR Pin。 若要為偵測到的 Azure Spatial Anchors 建立 AR Pin，開發人員可以呼叫 [建立以 Azure Cloud Spatial Anchors 為主的 ARPin]。

若要使用 Azure Spatial Anchors 服務找出對等節點所建立的 Azure Spatial Anchors，應用程式必須建立 [Azure Spatial Anchors 監看員]：

1. 檢查 Azure Spatial Anchors 工作階段是否正在執行。
2. 建立 AzureSpatialAnchorsLocateCriteria。
   • 您可以指定各種位置參數，例如與使用者的距離或與另一個錨點的距離。
3. 在 AzureSpatialAnchorsLocateCritieria 中宣告您所尋找的 Azure Spatial Anchor 識別碼。
4. 呼叫 [建立監看員]。

應用程式現在會開始尋找 Azure Spatial Anchors 服務已知的 Azure Spatial Anchors，這表示使用者可以找出其對等節點所建立的 Azure Spatial Anchors。

找出 Azure Spatial Anchor 之後，請呼叫 [停止監看員] 以停止 Azure Spatial Anchors 監看員並清除監看員資源。

您的最終事件圖形藍圖現在看起來應該類似下列螢幕擷取畫面：

下一個開發檢查點

依循我們配置的 Unreal 開發旅程，此時您會探索 MRTK核心建置組塊。 接下來，您可以繼續進行下一個建置組塊：

空間對應

或者，直接跳到混合實境平台功能和 API 的主題：

HoloLens 相機

您可以隨時回到 Unreal 開發檢查點。

接下來的步驟

• 本機空間錨點
• 空間錨點文件
• 空間錨點功能
• 有效的錨點體驗指導方針