Unreal 中的 Azure Spatial AnchorsAzure Spatial Anchors in Unreal

Azure Spatial Anchors 是 Microsoft Mixed Reality 服務,可讓擴增實境裝置探索、共用及保存實體世界中的錨點。Azure Spatial Anchors is a Microsoft Mixed Reality service, allowing augmented reality devices to discover, share, and persist anchor points in the physical world. 以下文件提供將 Azure Spatial Anchors 服務整合到 Unreal 專案中的指示。Documentation below provides instructions for integrating the Azure Spatial Anchors service into an Unreal project. 如果您要尋找更多資訊,請參閱 Azure Spatial Anchors 服務If you're looking for more information, check out the Azure Spatial Anchors service.

注意

如果您以 iOS 或 Android 作為目標,則 Unreal Engine 4.26 現在有適用於 ARKit 和 ARCore 支援的外掛程式。Unreal Engine 4.26 now has plugins for ARKit and ARCore support if you're targeting iOS or Android.

重要

本機錨點會儲存在裝置上,而 Azure Spatial Anchors 會儲存在雲端。Local anchors are stored on device, while Azure Spatial Anchors are stored in the cloud. 如果您要將錨點儲存在裝置本機上,我們有本機空間錨點文件,可協助您逐步完成此程序。If you're looking to store your anchors locally on a device, we have a Local Spatial Anchors document that can walk you through the process. 請注意,您在同一個專案中可以有本機和 Azure 錨點,而不會發生衝突。Note that you can have local and Azure anchors in the same project without conflict.

必要條件Prerequisites

若要完成本指南,請確定您:To complete this guide, make sure you have:

取得 Azure Spatial Anchors 帳戶資訊Getting Azure Spatial Anchors account info

在您的專案中使用 Azure Spatial Anchors 之前,您必須:Before using Azure Spatial Anchors in your project, you need to:

  • 建立空間錨點資源並複製下列帳戶欄位。Create a spatial anchors resource and copy the account fields listed below. 這些值用來向您的應用程式帳戶驗證使用者:These values are used to authenticate users with your application's account:
    • 帳戶識別碼Account ID
    • 帳戶金鑰Account Key

如需詳細資訊,請參閱 Azure Spatial Anchors 驗證文件。Check out the Azure Spatial Anchors authentication docs for more information.

注意

Unreal 4.25 中的 Azure Spatial Anchors 不支援 Azure AD 驗證權杖,但這項功能的支援將會在後續版本中推出。Azure Spatial Anchors in Unreal 4.25 does not support Azure AD authentication tokens, but support for this functionality will be coming in a later release.

新增 Azure Spatial Anchors 外掛程式Adding Azure Spatial Anchors plugins

在 Unreal 編輯器中啟用 Azure Spatial Anchors 外掛程式,方法如下:Enable the Azure Spatial Anchors plugins in the Unreal editor by:

  1. 按一下 [編輯] > [外掛程式] 並搜尋 AzureSpatialAnchorsAzureSpatialAnchorsForWMRClicking Edit > Plugins and searching for AzureSpatialAnchors and AzureSpatialAnchorsForWMR.
  2. 在兩個外掛程式中選取 [已啟用] 核取方塊,以允許存取您應用程式中的 Azure Spatial Anchors 藍圖程式庫。Select the Enabled checkbox in both plugins to allow access to the Azure Spatial Anchors blueprint libraries in your application.

Unreal 編輯器中的空間錨點外掛程式的螢幕擷取畫面

完成後,請重新啟動 Unreal 編輯器,讓外掛程式變更生效。Once that's done, restart the Unreal Editor for the plugin changes to take effect. 專案現在已準備好使用 Azure Spatial Anchors。The project is now ready to use Azure Spatial Anchors.

啟動空間錨點工作階段Starting a Spatial Anchors session

Azure Spatial Anchors 工作階段可讓用戶端應用程式與 Azure Spatial Anchors 服務進行通訊。An Azure Spatial Anchors session allows client applications to communicate with the Azure Spatial Anchors service. 您必須建立並啟動 Azure Spatial Anchors 工作階段,才能建立、保存和共用 Azure Spatial Anchors:You'll need to create and start an Azure Spatial Anchors session to create, persist, and share Azure Spatial Anchors:

  1. 針對您在應用程式中使用的 Pawn 開啟藍圖。Open the blueprint for the Pawn you're using in the application.
  2. 為 [帳戶識別碼] 和 [帳戶金鑰] 新增兩個字串變數,然後從您的 Azure Spatial Anchors 帳戶指派對應的值,以驗證工作階段。Add two string variables for the Account ID and Account Key, then assign the corresponding values from your Azure Spatial Anchors account to authenticate the session.

