C++/WinRT で Azure Spatial Anchors を使用してアンカーを作成して配置する方法

  • [アーティクル]

Azure Spatial Anchors を使用して、世界中の異なるデバイス間でアンカーを共有できます。 これは複数の異なる開発環境をサポートしています。 この記事では、Azure Spatial Anchors SDK を C++/WinRT で使用する方法について説明します。次のことを行います。

  • Azure Spatial Anchors セッションを正しく設定して管理する。
  • ローカル アンカーのプロパティを作成して設定する。
  • それらをクラウドにアップロードする。
  • クラウドの空間アンカーを検索して削除する。

前提条件

このガイドを完了するには、次のことが必要です。

Cross Platform

セッションの初期化

SDK のメイン エントリ ポイントは、セッションを表すクラスです。 通常は、ビューとネイティブ AR セッションを管理するクラス内のフィールドを宣言します。

CloudSpatialAnchorSession クラスの詳細を確認してください。

    CloudSpatialAnchorSession m_cloudSession{ nullptr };

    m_cloudSession = CloudSpatialAnchorSession();

認証の設定

サービスにアクセスするには、アカウント キー、アクセス トークン、または Microsoft Entra 認証トークンを提供する必要があります。 この詳細については、認証の概念に関するページも参照してください。

アカウント キー

アカウント キーは、アプリケーションが Azure Spatial Anchors サービスで認証できるようにするための資格情報です。 アカウント キーの使用目的は、すぐに開始できるようにサポートすることです。 特にアプリケーションの Azure Spatial Anchors との統合の開発フェーズ時などがこれに該当します。 そのようなものとして、開発中にクライアント アプリケーションにアカウント キーを埋め込んで使用できます。 開発の先の段階に進むときには、本番稼働レベルであるか、アクセス トークンによりサポートされるか、または Microsoft Entra ユーザー認証である認証メカニズムに移行することが強く推奨されます。 開発のためにアカウント キーを取得するには、Azure Spatial Anchors アカウントにアクセスし、[キー] タブに移動します。

SessionConfiguration クラスの詳細を確認してください。

    auto configuration = m_cloudSession.Configuration();
    configuration.AccountKey(LR"(MyAccountKey)");

アクセス トークン

アクセス トークンは、Azure Spatial Anchors で認証するためのより堅牢な方法です。 特に運用環境デプロイメントのアプリケーションを準備するきにはそのように言えます。 このアプローチの概要は、クライアント アプリケーションが安全に認証できるバックエンド サービスを設定することです。 バック エンド サービスは、実行時に AAD と連動し、Azure Spatial Anchors の Secure Token Service と連動してアクセス トークンを要求します。 このトークンは、クライアント アプリケーションに配信され、SDK で Azure Spatial Anchors で認証するために使用されます。

    auto configuration = m_cloudSession.Configuration();
    configuration.AccessToken(LR"(MyAccessToken)");

アクセス トークンが設定されていない場合は、TokenRequired イベントを処理するか、デリゲート プロトコルに tokenRequired メソッドを実装する必要があります。

イベント引数のプロパティを設定することで、イベントを同期的に処理できます。

TokenRequiredDelegate デリゲートの詳細を確認してください。

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
        args.AccessToken(LR"(MyAccessToken)");
    });

ハンドラーで非同期操作を実行する必要がある場合は、次の例のように deferral オブジェクトを要求してこれを完了することによって、トークンの設定を延期することができます。

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
        auto deferral = args.GetDeferral();
        MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
            if (!myToken.empty()) args.AccessToken(myToken);
            deferral.Complete();
        });
    });

Microsoft Entra 認証

Azure Spatial Anchors を使うと、アプリケーションはユーザーの Microsoft Entra ID (Active Directory) トークンでも認証できるようになります。 たとえば、Microsoft Entra トークンを使って Azure Spatial Anchors と統合することができます。 企業が Microsoft Entra ID でユーザーを管理している場合は、Azure Spatial Anchors SDK でユーザーの Microsoft Entra トークンを提供できます。 これにより、同じ Microsoft Entra テナントの一部であるアカウントについて、Azure Spatial Anchors サービスに対して直接認証できるようになります。

    auto configuration = m_cloudSession.Configuration();
    configuration.AuthenticationToken(LR"(MyAuthenticationToken)");

アクセス トークンの場合と同様に、Microsoft Entra トークンが設定されていない場合は、TokenRequired イベントを処理するか、デリゲート プロトコルに tokenRequired メソッドを実装する必要があります。

