Java で Azure Spatial Anchors を使用してアンカーを作成して配置する方法
Azure Spatial Anchors を使用して、世界中の異なるデバイス間でアンカーを共有できます。 これは複数の異なる開発環境をサポートしています。 この記事では、Azure Spatial Anchors SDK を Java で使用する方法について詳しく説明します。次のことを行います。
- Azure Spatial Anchors セッションを正しく設定して管理する。
- ローカル アンカーのプロパティを作成して設定する。
- それらをクラウドにアップロードする。
- クラウドの空間アンカーを検索して削除する。
前提条件
このガイドを完了するには、次のことが必要です。
- 「Azure Spatial Anchors の概要」を読んでいる。
- 5 分間のクイック スタートのいずれかを完了している。
- Java についての基本的な知識。
- ARCore についての基本的な知識。
セッションの初期化
SDK のメイン エントリ ポイントは、セッションを表すクラスです。 通常は、ビューとネイティブ AR セッションを管理するクラス内のフィールドを宣言します。
CloudSpatialAnchorSession クラスの詳細を確認してください。
private CloudSpatialAnchorSession mCloudSession;
// In your view handler
mCloudSession = new CloudSpatialAnchorSession();
認証の設定
サービスにアクセスするには、アカウント キー、アクセス トークン、または Microsoft Entra 認証トークンを提供する必要があります。 この詳細については、認証の概念に関するページも参照してください。
アカウント キー
アカウント キーは、アプリケーションが Azure Spatial Anchors サービスで認証できるようにするための資格情報です。 アカウント キーの使用目的は、すぐに開始できるようにサポートすることです。 特にアプリケーションの Azure Spatial Anchors との統合の開発フェーズ時などがこれに該当します。 そのようなものとして、開発中にクライアント アプリケーションにアカウント キーを埋め込んで使用できます。 開発の先の段階に進むときには、本番稼働レベルであるか、アクセス トークンによりサポートされるか、または Microsoft Entra ユーザー認証である認証メカニズムに移行することが強く推奨されます。 開発のためにアカウント キーを取得するには、Azure Spatial Anchors アカウントにアクセスし、[キー] タブに移動します。
SessionConfiguration クラスの詳細を確認してください。
mCloudSession.getConfiguration().setAccountKey("MyAccountKey");
アクセス トークン
アクセス トークンは、Azure Spatial Anchors で認証するためのより堅牢な方法です。 特に運用環境デプロイメントのアプリケーションを準備するきにはそのように言えます。 このアプローチの概要は、クライアント アプリケーションが安全に認証できるバックエンド サービスを設定することです。 バック エンド サービスは、実行時に AAD と連動し、Azure Spatial Anchors の Secure Token Service と連動してアクセス トークンを要求します。 このトークンは、クライアント アプリケーションに配信され、SDK で Azure Spatial Anchors で認証するために使用されます。
mCloudSession.getConfiguration().setAccessToken("MyAccessToken");
アクセス トークンが設定されていない場合は、TokenRequired イベントを処理するか、デリゲート プロトコルに tokenRequired メソッドを実装する必要があります。
イベント引数のプロパティを設定することで、イベントを同期的に処理できます。
TokenRequiredListener インターフェイスの詳細を確認してください。
mCloudSession.addTokenRequiredListener(args -> {
args.setAccessToken("MyAccessToken");
});
ハンドラーで非同期操作を実行する必要がある場合は、次の例のように deferral オブジェクトを要求してこれを完了することによって、トークンの設定を延期することができます。
mCloudSession.addTokenRequiredListener(args -> {
CloudSpatialAnchorSessionDeferral deferral = args.getDeferral();
MyGetTokenAsync(myToken -> {
if (myToken != null) args.setAccessToken(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 サービスに対して直接認証できるようになります。
mCloudSession.getConfiguration().setAuthenticationToken("MyAuthenticationToken");
アクセス トークンの場合と同様に、Microsoft Entra トークンが設定されていない場合は、TokenRequired イベントを処理するか、デリゲート プロトコルに tokenRequired メソッドを実装する必要があります。
イベント引数のプロパティを設定することで、イベントを同期的に処理できます。
mCloudSession.addTokenRequiredListener(args -> {
args.setAuthenticationToken("MyAuthenticationToken");
});
ハンドラーで非同期操作を実行する必要がある場合は、次の例のように deferral オブジェクトを要求してこれを完了することによって、トークンの設定を延期することができます。
mCloudSession.addTokenRequiredListener(args -> {
CloudSpatialAnchorSessionDeferral deferral = args.getDeferral();
MyGetTokenAsync(myToken -> {
if (myToken != null) args.setAuthenticationToken(myToken);
deferral.complete();
});
});
セッションの設定
セッションにおいて環境データを処理できるようにするには、Start() を呼び出します。
セッションによって発生したイベントを処理するには、イベント ハンドラーをアタッチします。
mCloudSession.setSession(mSession);
mCloudSession.start();
セッションにフレームを提供する
空間アンカー セッションは、ユーザーの周りに空白をマップすることによって機能します。 そうすることで、アンカーの場所を決定しやすくなります。 モバイル プラットフォーム (iOS と Android) には、プラットフォームの AR ライブラリからフレームを取得するためにカメラ フィードへのネイティブ呼び出しが必要です。 これに対し、HoloLens は環境を継続的にスキャンするため、モバイル プラットフォームの場合と異なり特定の呼び出しは必要ありません。
mCloudSession.processFrame(mSession.update());
ユーザーへのフィードバックの提供
セッションが更新されるイベントを処理するために、コードを記述できます。 セッションによるユーザーの環境の理解が深まるたびに、このイベントが発生します。 これにより、次のことが可能になります。
UserFeedbackクラスを使用して、デバイスが移動し、セッションで環境の把握状況が変わったら、ユーザーにフィードバックを提供する。 これを行うには、次の手順を実行します。- 空間アンカーを作成するのに十分な追跡済み空間データを確保できるのはどの時点かを判断する。 これは
ReadyForCreateProgressまたはRecommendedForCreateProgressで判断します。ReadyForCreateProgressが 1 を超えたら、クラウド空間アンカーを保存するのに十分なデータが得られています。ただし、RecommendedForCreateProgressが 1 を超えるまで待機することをお勧めします。
SessionUpdatedListener インターフェイスの詳細を確認してください。
mCloudSession.addSessionUpdatedListener(args -> {
auto status = args->Status();
if (status->UserFeedback() == SessionUserFeedback::None) return;
NumberFormat percentFormat = NumberFormat.getPercentInstance();
percentFormat.setMaximumFractionDigits(1);
mFeedback = String.format("Feedback: %s - Recommend Create=%s",
FeedbackToString(status.getUserFeedback()),
percentFormat.format(status.getRecommendedForCreateProgress()));
});
クラウド空間アンカーの作成
クラウド空間アンカーを作成するには、最初にプラットフォームの AR システムにアンカーを作成した後、対応するアンカーをクラウド上に作成します。 CreateAnchorAsync() メソッドを使用します。
CloudSpatialAnchor クラスの詳細を確認してください。
// Create a local anchor, perhaps by hit-testing and creating an ARAnchor
Anchor localAnchor = null;
List<HitResult> hitResults = mSession.update().hitTest(0.5f, 0.5f);
for (HitResult hit : hitResults) {
Trackable trackable = hit.getTrackable();
if (trackable instanceof Plane) {
if (((Plane) trackable).isPoseInPolygon(hit.getHitPose())) {
localAnchor = hit.createAnchor();
break;
}
}
}
// 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 = new CloudSpatialAnchor();
cloudAnchor.setLocalAnchor(localAnchor);
Future createAnchorFuture = mCloudSession.createAnchorAsync(cloudAnchor);
CheckForCompletion(createAnchorFuture, cloudAnchor);
// ...
private void CheckForCompletion(Future createAnchorFuture, CloudSpatialAnchor cloudAnchor) {
new android.os.Handler().postDelayed(() -> {
if (createAnchorFuture.isDone()) {
try {
createAnchorFuture.get();
mFeedback = String.format("Created a cloud anchor with ID=%s", cloudAnchor.getIdentifier());
}
catch(InterruptedException e) {
mFeedback = String.format("Save Failed:%s", e.getMessage());
}
catch(ExecutionException e) {
mFeedback = String.format("Save Failed:%s", e.getMessage());
}
}
else {
CheckForCompletion(createAnchorFuture, cloudAnchor);
}
}, 500);
}
前述のように、新しいクラウド空間アンカーの作成を試みる前に、十分な環境データが取得されている必要があります。 これは、ReadyForCreateProgress が 1 を超えている必要があることを意味しますが、Microsoft では RecommendedForCreateProgress が 1 を超えるまで待機することをお勧めします。
Future<SessionStatus> sessionStatusFuture = mCloudSession.getSessionStatusAsync();
CheckForCompletion(sessionStatusFuture);
// ...
private void CheckForCompletion(Future<SessionStatus> sessionStatusFuture) {
new android.os.Handler().postDelayed(() -> {
if (sessionStatusFuture.isDone()) {
try {
SessionStatus value = sessionStatusFuture.get();
if (value.getRecommendedForCreateProgress() < 1.0f) return;
// Issue the creation request...
}
catch(InterruptedException e) {
mFeedback = String.format("Session status error:%s", e.getMessage());
}
catch(ExecutionException e) {
mFeedback = String.format("Session status error:%s", e.getMessage());
}
}
else {
CheckForCompletion(sessionStatusFuture);
}
}, 500);
}
プロパティの設定
クラウド空間アンカーを保存するときには、いくつかのプロパティを追加することを選択できます。 これは保存されるオブジェクトの型や、相互作用に対して有効にすべきかどうかなどの基本プロパティなどです。 そのようにすると検出時に役立つ場合があります。空のコンテンツの画像フレームなど、ユーザー向けのオブジェクトをすぐにレンダリングできます。 次に、バックグラウンドでの別のダウンロードにより、フレームに表示されるピクチャなどの、追加の状態の詳細が取得されます。
CloudSpatialAnchor cloudAnchor = new CloudSpatialAnchor();
cloudAnchor.setLocalAnchor(localAnchor);
Map<String,String> properties = cloudAnchor.getAppProperties();
properties.put("model-type", "frame");
properties.put("label", "my latest picture");
Future createAnchorFuture = mCloudSession.createAnchorAsync(cloudAnchor);
// ...
プロパティを更新する
アンカーでプロパティを更新するには、UpdateAnchorProperties() メソッドを使用します。 2 つ以上のデバイスが同じアンカーのプロパティを同時に更新する場合は、オプティミスティック同時実行制御モデルを使用します。 これは、最初の書き込みが優先されることを意味します。 その他のすべての書き込みには、「同時実行」エラーが発生します。再試行する前に、プロパティの更新が必要になります。
CloudSpatialAnchor anchor = /* locate your anchor */;
anchor.getAppProperties().put("last-user-access", "just now");
Future updateAnchorPropertiesFuture = mCloudSession.updateAnchorPropertiesAsync(anchor);
CheckForCompletion(updateAnchorPropertiesFuture);
// ...
private void CheckForCompletion(Future updateAnchorPropertiesFuture) {
new android.os.Handler().postDelayed(() -> {
if (updateAnchorPropertiesFuture.isDone()) {
try {
updateAnchorPropertiesFuture.get();
}
catch(InterruptedException e) {
mFeedback = String.format("Updating Properties Failed:%s", e.getMessage());
}
catch(ExecutionException e) {
mFeedback = String.format("Updating Properties Failed:%s", e.getMessage());
}
}
else {
CheckForCompletion1(updateAnchorPropertiesFuture);
}
}, 500);
}
アンカーがサービス上で作成された後は、アンカーの位置を更新することはできません。新しい位置を追跡するには、新しいアンカーを作成し、古いアンカーを削除する必要があります。
プロパティを更新するためにアンカーを探知する必要がない場合は、CloudSpatialAnchor オブジェクトをプロパティと共に返す GetAnchorPropertiesAsync() メソッドを使用できます。
Future<CloudSpatialAnchor> getAnchorPropertiesFuture = mCloudSession.getAnchorPropertiesAsync("anchorId");
CheckForCompletion(getAnchorPropertiesFuture);
// ...
private void CheckForCompletion(Future<CloudSpatialAnchor> getAnchorPropertiesFuture) {
new android.os.Handler().postDelayed(() -> {
if (getAnchorPropertiesFuture.isDone()) {
try {
CloudSpatialAnchor anchor = getAnchorPropertiesFuture.get();
if (anchor != null) {
anchor.getAppProperties().put("last-user-access", "just now");
Future updateAnchorPropertiesFuture = mCloudSession.updateAnchorPropertiesAsync(anchor);
// ...
}
} catch (InterruptedException e) {
mFeedback = String.format("Getting Properties Failed:%s", e.getMessage());
} catch (ExecutionException e) {
mFeedback = String.format("Getting Properties Failed:%s", e.getMessage());
}
} else {
CheckForCompletion(getAnchorPropertiesFuture);
}
}, 500);
}
有効期限の設定
未来の特定の日付で有効期限が自動的に切れるようにアンカーを構成することもできます。 有効期限が切れたアンカーは、特定も更新もできなくなります。 有効期限を設定できるのはアンカーを作成しているときだけです。それをクラウドに保存する前に設定してください。 後で有効期限を更新することはできません。 アンカーの作成中に有効期限が設定されていない場合、アンカーは手動で削除されたときにのみ有効期限が切れます。
Date now = new Date();
Calendar cal = Calendar.getInstance();
cal.setTime(now);
cal.add(Calendar.DATE, 7);
Date oneWeekFromNow = cal.getTime();
cloudAnchor.setExpiration(oneWeekFromNow);
クラウド空間アンカーを見つける
Azure Spatial Anchors を使用する主な理由の 1 つに、以前に保存したクラウド空間アンカーを検索できることが挙げられます。 このためには、"Watcher" を使用しています。 一度に使用できる Watcher は 1 つだけです。複数の Watcher はサポートされていません。 Watcher を使用してクラウド空間アンカーを見つける方法はいくつかあります (アンカー検索戦略とも呼ばれます)。 Watcher では一度に 1 つの方法を使用することができます。
注意
アンカーを配置するたびに、Azure Spatial Anchors は、収集された環境データを使用して、アンカーのビジュアル情報を増強しようとします。 アンカーを配置するのに問題がある場合は、アンカーを作成した後、さまざまな角度や照明条件から何度か配置してみるといいでしょう。
クラウド空間アンカーを識別子で検索する場合は、クラウド空間アンカー識別子をアプリケーションのバックエンド サービスに格納しておけば、それに対して適切に認証できるすべてのデバイスからアクセスできます。 この例のついては、「チュートリアル: デバイス間で空間アンカーを共有する」をご覧ください。
AnchorLocateCriteria オブジェクトをインスタンス化し、検索する識別子を設定します。次に AnchorLocateCriteria を指定することでセッション上の CreateWatcher メソッドを呼び出します。
AnchorLocateCriteria criteria = new AnchorLocateCriteria();
criteria.setIdentifiers(new String[] { "id1", "id2", "id3" });
mCloudSession.createWatcher(criteria);
監視が作成された後、要求されたすべてのアンカーに対して AnchorLocated イベントが発生します。 このイベントは、アンカーが探知されたとき、またはアンカーを探知できなかった場合に発生します。 このような状況が発生した場合は、その理由が状態に示されます。 監視のすべてのアンカーが (探知されたかどうかを問わず) 処理された後、LocateAnchorsCompleted イベントが発生します。 識別子の上限は、Watcher 1 つあたり 35 個です。
AnchorLocatedListener インターフェイスの詳細を確認してください。
mCloudSession.addAnchorLocatedListener(args -> {
switch (args.getStatus()) {
case Located:
CloudSpatialAnchor foundAnchor = args.getAnchor();
// Go add your anchor to the scene...
break;
case AlreadyTracked:
// This anchor has already been reported and is being tracked
break;
case 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 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 リソースをクリーンアップすることをお勧めします。
Future deleteAnchorFuture = mCloudSession.deleteAnchorAsync(cloudAnchor);
// Perform any processing you may want when delete finishes (deleteAnchorFuture is done)
セッションの一時停止、リセット、停止
セッションを一時的に停止するために、Stop() を呼び出すことができます。 そうすることで、ProcessFrame() を呼び出した場合でも、あらゆるウォッチャーや環境処理を停止できます。 次に Start() を呼び出して、処理を再開できます。 再開するとき、既にセッションでキャプチャされた環境データは保持されます。
mCloudSession.stop();
セッションでキャプチャされた環境データをリセットするために、Reset() を呼び出すことができます。
mCloudSession.reset();
セッション後に適切にクリーンアップするには、close() を呼び出します。
mCloudSession.close();
次のステップ
このガイドでは、Azure Spatial Anchors SDK を使用してアンカーを作成および探知する方法について学習しました。 アンカーのリレーションシップの詳細については、次のガイドに進んでください。