詳細資料面板的螢幕擷取畫面,其中已醒目提示 Azure Spatial Anchors 帳戶識別碼、金鑰和變數類型

啟動 Azure Spatial Anchors 工作階段,方法如下:Start an Azure Spatial Anchors session by:

  1. 檢查 [AR 工作階段] 是否正在 HoloLens 應用程式中執行,因為直到 AR 工作階段執行,才能啟動 Azure Spatial Anchors 工作階段。Checking that an AR Session is running in the HoloLens application, as the Azure Spatial Anchors session can't start until an AR Session is running. 如果您尚未設定工作階段,請建立 AR 工作階段資產If you don't have one setup, create an AR Session asset.
  2. 新增 [啟動 Azure Spatial Anchors 工作階段] 自訂事件並加以設定,如下列螢幕擷取畫面所示。Adding the Start Azure Spatial Anchors Session custom event and configure it as shown in the screenshot below.
    • 建立工作階段時,依預設不會啟動工作階段,這可讓您使用 Azure Spatial Anchors 服務設定工作階段以進行驗證。Creating a session doesn't start the session by default, which allows you to configure the session for authentication with the Azure Spatial Anchors service.

開始 Azure Spatial Anchors 工作階段自訂事件的藍圖

  1. 設定 Azure Spatial Anchors 工作階段,以提供 [帳戶識別碼] 和 [帳戶金鑰]。Configure the Azure Spatial Anchors session to provide the Account ID and Account Key.

已新增帳戶識別碼和金鑰的設定工作階段函式的藍圖

  1. 啟動 Azure Spatial Anchors 工作階段,讓應用程式能夠建立及尋找 Azure Spatial Anchors。Start the Azure Spatial Anchors session, allowing the application to create and locate Azure Spatial Anchors.

Azure Spatial Anchors 工作階段啟動函式的藍圖

當您不再使用該服務時,在事件圖形藍圖中清除 Azure Spatial Anchors 資源是很好的作法:It's good practice to clean up Azure Spatial Anchors resources in your Event Graph blueprint when you're no longer using the service:

  1. 停止 Azure Spatial Anchors 工作階段。Stop the Azure Spatial Anchors session. 工作階段將不再執行,但其相關聯的資源仍會存在於 Azure Spatial Anchors 外掛程式中。The session will no longer be running, but its associated resources will still exist in the Azure Spatial Anchors plugin.

停止 Azure Spatial Anchors 工作階段自訂事件和停止工作階段函式的藍圖

  1. 終結 Azure Spatial Anchors 工作階段,以清除 Azure Spatial Anchors 外掛程式仍知道的任何 Azure Spatial Anchors 工作階段資源。Destroy the Azure Spatial Anchors session to clean up any Azure Spatial Anchors session resources still known to the Azure Spatial Anchors plugin.

終結工作階段函式的藍圖

您的事件圖形藍圖看起來應該類似下列螢幕擷取畫面:Your Event Graph blueprint should look like the screenshot below:

Azure Spatial Anchors 工作階段設定的完整事件圖形的藍圖

建立錨點Creating an anchor

Azure Spatial Anchors 代表擴增實境應用程式空間中的實體世界姿態,會將擴增實境內容連結至實體位置。An Azure Spatial Anchor represents a physical world pose in the augmented reality application space, which locks augmented reality content to physical locations. Azure Spatial Anchors 也可以在不同的使用者間共用。Azure Spatial Anchors can also be shared among different users. 此共用可讓在不同裝置上繪製的擴增實境內容放置於實體世界中的相同位置。This sharing allows augmented reality content drawn on different devices to be positioned in the same location in the physical world.

若要建立新的 Azure Spatial Anchors:To create a new Azure Spatial Anchor:

  1. 檢查 Azure Spatial Anchors 工作階段是否正在執行。Check that an Azure Spatial Anchors session is running. 若沒有任何正在執行的 Azure Spatial Anchors 工作階段,應用程式就無法建立或保存 Azure Spatial Anchors。The application can't create or persist an Azure Spatial Anchor when no Azure Spatial Anchors session is running.