イベント引数のプロパティを設定することで、イベントを同期的に処理できます。

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [](auto&&, auto&& args) {
        args.AuthenticationToken(LR"(MyAuthenticationToken)");
    });

ハンドラーで非同期操作を実行する必要がある場合は、次の例のように deferral オブジェクトを要求してこれを完了することによって、トークンの設定を延期することができます。

    m_accessTokenRequiredToken = m_cloudSession.TokenRequired(winrt::auto_revoke, [this](auto&&, auto&& args) {
        auto deferral = args.GetDeferral();
        MyGetTokenAsync([&deferral, &args](winrt::hstring const& myToken) {
            if (!myToken.empty()) args.AuthenticationToken(myToken);
            deferral.Complete();
        });
    });

セッションの設定

セッションにおいて環境データを処理できるようにするには、Start() を呼び出します。

セッションによって発生したイベントを処理するには、イベント ハンドラーをアタッチします。

Start メソッドの詳細を確認してください。

    m_cloudSession.Start();

セッションにフレームを提供する

空間アンカー セッションは、ユーザーの周りに空白をマップすることによって機能します。 そうすることで、アンカーの場所を決定しやすくなります。 モバイル プラットフォーム (iOS と Android) には、プラットフォームの AR ライブラリからフレームを取得するためにカメラ フィードへのネイティブ呼び出しが必要です。 これに対し、HoloLens は環境を継続的にスキャンするため、モバイル プラットフォームの場合と異なり特定の呼び出しは必要ありません。

ProcessFrame メソッドの詳細を確認してください。

    m_cloudSession->ProcessFrame(ar_frame_);

ユーザーへのフィードバックの提供

セッションが更新されるイベントを処理するために、コードを記述できます。 セッションによるユーザーの環境の理解が深まるたびに、このイベントが発生します。 これにより、次のことが可能になります。

  • UserFeedback クラスを使用して、デバイスが移動し、セッションで環境の把握状況が変わったら、ユーザーにフィードバックを提供する。 これを行うには、次の手順を実行します。
  • 空間アンカーを作成するのに十分な追跡済み空間データを確保できるのはどの時点かを判断する。 これは ReadyForCreateProgress または RecommendedForCreateProgress で判断します。 ReadyForCreateProgress が 1 を超えたら、クラウド空間アンカーを保存するのに十分なデータが得られています。ただし、RecommendedForCreateProgress が 1 を超えるまで待機することをお勧めします。

SessionUpdatedDelegate デリゲートの詳細を確認してください。

    m_sessionUpdatedToken = m_cloudSession.SessionUpdated(winrt::auto_revoke, [this](auto&&, auto&& args)
    {
        auto status = args.Status();
        if (status.UserFeedback() == SessionUserFeedback::None) return;
        m_feedback = LR"(Feedback: )" + FeedbackToString(status.UserFeedback()) + LR"( -)" +
            LR"( Recommend Create=)" + FormatPercent(status.RecommendedForCreateProgress() * 100.f);
    });

クラウド空間アンカーの作成

クラウド空間アンカーを作成するには、最初にプラットフォームの AR システムにアンカーを作成した後、対応するアンカーをクラウド上に作成します。 CreateAnchorAsync() メソッドを使用します。

CloudSpatialAnchor クラスの詳細を確認してください。

    // Initialization
    SpatialStationaryFrameOfReference m_stationaryReferenceFrame = nullptr;
    HolographicDisplay defaultHolographicDisplay = HolographicDisplay::GetDefault();
    SpatialLocator spatialLocator = defaultHolographicDisplay.SpatialLocator();
    m_stationaryReferenceFrame = spatialLocator.CreateStationaryFrameOfReferenceAtCurrentLocation();

    // Create a local anchor, perhaps by positioning a SpatialAnchor a few meters in front of the user
    SpatialAnchor localAnchor{ nullptr };
    PerceptionTimestamp timestamp = PerceptionTimestampHelper::FromHistoricalTargetTime(DateTime::clock::now());
    SpatialCoordinateSystem currentCoordinateSystem = m_attachedReferenceFrame.GetStationaryCoordinateSystemAtTimestamp(timestamp);
    SpatialPointerPose pose = SpatialPointerPose::TryGetAtTimestamp(currentCoordinateSystem, timestamp);

    // Get the gaze direction relative to the given coordinate system.
    const float3 headPosition = pose.Head().Position();
    const float3 headDirection = pose.Head().ForwardDirection();

    // The anchor is positioned two meter(s) along the user's gaze direction.
    constexpr float distanceFromUser = 2.0f; // meters
    const float3 gazeAtTwoMeters = headPosition + (distanceFromUser * headDirection);

    localAnchor = SpatialAnchor::TryCreateRelativeTo(currentCoordinateSystem, gazeAtTwoMeters);

    // If the user is placing some application content in their environment,
    // you might show content at this anchor for a while, then save when
    // the user confirms placement.
    CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
    cloudAnchor.LocalAnchor(localAnchor);
    co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);
    m_feedback = LR"(Created a cloud anchor with ID=)" + cloudAnchor.Identifier();

