本記事はAzure Spatial Anchorsの調査①の続きになります。
実際にAzure Spatial Anchorsのサービスを触りながら、技術検証を進めていくこととします。

検証環境

• Windows 10 Version 1909
• Unity 2021.1.4f1
• Visual Studio 2019
• デプロイ端末
  • HoloLens 2

Spatial Anchorsリソースを作成する（Azure Portal）[1]

1. Azure Portalの「リソースの作成」から「Spatial Anchors」を検索します。
   
2. リソース名等を入力し、「作成」をクリックします。
   
3. デプロイが完了したらリソースに移動し、下記の情報をテキストエディタにコピーしておきます。これらの情報は、Azure Spatial Anchors SDKを使用してAzureに接続する際に必要となります。
   • アカウント ID
     
   • アカウント ドメイン
     
   • プライマリ キー
     

Azure Spatial Anchors SDKのUnityプロジェクトへの導入手順 [2]

プロジェクトの要件

バージョン2.9以降のAzureSpatial Anchors SDKは、以下のパッケージを使用して、UnityXRプラグインフレームワークを使用してUnity2020.3（LTS）で構成する必要があります。

• AR Foundation: 4.0.12
• Windows XR Plugin (for HoloLens device support) : 4.4.1
• ARCore XR Plugin (for Android device support): 4.0.12
• ARKit XR Plugin (for iOS device support): 4.0.12

ASAパッケージのダウンロード

※Mixed Reality Feature Toolを使用することで簡単にUnityに導入できます。
それ以外の方法として、以下のような手順で導入が可能となります。

必要なパッケージをダウンロードするには、NPM がインストールされている必要があります。
以下のコマンドを実行します。 は、現在のフォルダーにダウンロードする Azure Spatial Anchors のバージョンに置き換えてください。

npm pack com.microsoft.azure.spatial-anchors-sdk.core@<version_number> --registry https://api.bintray.com/npm/microsoft/AzureMixedReality-NPM

※注意：入手できる Azure Spatial Anchors パッケージのバージョンを一覧表示するには、次のコマンドを実行します。

npm view com.microsoft.azure.spatial-anchors-sdk.core --registry https://api.bintray.com/npm/microsoft/AzureMixedReality-NPM versions

コマンドを実行したフォルダーに、Azure Spatial Anchors のコア パッケージがダウンロードされます。
プロジェクトでサポートするプラットフォーム (Android、iOS、HoloLens) ごとに、この手順を繰り返してパッケージをダウンロードします。

プラットフォーム	パッケージ名
Android	com.microsoft.azure.spatial-anchors-sdk.android@
iOS	com.microsoft.azure.spatial-anchors-sdk.ios@
HoloLens	com.microsoft.azure.spatial-anchors-sdk.windows@

ASA パッケージのインポート

ダウンロードした Azure Spatial Anchors パッケージ（.tgz）をUnity Package Manager の[Add package from tarball]から、 Unity プロジェクトにインポートします。詳しい手順はこちらをご覧ください。

上記の手順を実施することで、無事にASA SDKの導入ができることが確認できました。

Unity で Azure Spatial Anchors を使用してアンカーを作成して配置する方法 [3]

セッションの初期化

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

CloudSpatialAnchorSession cloudSession;
// In your view handler
this.cloudSession = new CloudSpatialAnchorSession();

認証の設定

サービスにアクセスするには、アカウント キー、アクセス トークン、または Azure Active Directory 認証トークンを提供する必要があります。 この詳細については、Azure Spatial Anchors に対する認証と承認に関するページも参照してください。

アカウントキーを使用するパターン

アカウント キーは、アプリケーションが Azure Spatial Anchors サービスで認証できるようにするための資格情報です。
アカウント キーの使用目的は、アプリケーションに Azure Spatial Anchorsを導入するといった開発フェーズ時にすぐに開始できるようにすることです。クライアント アプリケーションにアカウント キーを埋め込んで使用できます。 開発の先のフェーズに進むときには、実稼働レベルであるか、アクセス トークンによりサポートされるか、または Azure Active Directory ベースのユーザー認証である認証メカニズムに移行することが推奨されます。 開発のためにアカウント キーを取得するには、Azure Spatial Anchors アカウントにアクセスし、[キー] タブに移動します。
SessionConfigurationクラスの詳細を確認してください。

this.cloudSession.Configuration.AccountKey = @"MyAccountKey";

アクセストークンを使用するパターン

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

this.cloudSession.Configuration.AccessToken = @"MyAccessToken";

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