建立 Azure Spatial Anchors 自訂事件的藍圖

  1. 建立或取得應保存其位置的 Unreal 場景元件Create or obtain an Unreal Scene Component that should have its location persisted.
    • 在下圖中,[需要錨點的場景元件] 元件會當作變數使用。In the below image, the Scene Component Needing Anchor component is used as a variable. 需要 Unreal 場景元件才能建立 AR Pin 和 Azure Spatial Anchors 的應用程式世界轉換。An Unreal Scene Component is needed to establish an application world transform for an AR Pin and Azure Spatial Anchor.

建立 Azure Spatial Anchors 自訂事件與場景元件的藍圖

若要為 Unreal 場景元件建構並儲存 Azure Spatial Anchors:To construct and save an Azure Spatial Anchor for an Unreal Scene Component:

  1. 針對 Unreal 場景元件呼叫 Pin 元件,並指定場景元件的 [世界轉換] 作為用於 AR Pin 的世界轉換。Call the Pin Component for the Unreal Scene Component and specify the Scene Component's World Transform as the World Transform used for the AR Pin.
    • Unreal 會使用 AR Pin 來追蹤應用程式空間中的 AR 點,其用來建立 Azure Spatial Anchors。Unreal tracks AR points in the application space using AR Pins, which are used to create an Azure Spatial Anchor. 在 Unreal 中,AR Pin 類似於 HoloLens 上的空間錨點。In Unreal, an AR Pin is analogous to a SpatialAnchor on HoloLens.

連線至釘選元件函式之場景元件的藍圖

  1. 使用新建立的 AR Pin 呼叫 [建立雲端錨點]。Call Create Cloud Anchor using the newly created AR Pin.
    • 「建立雲端錨點」會在本機建立 Azure Spatial Anchors,但不在 Azure Spatial Anchors 服務中。Create Cloud Anchor creates an Azure Spatial Anchor locally but not in the Azure Spatial Anchor service. 在透過服務建立 Azure Spatial Anchors 之前,可以設定 Azure Spatial Anchors 的參數 (例如到期日)。Parameters for the Azure Spatial Anchor, such as an expiration date, can be set before creating the Azure Spatial Anchor with the service.

釘選元件函式連線至會傳回 ARPin 的建立雲端錨點函式的藍圖

  1. 設定 Azure Spatial Anchors 到期。Set the Azure Spatial Anchor expiration. 此函式的 Lifetime 參數可讓開發人員以秒為單位指定服務應維護錨點的時間長度。This function's Lifetime parameter allows the developer to specify in seconds how long the anchor should be maintained by the service.
    • 例如,為期一週的到期日會採用 60秒 x 60 分鐘 x 24 小時 x 7 天 = 604,800 秒的值。For example, a week long expiration would take a value of 60 seconds x 60 minutes x 24 hours x seven days = 604,800 seconds.

雲端錨點連線至設定到期函式 (存留期值設定為 604,800 秒) 的藍圖

設定錨點參數之後,請將錨點宣告為準備好儲存。After setting anchor parameters, declare the anchor as ready to save. 在下列範例中,新建立的 Azure Spatial Anchors 會新增至需要儲存的一組 Azure Spatial Anchors。In the example below, the newly created Azure Spatial Anchor is added to a set of Azure Spatial Anchors needing saving. 此集合會宣告為 Pawn 藍圖的變數。This set is declared as a variable for the Pawn blueprint.

錨點已準備好要儲存在設定變數中的藍圖

儲存錨點Saving an Anchor

使用您的參數設定 Azure Spatial Anchors 之後,請呼叫 [儲存雲端錨點]。After configuring the Azure Spatial Anchor with your parameters, call Save Cloud Anchor. 「儲存雲端錨點」會對 Azure Spatial Anchors 服務宣告錨點。Save Cloud Anchor declares the anchor to the Azure Spatial Anchors service. 當「儲存雲端錨點」的呼叫成功時,Azure Spatial Anchors 可供 Azure Spatial Anchors 服務的其他使用者使用。When the call to Save Cloud Anchor succeeds, the Azure Spatial Anchor is available to other users of the Azure Spatial Anchor service.