前述のように、新しいクラウド空間アンカーの作成を試みる前に、十分な環境データが取得されている必要があります。 これは、ReadyForCreateProgress が 1 を超えている必要があることを意味しますが、Microsoft では RecommendedForCreateProgress が 1 を超えるまで待機することをお勧めします。

GetSessionStatusAsync メソッドの詳細を確認してください。

    SessionStatus status = co_await m_cloudSession.GetSessionStatusAsync();
    if (value.RecommendedForCreateProgress() < 1.0f) return;
    // Issue the creation request ...

プロパティの設定

クラウド空間アンカーを保存するときには、いくつかのプロパティを追加することを選択できます。 これは保存されるオブジェクトの型や、相互作用に対して有効にすべきかどうかなどの基本プロパティなどです。 そのようにすると検出時に役立つ場合があります。空のコンテンツの画像フレームなど、ユーザー向けのオブジェクトをすぐにレンダリングできます。 次に、バックグラウンドでの別のダウンロードにより、フレームに表示されるピクチャなどの、追加の状態の詳細が取得されます。

AppProperties メソッドの詳細を確認してください。

    CloudSpatialAnchor cloudAnchor = CloudSpatialAnchor();
    cloudAnchor.LocalAnchor(localAnchor);
    auto properties = m_cloudAnchor.AppProperties();
    properties.Insert(LR"(model-type)", LR"(frame)");
    properties.Insert(LR"(label)", LR"(my latest picture)");
    co_await m_cloudSession.CreateAnchorAsync(cloudAnchor);

プロパティを更新する

アンカーでプロパティを更新するには、UpdateAnchorProperties() メソッドを使用します。 2 つ以上のデバイスが同じアンカーのプロパティを同時に更新する場合は、オプティミスティック同時実行制御モデルを使用します。 これは、最初の書き込みが優先されることを意味します。 その他のすべての書き込みには、「同時実行」エラーが発生します。再試行する前に、プロパティの更新が必要になります。

UpdateAnchorPropertiesAsync メソッドの詳細を確認してください。

    CloudSpatialAnchor anchor = /* locate your anchor */;
    anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
    co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);

アンカーがサービス上で作成された後は、アンカーの位置を更新することはできません。新しい位置を追跡するには、新しいアンカーを作成し、古いアンカーを削除する必要があります。

プロパティを更新するためにアンカーを探知する必要がない場合は、CloudSpatialAnchor オブジェクトをプロパティと共に返す GetAnchorPropertiesAsync() メソッドを使用できます。

GetAnchorPropertiesAsync メソッドの詳細を確認してください。

    CloudSpatialAnchor anchor = co_await m_cloudSession.GetAnchorPropertiesAsync(LR"(anchorId)");
    if (anchor != nullptr)
    {
        anchor.AppProperties().Insert(LR"(last-user-access)", LR"(just now)");
        co_await m_cloudSession.UpdateAnchorPropertiesAsync(anchor);
    }

有効期限の設定

未来の特定の日付で有効期限が自動的に切れるようにアンカーを構成することもできます。 有効期限が切れたアンカーは、特定も更新もできなくなります。 有効期限を設定できるのはアンカーを作成しているときだけです。それをクラウドに保存する前に設定してください。 後で有効期限を更新することはできません。 アンカーの作成中に有効期限が設定されていない場合、アンカーは手動で削除されたときにのみ有効期限が切れます。

Expiration メソッドの詳細を確認してください。

    const int64_t oneWeekFromNowInHours = 7 * 24;
    const DateTime oneWeekFromNow = DateTime::clock::now() + std::chrono::hours(oneWeekFromNowInHours);
    cloudAnchor.Expiration(oneWeekFromNow);

クラウド空間アンカーを見つける