this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
{
    args.AccessToken = @"MyAccessToken";
};

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

this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
{
    var deferral = args.GetDeferral();
    string myToken = await MyGetTokenAsync();
    if (myToken != null) args.AccessToken = myToken;
    deferral.Complete();
};

Azure Active Directory認証トークンを使用するパターン

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

this.cloudSession.Configuration.AuthenticationToken = @"MyAuthenticationToken";

アクセス トークンの場合と同様、Azure AD トークンが設定されていない場合は、TokenRequired イベントを処理するか、デリゲート プロトコルに tokenRequired メソッドを実装する必要があります。
イベント引数のプロパティを設定することで、イベントを同期的に処理できます。

this.cloudSession.TokenRequired += (object sender, TokenRequiredEventArgs args) =>
{
    args.AuthenticationToken = @"MyAuthenticationToken";
};

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

this.cloudSession.TokenRequired += async (object sender, TokenRequiredEventArgs args) =>
{
    var deferral = args.GetDeferral();
    string myToken = await MyGetTokenAsync();
    if (myToken != null) args.AuthenticationToken = myToken;
    deferral.Complete();
};

セッションの設定

セッションにおいて環境データを処理できるようにするには、Start() を呼び出します。
セッションによって発生したイベントを処理するには、イベント ハンドラーをアタッチします。

#if UNITY_ANDROID || UNITY_IOS
    this.cloudSession.Session = aRSession.subsystem.nativePtr.GetPlatformPointer();
#elif UNITY_WSA || WINDOWS_UWP
    // No need to set a native session pointer for HoloLens.
#else
    throw new NotSupportedException("The platform is not supported.");
#endif
    this.cloudSession.Start();

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

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

#if UNITY_ANDROID || UNITY_IOS
XRCameraFrame xRCameraFrame;
if (aRCameraManager.subsystem.TryGetLatestFrame(cameraParams, out xRCameraFrame))
{
    long latestFrameTimeStamp = xRCameraFrame.timestampNs;

    bool newFrameToProcess = latestFrameTimeStamp > lastFrameProcessedTimeStamp;

    if (newFrameToProcess)
    {
        session.ProcessFrame(xRCameraFrame.nativePtr.GetPlatformPointer());
        lastFrameProcessedTimeStamp = latestFrameTimeStamp;
    }
}
#endif

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

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

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

this.cloudSession.SessionUpdated += (object sender, SessionUpdatedEventArgs args) =>
{
    var status = args.Status;
    if (status.UserFeedback == SessionUserFeedback.None) return;
    this.feedback = $"Feedback: {Enum.GetName(typeof(SessionUserFeedback), status.UserFeedback)} -" +
        $" Recommend Create={status.RecommendedForCreateProgress: 0.#%}";
};

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

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

    // Create a local anchor, perhaps by hit-testing and spawning an object within the scene
    Vector3 hitPosition = new Vector3();
#if UNITY_ANDROID || UNITY_IOS
    Vector2 screenCenter = new Vector2(0.5f, 0.5f);
    List<ARRaycastHit> aRRaycastHits = new List<ARRaycastHit>();
    if(arRaycastManager.Raycast(screenCenter, aRRaycastHits) && aRRaycastHits.Count > 0)
    {
        ARRaycastHit hit = aRRaycastHits[0];
        hitPosition = hit.pose.position;
    }
#elif WINDOWS_UWP || UNITY_WSA
    RaycastHit hit;
    if (this.TryGazeHitTest(out hit))
    {
        hitPosition = hit.point;
    }
#endif

    Quaternion rotation = Quaternion.AngleAxis(0, Vector3.up);
    this.localAnchor = GameObject.Instantiate(/* some prefab */, hitPosition, rotation);
    this.localAnchor.AddComponent<CloudNativeAnchor>();

    // 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.
    CloudNativeAnchor cloudNativeAnchor = this.localAnchor.GetComponent<CloudNativeAnchor>();
    if (cloudNativeAnchor.CloudAnchor == null) { cloudNativeAnchor.NativeToCloud(); }  
    CloudSpatialAnchor cloudAnchor = cloudNativeAnchor.CloudAnchor;
    await this.cloudSession.CreateAnchorAsync(cloudAnchor);
    this.feedback = $"Created a cloud anchor with ID={cloudAnchor.Identifier}");

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

SessionStatus value = await this.cloudSession.GetSessionStatusAsync();
if (value.RecommendedForCreateProgress < 1.0f) return;
// Issue the creation request ...