呼叫的儲存雲端錨點函式的藍圖

注意

「儲存雲端錨點」是非同步函式,只能在遊戲執行緒事件 (例如 EventTick) 上呼叫。Save Cloud Anchor is an asynchronous function and can only be called on a game thread event such as EventTick. 「儲存雲端錨點」可能不會顯示為自訂藍圖函式中可用的藍圖函式。Save Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. 不過,其應可在 Pawn 事件圖形藍圖編輯器中使用。However, it should be available in the Pawn Event Graph blueprint editor.

在下列範例中,Azure Spatial Anchors 會在輸入事件回呼期間儲存在集合中。In the example below, the Azure Spatial Anchor is stored in a set during an input event callback. 然後錨點會儲存在 EventTick 上。The anchor is then saved on the EventTick. 視您的 Azure Spatial Anchors 工作階段所建立的空間資料量而定,儲存 Azure Spatial Anchors 可能會進行多次嘗試。Saving an Azure Spatial Anchor may take multiple attempts depending on the amount of spatial data that your Azure Spatial Anchors session has created. 這就是為何檢查儲存呼叫是否成功是個好主意。That's why it's a good idea to check whether the save call succeeded.

若未儲存錨點,請將其重新新增至仍需要儲存的錨點集合。If the anchor doesn't save, readd it to the set of anchors still needing to be saved. 未來的 EventTicks 會繼續嘗試儲存錨點,直到成功儲存為止。Future EventTicks will keep trying to save the anchor until it's successfully stored.

未儲存的錨點再次儲存到設定變數中的藍圖

儲存錨點後,AR Pin 的轉換可作為參考轉換,以便將內容放在您的應用程式中。Once the anchor saves, the AR Pins' transform acts as a reference transform for placing content in your app. 其他使用者可以偵測此錨點,並針對實體世界中的不同裝置對齊 AR 內容。Other users can detect this anchor and align AR content for different devices in the physical world.

刪除錨點Deleting an Anchor

您可藉由呼叫 [刪除雲端錨點],從 Azure Spatial Anchors 服務刪除錨點。You can delete anchors from the Azure Spatial Anchor service by calling Delete Cloud Anchor.

呼叫的刪除雲端錨點函式的藍圖

注意

「刪除雲端錨點」是潛伏的函式,只能在遊戲執行緒事件 (例如 EventTick) 上呼叫。Delete Cloud Anchor is a latent function and can only be called on a game thread event, such as EventTick. 「刪除雲端錨點」可能不會顯示為自訂藍圖函式中可用的藍圖函式。Delete Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. 不過,其應可在 Pawn 事件圖形藍圖編輯器中使用。It should however be available in the Pawn Event Graph blueprint editor.

在下列範例中,錨點會在自訂輸入事件上標示要刪除。In the example below, the anchor is flagged for deletion on a custom input event. 然後會在 EventTick 上嘗試刪除。The deletion is then attempted on the EventTick. 如果錨點刪除失敗,請將 Azure Spatial Anchors 新增至標示要刪除的錨點集合,然後在稍後的 EventTick 上再次嘗試。If the anchor deletion fails, add the Azure Spatial Anchor to the set of anchors flagged for deletion and tries again on later EventTicks.

您的事件圖形藍圖現在看起來應該類似下列螢幕擷取畫面:Your Event Graph blueprint should now look like the screenshot below:

用來處理雲端錨點的完整事件圖形的藍圖

尋找既有的錨點Locating pre-existing anchors

具有 Azure Spatial Anchors 服務的對等節點可以建立現有的錨點:Existing anchors can be created by peers with the Azure Spatial Anchors service:

  1. 針對您想要偵測的錨點,取得 Azure Spatial Anchors 識別碼。Obtain an Azure Spatial Anchor identifier for the anchor that you would like to detect.
    • 在先前的 Azure Spatial Anchors 工作階段中,可以為相同裝置所建立的錨點取得錨點識別碼。An anchor identifier can be obtained for an anchor created by the same device in a previous Azure Spatial Anchors session. 其也可透過與 Azure Spatial Anchors 服務互動的對等裝置來建立及共用。It can also be created and shared by peer devices interacting with the Azure Spatial Anchors service.