Azure Spatial Anchors を使用する主な理由の 1 つに、以前に保存したクラウド空間アンカーを検索できることが挙げられます。 このためには、"Watcher" を使用しています。 一度に使用できる Watcher は 1 つだけです。複数の Watcher はサポートされていません。 Watcher を使用してクラウド空間アンカーを見つける方法はいくつかあります (アンカー検索戦略とも呼ばれます)。 Watcher では一度に 1 つの方法を使用することができます。

  • ID でアンカーを検索します。
  • 以前検索したアンカーに接続されているアンカーを検索します。 アンカーの関係については、こちらをご覧ください。
  • 粗い再局在化を使用してアンカーを検索します。

注意

アンカーを配置するたびに、Azure Spatial Anchors は、収集された環境データを使用して、アンカーのビジュアル情報を増強しようとします。 アンカーを配置するのに問題がある場合は、アンカーを作成した後、さまざまな角度や照明条件から何度か配置してみるといいでしょう。

クラウド空間アンカーを識別子で検索する場合は、クラウド空間アンカー識別子をアプリケーションのバックエンド サービスに格納しておけば、それに対して適切に認証できるすべてのデバイスからアクセスできます。 この例のついては、「チュートリアル: デバイス間で空間アンカーを共有する」をご覧ください。

AnchorLocateCriteria オブジェクトをインスタンス化し、検索する識別子を設定します。次に AnchorLocateCriteria を指定することでセッション上の CreateWatcher メソッドを呼び出します。

CreateWatcher メソッドの詳細を確認してください。

    AnchorLocateCriteria criteria = AnchorLocateCriteria();
    criteria.Identifiers({ LR"(id1)", LR"(id2)", LR"(id3)" });
    auto cloudSpatialAnchorWatcher = m_cloudSession.CreateWatcher(criteria);

監視が作成された後、要求されたすべてのアンカーに対して AnchorLocated イベントが発生します。 このイベントは、アンカーが探知されたとき、またはアンカーを探知できなかった場合に発生します。 このような状況が発生した場合は、その理由が状態に示されます。 監視のすべてのアンカーが (探知されたかどうかを問わず) 処理された後、LocateAnchorsCompleted イベントが発生します。 識別子の上限は、Watcher 1 つあたり 35 個です。

AnchorLocatedDelegate デリゲートの詳細を確認してください。

    m_anchorLocatedToken = m_cloudSession.AnchorLocated(winrt::auto_revoke, [this](auto&&, auto&& args)
    {
        switch (args.Status())
        {
            case LocateAnchorStatus::Located:
            {
                CloudSpatialAnchor foundAnchor = args.Anchor();
            }
                break;
            case LocateAnchorStatus::AlreadyTracked:
                // This anchor has already been reported and is being tracked
                break;
            case LocateAnchorStatus::NotLocatedAnchorDoesNotExist:
                // The anchor was deleted or never existed in the first place
                // Drop it, or show UI to ask user to anchor the content anew
                break;
            case LocateAnchorStatus::NotLocated:
                // The anchor hasn't been found given the location data
                // The user might in the wrong location, or maybe more data will help
                // Show UI to tell user to keep looking around
                break;
        }
    });

アンカーの削除

使用されなくなったアンカーの削除は、開発のプロセスおよびプラクティスに早い段階で取り入れて、常時 Azure リソースをクリーンアップすることをお勧めします。

DeleteAnchorAsync メソッドの詳細を確認してください。

    co_await m_cloudSession.DeleteAnchorAsync(cloudAnchor);
    // Perform any processing you may want when delete finishes

セッションの一時停止、リセット、停止

セッションを一時的に停止するために、Stop() を呼び出すことができます。 そうすることで、ProcessFrame() を呼び出した場合でも、あらゆるウォッチャーや環境処理を停止できます。 次に Start() を呼び出して、処理を再開できます。 再開するとき、既にセッションでキャプチャされた環境データは保持されます。

Stop メソッドの詳細を確認してください。

    m_cloudSession.Stop();

セッションでキャプチャされた環境データをリセットするために、Reset() を呼び出すことができます。

Reset メソッドの詳細を確認してください。

    m_cloudSession.Reset();

セッションがすべての参照を解放した後に適切にクリーンアップするようにします。

    m_cloudSession = nullptr;

次のステップ

このガイドでは、Azure Spatial Anchors SDK を使用してアンカーを作成および探知する方法について学習しました。 アンカーのリレーションシップの詳細については、次のガイドに進んでください。

アンカーのリレーションシップ