プロパティの設定

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

CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor() { LocalAnchor = localAnchor };
cloudAnchor.AppProperties[@"model-type"] = @"frame";
cloudAnchor.AppProperties[@"label"] = @"my latest picture";
await this.cloudSession.CreateAnchorAsync(cloudAnchor);

プロパティを更新する

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

CloudSpatialAnchor anchor = /* locate your anchor */;
anchor.AppProperties[@"last-user-access"] = @"just now";
await this.cloudSession.UpdateAnchorPropertiesAsync(anchor);

アンカーがサービス上で作成された後は、アンカーの位置を更新することはできません。新しい位置を追跡するには、新しいアンカーを作成し、古いアンカーを削除する必要があります。
プロパティを更新するためにアンカーを探知する必要がない場合は、CloudSpatialAnchor オブジェクトをプロパティと共に返す GetAnchorPropertiesAsync() メソッドを使用できます。

var anchor = await cloudSession.GetAnchorPropertiesAsync(@"anchorId");
if (anchor != null)
{
    anchor.AppProperties[@"last-user-access"] = @"just now";
    await this.cloudSession.UpdateAnchorPropertiesAsync(anchor);
}

有効期限の設定

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

cloudAnchor.Expiration = DateTimeOffset.Now.AddDays(7);

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

Azure Spatial Anchors を使用する主な理由の 1 つに、以前に保存したクラウド空間アンカーを検索できることが挙げられます。 クラウド空間アンカーは、さまざまな方法で検索できます。 Watcher では一度に 1 つの方法を使用することができます。

• ID でアンカーを検索します。
• 以前検索したアンカーに接続されているアンカーを検索します。
• 粗い再局在化を使用してアンカーを検索します。

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

クラウド空間アンカーを ID で検索する場合、そのクラウド空間アンカー ID をアプリケーションのバックエンド サービスに格納しておけば、そのバックエンド サービスに対して適切に認証を行うことができるあらゆるデバイスからアクセスさせることができます。
AnchorLocateCriteria オブジェクトをインスタンス化し、検索する識別子を設定します。次に AnchorLocateCriteria を指定することでセッション上の CreateWatcher メソッドを呼び出します。

AnchorLocateCriteria criteria = new AnchorLocateCriteria();
criteria.Identifiers = new string[] { @"id1", @"id2", @"id3" };
this.cloudSession.CreateWatcher(criteria);

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

this.cloudSession.AnchorLocated += (object sender, AnchorLocatedEventArgs args) =>
{
    switch (args.Status)
    {
        case LocateAnchorStatus.Located:
            CloudSpatialAnchor foundAnchor = args.Anchor;
            // Go add your anchor to the scene...
            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;
    }
}

アンカーの削除

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

await this.cloudSession.DeleteAnchorAsync(cloudAnchor);
// Perform any processing you may want when delete finishes

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

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

this.cloudSession.Stop();

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

this.cloudSession.Reset();

セッション後に適切にクリーンアップするには、Dispose() を呼び出します。

this.cloudSession.Dispose();

アンカーにリレーションをつける

下記の2パターンでアンカーにリレーションをつけることができます。

パターン①：1つのセッションでアンカーにリレーションをつける

1. 1つ目の地点にCloudSpatialAnchorSession を使用してアンカー A を作成します。
2. 2つ目の地点に1と同じCloudSpatialAnchorSession を使用してアンカー B を作成します。この時点でアンカーAとBが接続されます。Spatial Anchors サービスがこの関係を保持します。

パターン②：複数のセッションでアンカーにリレーションをつける

1. 1 つ目の CloudSpatialAnchorSession でいくつかのアンカー (アンカー A および B) を作成します。
2. 2つ目の CloudSpatialAnchorSession を作成して、これらのアンカーのいずれか (たとえば、アンカー A) を見つけます。
3. 2つ目の CloudSpatialAnchorSession を使用してアンカー C を作成します。 この時点でアンカー A・Bとアンカー C が接続されます。 Spatial Anchors サービスがこの関係を保持します。

アンカーのリレーションの検証方法

CloudSpatialAnchorWatcher で NearAnchorCriteria を設定することで、2 つのアンカーが接続されていることを検証できます。

参考資料

• Azure Spatial Anchors を使用する Unity HoloLens アプリを作成する [1]
• Unity プロジェクトでの Azure Spatial Anchors の構成 [2]
• Unity で Azure Spatial Anchors を使用してアンカーを作成して配置する方法 [3]