メインコンテンツまでスキップ

Map-based Relocalization Sample

このサンプルでは、マップベースのリローカリゼーションを使って、マップからシェアードアンカーを探し出し、リローカリゼーションに成功するとシェアードアンカーの位置に立方体を表示します。

シェアードアンカーが見つかると、ARの原点（0, 0, 0）をシェアードアンカーの位置に移動させます。マップベースのシェアードアンカーの場合、この実世界空間での位置は、最初に地図のスキャンを開始した場所となります。

シーンを理解する​

シーンの階層​

まず、シーンの構成から見ていきましょう。これは、サンプルのゲームオブジェクト階層です。

AR Foundationから提供された階層に、通常の AR Session Origin と AR Session オブジェクトがあるのが確認できます。

Pretia SDKで作られたアプリは、AR Foundationの標準的なコンポーネントで作られた通常のARアプリと非常によく似ています。Pretia SDKのリローカリゼーションは、UnityのXR Subsystemの上に構築されており、AR Foundationと相互に運用できます。

ARSharedAnchorManager​

AR Session Originオブジェクトには、ARSharedAnchorManagerというコンポーネントがあります。

このコンポーネントはSDKによって提供され、リローカリゼーションプロセスを管理する責任を負っています。インスペクタを見ると、修正可能なフィールドがいくつかあることが分かります。このチュートリアルでは、 Map Selection にのみ興味があります。画像ベースのリローカライゼーション機能を使用しないので、AR Tracked Image Managerは空欄のままにしておきます。

リローカリゼーション自動的に実行するオプションがありますが、このサンプルでは使用しません。詳しくはARSharedAnchorManager API Referenceを参照してください。

Map Selection​

Map Selection を割り当てると、マップベースのリローカライズに使用されるデフォルトのマップ選択ストラテジーを設定します。Pretia SDKはデフォルトのマップ選択方法として、DirectMapSelection とCriteriaBasedMapSelection の2つを提供しています（詳しくはMapSelectionを参照してください）。

DirectMapSelection は、アセットに割り当てられている Map Key をそのまま返します。マップキーは開発者コンソールから取得することができます。

Starting/Stopping Relocalization​

SceneController オブジェクトには、MapBasedRelocSceneController という名前のコンポーネントがあります。このスクリプトは、ボタンが押されたときにリローカライズの開始/停止を行うことができます。以下は、リローカライズの開始と停止に関連するAPIです。

// Grab an instance of ARSharedAnchorManager
private ARSharedAnchorManager _sharedAnchorManager;

// Start map-based relocalization using the default map selection strategy
_sharedAnchorManager.StartCloudMapRelocalization();

// Will skip the default map selection strategy and
// start map-based relocalization using mapKey
string mapKey = "XXXX"
_sharedAnchorManager.StartCloudMapRelocalization(mapKey);
 
// Stop any running relocalization process and
// reset the shared anchor status
_sharedAnchorManager.ResetSharedAnchor();

Handling Events​

ARContentHandler と ARContents オブジェクトを見てみましょう。ARContents は階層構造で無効になっていることがわかります。これは、リローカライズに成功したときだけ有効にしたいためです。これを実現するために、 ARContentHandler の中に、 ARSharedAnchorManager からの OnRelocalized イベントを参照して有効にするコンポーネントがあります。

public delegate void RelocalizedEvent();
public event RelocalizedEvent OnRelocalized;

シェアードアンカーの動作に対する反応をより細かく制御するために、SDKは共有アンカーの状態が変化したときのコールバックを提供します。

シェアードアンカーは、Stopped 、Initializing 、Relocalizing、Relocalizedの4つの状態のうちの1つになります。StatusUpdater オブジェクトのコンポーネントは、UI キャンバスのステータステキストが変更されるたびにそれを更新する役割を担います。

public delegate void RelocalizationStateChanged(RelocalizationState newState);
public event RelocalizationStateChanged OnRelocalizationStateChanged;

public enum RelocalizationState
{
    Stopped = 0,
    Initializing = 1,
    Relocalizing = 2,
    Relocalized = 3
}

また、失敗してしまったケースでは、SDKはこれらのイベントを提供します。ErrorHandler にあるコンポーネントは、エラーが発生したときに UIキャンバスにエラーメッセージを表示します。

public delegate void SharedAnchorSubsystemException(Exception e);
public event SharedAnchorSubsystemException OnException;

Relocalization Score​

リローカライゼーションを行う場合、正しい場所をスキャンしているかどうかが分からないことが多くあります。そのため、私たちはリローカライズスコアを取得する方法を提供しています。

このスコアは 0f から 1f までの範囲です。1f に近いほど、リローカライズが成功に近いことを意味します。scoreUpdater というコンポーネントがあり、スコアが変わるたびにUIキャンバスのスコアテキストを更新します。さらに、ARSharedAnchorManager の RelocalizationScore フィールドからスコアを取得することもできます。

public delegate void RelocalizationScoreUpdated(float score);
public event RelocalizationScoreUpdated OnRelocalizationScoreUpdated;

// Alternatively, get the score from RelocalizationScore
public float RelocalizationScore { get; }

サンプルをビルドする​

アプリケーションをビルドする前に、設定を行う必要があります。アプリケーションをビルドする方法については、こちらのガイドを参照してください。

サンプルを実行する​

デバイス上でサンプルを実行し、Map Key に使用したマップの領域をスキャンしてアプリの動作を確認します。シェアードアンカー位置（このマップのマッピングを最初に開始した位置）に立方体が表示されるはずです。

ここまできたら、いよいよARコンテンツをプロジェクトに追加していきます。オブジェクトを配置する方法についてのガイドをご覧になることをおすすめします。