Unreal での Azure Spatial AnchorsAzure Spatial Anchors in Unreal

概要Overview

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.

重要

ローカル アンカーはデバイスに格納されますが、Azure 空間アンカーはクラウドに格納されます。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:

  • Spatial Anchors リソースを作成し、次に示すアカウント フィールドをコピーします。Create a spatial anchors resource and copy the account fields listed below. これらの値は、アプリケーションのアカウントでユーザーを認証するために使用されます。These values are used to authenticate users with your application's account:
    • アカウント IDAccount 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

Azure Spatial Anchors プラグインを、次のようにして、Unreal エディターで有効にします。Enable the Azure Spatial Anchors plugins in the Unreal editor by:

  1. [編集] > [プラグイン] の順にクリックし、AzureSpatialAnchorsAzureSpatialAnchorsForWMR を検索します。Clicking 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.

Spatial Anchors プラグイン

完了したら、プラグインの変更を有効にするために、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.

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 空間アンカーの作成、永続化、共有には、Azure Spatial Anchors セッションを作成して開始する必要があります。You'll need to create and start an Azure Spatial Anchors session to create, persist, and share Azure Spatial Anchors:

  1. アプリケーションで使用しているポーンのブループリントを開きます。Open the blueprint for the Pawn you're using in the application.
  2. [アカウント ID][アカウント キー] 用に 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.

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. Start Azure Spatial Anchors Session カスタム イベントを追加し、次のスクリーンショットに示すように構成します。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 the developer to configure the session for authentication with the Azure Spatial Anchors service.

Spatial Anchors プラグイン

  1. Azure Spatial Anchors セッションを構成して、 [アカウント ID][アカウント キー] を指定します。Configure the Azure Spatial Anchors session to provide the Account ID and Account Key.

Spatial Anchors プラグイン

  1. Azure Spatial Anchors セッションを開始し、アプリケーションで Azure 空間アンカーを作成して配置できるようにします。Start the Azure Spatial Anchors session, allowing the application to create and locate Azure Spatial Anchors.

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.

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.

Spatial Anchors プラグイン

イベント グラフ ブループリントは、次のスクリーンショットのようになります。Your Event Graph blueprint should look like the screenshot below:

Spatial Anchors プラグイン

アンカーを作成するCreating an anchor

Azure 空間アンカーは、拡張現実アプリケーション空間における現実世界のポーズを表します。これにより、拡張現実コンテンツが現実世界の場所に固定されます。An Azure Spatial Anchor represents a physical world pose in the augmented reality application space, which locks augmented reality content to locations in the physical world. Azure 空間アンカーは、異なるユーザー間で共有することもできます。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 空間アンカーを作成するには:To create a new Azure Spatial Anchor:

  1. Azure Spatial Anchors セッションが実行されていることを確認します。Check that an Azure Spatial Anchors session is running. Azure Spatial Anchors セッションが 1 つも実行されていない場合、アプリケーションは Azure 空間アンカーの作成や永続化を行えません。The application can't create or persist an Azure Spatial Anchor when no Azure Spatial Anchors session is running.

Spatial Anchors プラグイン

  1. Unreal Scene コンポーネント を作成または取得します。これは、場所が永続化されている必要があります。Create or obtain an Unreal Scene Component that should have its location persisted.
    • 次の図では、Scene Component Needing Anchor コンポーネントが変数として使用されています。In the below image, the Scene Component Needing Anchor component is used as a variable. Unreal Scene コンポーネントは、AR ピンと Azure 空間アンカーのためのアプリケーション ワールド変換を確立するために必要です。An Unreal Scene Component is needed to establish an application world transform for an AR Pin and Azure Spatial Anchor.

Spatial Anchors プラグイン