使用取得 Azure 雲端識別碼函式的儲存 Azure Spatial Anchors 識別碼自訂事件的藍圖

  1. AzureSpatialAnchorsEvent 元件新增至您的 Pawn 藍圖。Add an AzureSpatialAnchorsEvent component to your Pawn blueprint.
    • 此元件可讓您訂閱各種 Azure Spatial Anchors 事件,例如找到 Azure Spatial Anchors 時所呼叫的事件。This component allows you to subscribe to various Azure Spatial Anchors events, such as events called when Azure Spatial Anchors are located.

在藍圖編輯器中開啟 BP_Pawn,且已開啟元件和詳細資料面板的螢幕擷取畫面

  1. 針對 [AzureSpatialAnchorsEvent] 元件訂閱 [ASAAnchor 找出的委派]。Subscribe to the ASAAnchor Located Delegate for the AzureSpatialAnchorsEvent component.
    • 委派可讓應用程式知道何時找到與 Azure Spatial Anchors 帳戶相關聯的新錨點。The delegate lets the application know when new anchors associated with the Azure Spatial Anchors account have been located.
    • 透過事件回呼,使用 Azure Spatial Anchors 工作階段所建立對等節點的 Azure Spatial Anchors,預設不會建立 AR Pin。With the event callback, Azure Spatial Anchors created by peers using the Azure Spatial Anchors session won't have AR Pins created by default. 若要為偵測到的 Azure Spatial Anchors 建立 AR Pin,開發人員可以呼叫 [建立以 Azure Cloud Spatial Anchors 為主的 ARPin]。To create an AR Pin for the detected Azure Spatial Anchor, developers can call Create ARPin Around Azure Cloud Spatial Anchor.

開始播放事件連線至 ASAAnchor 找出的委派的藍圖

若要使用 Azure Spatial Anchors 服務找出對等節點所建立的 Azure Spatial Anchors,應用程式必須建立 [Azure Spatial Anchors 監看員]:To locate Azure Spatial Anchors created by peers using the Azure Spatial Anchor service, the application will have to create an Azure Spatial Anchors Watcher:

  1. 檢查 Azure Spatial Anchors 工作階段是否正在執行。Check that an Azure Spatial Anchors session is running.
  2. 建立 AzureSpatialAnchorsLocateCriteriaCreate an AzureSpatialAnchorsLocateCriteria.
    • 您可以指定各種位置參數,例如與使用者的距離或與另一個錨點的距離。You can specify various location parameters like distance from the user or distance from another anchor.
  3. AzureSpatialAnchorsLocateCritieria 中宣告您所尋找的 Azure Spatial Anchor 識別碼。Declare the Azure Spatial Anchor identifier you're looking for in the AzureSpatialAnchorsLocateCritieria.
  4. 呼叫 [建立監看員]。Call Create Watcher.

啟動 Azure Spatial Anchors 監看員自訂事件的藍圖

應用程式現在會開始尋找 Azure Spatial Anchors 服務已知的 Azure Spatial Anchors,這表示使用者可以找出其對等節點所建立的 Azure Spatial Anchors。The application now begins looking for Azure Spatial Anchors known to the Azure Spatial Anchors service, meaning that users can locate Azure Spatial Anchors created by their peers.

找出 Azure Spatial Anchor 之後,請呼叫 [停止監看員] 以停止 Azure Spatial Anchors 監看員並清除監看員資源。After locating the Azure Spatial Anchor, call Stop Watcher to stop the Azure Spatial Anchors Watcher and clean up watcher resources.

呼叫停止監看員函式的藍圖

您的最終事件圖形藍圖現在看起來應該類似下列螢幕擷取畫面:Your final Event Graph blueprint should now look like the screenshot below:

用來處理錨點委派事件的完整事件圖形的藍圖

下一個開發檢查點Next Development Checkpoint

依循我們配置的 Unreal 開發旅程,此時您會探索 MRTK核心建置組塊。If you're following the Unreal development journey we've laid out, you're in the midst of exploring the MRTK core building blocks. 接下來,您可以繼續進行下一個建置組塊:From here, you can continue to the next building block:

或者,直接跳到混合實境平台功能和 API 的主題:Or jump to Mixed Reality platform capabilities and APIs:

您可以隨時回到 Unreal 開發檢查點You can always go back to the Unreal development checkpoints at any time.

接下來的步驟Next steps