Unreal Scene コンポーネント用の Azure 空間アンカーを構築して保存するには:To construct and save an Azure Spatial Anchor for an Unreal Scene Component:

  1. Unreal Scene コンポーネントの Pin コンポーネントを呼び出し、Scene コンポーネントの World Transform を AR ピンで使用するワールド トランスフォームとして指定します。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 ピンを使用してアプリケーション空間内の AR ポイントを追跡します。これは、Azure 空間アンカーを作成するために使用されます。Unreal tracks AR points in the application space using AR Pins, which are used to create an Azure Spatial Anchor. Unreal では、AR ピンは HoloLens の SpatialAnchor に似ています。In Unreal, an AR Pin is analogous to a SpatialAnchor on HoloLens.

Spatial Anchors プラグイン

  1. 新しく作成した AR ピンを使用して、Create Cloud Anchor を呼び出します。Call Create Cloud Anchor using the newly created AR Pin.
    • Create Cloud Anchor では、Azure Spatial Anchors サービス内ではなく、ローカルに Azure 空間アンカーが作成されます。Create Cloud Anchor creates an Azure Spatial Anchor locally but not in the Azure Spatial Anchor service. Azure 空間アンカーの有効期限などのパラメーターは、サービスを使用して Azure 空間アンカーを作成する前に設定できます。Parameters for the Azure Spatial Anchor, such as an expiration date, can be set before creating the Azure Spatial Anchor with the service.

Spatial Anchors プラグイン

  1. Azure 空間アンカーの有効期限を設定します。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.
    • たとえば、有効期限を 1 週間とする場合、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.

Spatial Anchors プラグイン

アンカーのパラメーターを設定したら、アンカーの保存準備ができたことを宣言します。After setting anchor parameters, declare the anchor as ready to save. 次の例では、新しく作成した Azure 空間アンカーが、保存が必要な一連の Azure 空間アンカーに追加されています。In the example below, the newly created Azure Spatial Anchor is added to a set of Azure Spatial Anchors needing saving. このセットは、ポーン ブループリントの変数として宣言されています。This set is declared as a variable for the Pawn blueprint.

Spatial Anchors プラグイン

アンカーを保存するSaving an Anchor

パラメーターを指定して Azure 空間アンカーを構成したら、Save Cloud Anchor を呼び出します。After configuring the Azure Spatial Anchor with your parameters, call Save Cloud Anchor. Save Cloud Anchor では、Azure Spatial Anchors サービスにそのアンカーが宣言されます。Save Cloud Anchor declares the anchor to the Azure Spatial Anchors service. Save Cloud Anchor への呼び出しが成功すると、Azure 空間アンカーは、その 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.

Spatial Anchors プラグイン

注意

Save Cloud Anchor は非同期関数で、EventTick などのゲーム スレッド イベントでのみ呼び出すことができます。Save Cloud Anchor is an asynchronous function and can only be called on a game thread event such as EventTick. Save Cloud Anchor は、カスタムのブループリント関数では、使用可能なブループリント関数として表示されない場合があります。Save Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. ただし、ポーン イベント グラフ ブループリント エディターでは使用できます。However, it should be available in the Pawn Event Graph blueprint editor.

次の例では、Azure 空間アンカーは入力イベント コールバック中にセットに保存されます。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 空間アンカーの保存を複数回試行することが必要になる場合があります。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, re-add it to the set of anchors still needing to be saved. 将来的には、アンカーが Azure Spatial Anchors サービスに正常に保存されるまで、EventTick によってアンカーの保存が試みられるようになる予定です。Future EventTicks will try to save the anchor until it's successfully stored in the Azure Spatial Anchor service.

Spatial Anchors プラグイン

アンカーが保存されると、その AR ピンの変換を、アプリケーションにコンテンツを配置するための参照変換として使用できるようになります。Once the anchor saves, you can use the AR Pins' transform as a reference transform for placing content in the application. 他のユーザーは、このアンカーを検出し、現実世界のさまざまなデバイス向けに AR コンテンツを配置できます。Other users can detect this anchor and align AR content for different devices in the physical world.

アンカーを削除するDeleting an Anchor

Delete Cloud Anchor を呼び出して、Azure Spatial Anchors サービスからアンカーを削除できます。You can delete anchors from the Azure Spatial Anchor service by calling Delete Cloud Anchor.

Spatial Anchors プラグイン

注意

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 は、カスタムのブループリント関数では、使用可能なブループリント関数として表示されない場合があります。Delete Cloud Anchor may not appear as an available blueprint function in custom blueprint Functions. ただし、ポーン イベント グラフ ブループリント エディターでは使用できます。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 空間アンカーを削除のフラグが設定されているアンカーのセットに追加し、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:

Spatial Anchors プラグイン

既存のアンカーを検索するLocating pre-existing anchors

Azure 空間アンカーを作成するだけでなく、仲間が Azure Spatial Anchors サービスを使って作成したアンカーを検出することもできます。In addition to creating Azure Spatial Anchors, you can detect anchors created by peers with the Azure Spatial Anchors service:

  1. 検出したいアンカーの Azure 空間アンカー識別子を取得します。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.

Spatial Anchors プラグイン

  1. AzureSpatialAnchorsEvent コンポーネントをポーン ブループリントに追加します。Add an AzureSpatialAnchorsEvent component to your Pawn blueprint.
    • このコンポーネントを使用すると、Azure 空間アンカーが検索されるときに呼び出されるイベントなど、さまざまな 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.

Spatial Anchors プラグイン

  1. AzureSpatialAnchorsEvent コンポーネントの ASAAnchor Located Delegate をサブスクライブします。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 空間アンカーには、既定で AR ピンが作成されません。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 空間アンカーの AR ピンを作成するため、開発者は Create ARPin Around Azure Cloud Spatial Anchor を呼び出すことができます。To create an AR Pin for the detected Azure Spatial Anchor, developers can call Create ARPin Around Azure Cloud Spatial Anchor.

Spatial Anchors プラグイン

仲間が Azure Spatial Anchors サービスを使用して作成した Azure 空間アンカーを検索するには、そのアプリケーションで Azure Spatial Anchors Watcher を作成する必要があります。In order 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. AzureSpatialAnchorsLocateCriteria を作成します。Create an AzureSpatialAnchorsLocateCriteria.
    • ユーザーからの距離や別のアンカーからの距離など、さまざまな位置パラメーターを指定できます。You can specify various location parameters like distance from the user or distance from another anchor.
  3. AzureSpatialAnchorsLocateCritieria で、目的の Azure 空間アンカー識別子を宣言します。Declare your desired Azure Spatial Anchor identifier in the AzureSpatialAnchorsLocateCritieria.
  4. Create Watcher を呼び出します。Call Create Watcher.

Spatial Anchors プラグイン

これで、アプリケーションで、Azure Spatial Anchors サービスに認識されている Azure 空間アンカーの検索が開始されます。この結果、ユーザーは仲間が作成した Azure 空間アンカーを見つけることができるようになります。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 空間アンカーを見つけたら、Stop Watcher を呼び出して Azure Spatial Anchors Watcher を停止し、監視リソースをクリーンアップします。After locating the Azure Spatial Anchor, call Stop Watcher to stop the Azure Spatial Anchors Watcher and clean up watcher resources.

Spatial Anchors プラグイン

最終的なイベント グラフ ブループリントは、次のスクリーンショットのようになります。Your final Event Graph blueprint should now look like the screenshot below:

Spatial Anchors プラグイン

次の開発チェックポイントNext Development Checkpoint

私たちが用意した Unreal 開発チェックポイント体験に従っている場合、読者は MRTK コア構成要素を探索している段階にいます。If you're following the Unreal development checkpoint journey we've laid out, you're in the midst of exploring the MRTK core building blocks. ここから、次の構成要素に進むことができます。From here, you can proceed to the next building block:

または、Mixed Reality プラットフォームの機能と 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