バージョン: 1.0.1

画像トラッキング

画像トラッキングの基本的な情報と、AR FoundationのAR Tracked Image Managerコンポーネントが何をするかについては、Unityのドキュメントを参照してください。

画像ターゲットは、XR Reference Image Libraryを通して基礎となるXRプラグインに供給されます。
追加された画像には、後でトラッキングされたターゲットを特定するのに便利な名前と、trueに設定する必要がある重要なKeep Texture at Runtimeフラグがあります。これにより、サブシステムはトラッキングのためにテクスチャデータをSnapdragon Spaces Servicesに渡すことができます。

機能の有効化

この機能を使用するには、以下のOpenXRのプロジェクト設定でImage Trackingにチェックする必要があります。
Project Settings > XR Plug-in Management > OpenXR (Androidタブ) > OpenXR Feature Groups > Snapdragon Spaces > Image Tracking
alt text

機能の設定

この機能の設定は、OpenXRのプロジェクト設定のImage Trackingの項目内の右横の歯車アイコンをクリックすると表示されます。

alt text
画像トラッキング機能には2つの設定があります。

Extended Range Mode：広範囲に最適化されたトラッキングを行います。
Low Power Mode：低消費電力に最適化されたトラッキングを行います。

Spaces Reference Image Configurator

alt text オプションのSpaces Reference Image Configuratorコンポーネントは、ARTrackedImageManagerと同じGameObjectに追加することができます。このコンポーネントでは、トラッキング画像の追加設定を行えます。

トラッキングモード

Tracking Modeのフィールドでは、画像ごとに異なるトラッキングモードを設定できます。

Dynamic (Default)：Dynamicモードは、トラッキングされた画像の位置がフレームごとに更新され、移動中のターゲットと静止したターゲットの両方で機能します。トラッキングされた画像が見つからない場合、位置や姿勢は報告されません。このモードでは、他のトラッキングモードに比べて消費電力が高くなります。Spaces Reference Image Configuratorコンポーネントが見つからない場合、全てのトラッキング画像はデフォルトでこのトラッキングモードを使用します。
Static：Staticモードは、静止した画像をトラッキングするのに役立ち、消費電力の削減とパフォーマンスの向上につながります。たとえば、床や壁に貼り付けられた画像がこれに該当します。このモードは、画像が見えなくなった後も、引き続き表示される必要があるARオブジェクトを表示し続けるのに便利です。Staticモードでトラッキングされた画像の位置は、画像が移動したか視界から外れたかに関係なく、更新されることはありません。
Adaptive：Adaptiveモードは静止した画像で動作しますが、トラッキングされた画像が動いた場合は、およそ5フレームごとに定期的に画像の位置を更新します。HMDが移動した場合、画像の位置はディスプレイのリフレッシュレートに合わせて更新されます。視界から外れた画像のトラッキングは最終的に失われます。このモードは、消費電力とトラッキング精度のバランスをとります。

トラッキングモード	トラッキングの開始タイミング	画像位置の更新間隔	トラッキングの終了タイミング
Dynamic (default)	画像がカメラ画角内に入った時	全てのフレーム	画像がカメラ画角外に出た時
Static	画像がカメラ画角内に入った時	更新無し	新しい画像がトラッキングされた場合
Adaptive	画像がカメラ画角内に入った時	5フレームごと	画像がカメラ画角外に出た時

アプリを起動すると、トラッキングされた画像は Spaces Reference Image Configuratorコンポーネントで定義されたトラッキングモードを使用します。

    public SpacesReferenceImageConfigurator referenceImageConfigurator;
    private Dictionary<TrackableId, ...> _trackedImages = new Dictionary<TrackableId, ...>();
    ...

    string referenceImageName = ...; // referenceImageName to change Tracking Mode for
    TrackableId trackableId = ...; // a TrackableId for an existing tracked instance of this image
    ...

    // first, stop tracking any instances of the tracked image for which the Tracking Mode should be updated.
    // if tracking is not stopped, the instance can (but is not guaranteed to) continue to be tracked using the old Tracking Mode for some time 
    referenceImageConfigurator.StopTrackingImageInstance(referenceImageName, trackableId);
    ...
    
    // then, set the desired tracking mode for all future instances of the tracked image with that referenceImageName
    referenceImageConfigurator.SetTrackingModeForReferenceImage(referenceImageName, SpacesImageTrackingMode.DYNAMIC);
    referenceImageConfigurator.SetTrackingModeForReferenceImage(referenceImageName, SpacesImageTrackingMode.STATIC);
    referenceImageConfigurator.SetTrackingModeForReferenceImage(referenceImageName, SpacesImageTrackingMode.ADAPTIVE);

トラッキング画像を変更(追加)する

画像トラッキングに使用する画像ターゲット（マーカー）をEditor上で変更する方法を紹介します。

1. 画像のインポート

Projectタブ内の任意のフォルダに、画像トラッキングに使用したい画像をインポートします。　

使用する画像について

画像トラッキングでは画像の特徴を利用してトラッキングを行っています。
以下の基準で画像を用意することを、お勧めします。認識が難しい例の場合、トラッキング出来ない可能性があります。

良い例

特徴（情報量）が多い（例：SpacesTown）
カラフル
アスペクト比が、正方形に近い
バージョン数が高い（セル数が多い）QRコード

認識が難しい例

特徴（情報量）が少ない
余白が多い
単色
画像内で同じパターンが続いている
アスペクト比が、横もしくは縦に極端に長い
ドット数が少ない
- ArUcoマーカー
- バージョン数が低い（セル数が少ない）QRコード

2. 画像の設定

新たにインポートした画像を選択し、以下の変更を行った後に、「Apply」を選択します。

「Read/Write」：有効
「Format」：RGB 24bit

「Feature unavailable」と表示される場合

上記の「Read/Write」を無効にしてしまった場合、画像トラッキング機能は動作しなくなります。
画像トラッキングのサンプルの場合は、アプリ内で「Feature unavailable」と表示されます。

3. ReferenceImageLibraryの設定

ReferenceImageLibraryを選択します。
- 機能サンプルの場合：Assets/Samples/Snapdragon Spaces/1.0.1/Core Samples/Scenes/Image Tracking Sample/Image Libraries/ReferenceImageLibrary
ReferenceImageLibraryのInspector内の「Add Image」を選択します。　
ReferenceImageLibraryのInspector内で以下の変更を行います。
- 「Texture 2D（画像のサムネ）」：新たにインポートしておいた画像を選択します。
- 「Specify Size」：有効
  - 「Physical Size」：実際に物理的に用意する画像のサイズを指定します。
- 「Keep Texture at Runtime」：有効

設定項目について

「Physical Size」：画像トラッキングの精度に影響するため、実際の画像サイズを指定することは重要です。
「Keep Texture at Runtime」：無効にしてしまった場合、アプリは正常に動作しているように見えても、その画像を認識することはできません。

マーカーが認識されるか確認する際のTIP

Snapdragon Spaces Servicesが正常に動作していない場合、認識されるはずのマーカーであっても認識されない場合があります。そのため、Spacesの不具合の問題なのかマーカーの問題なのかを把握するために、検証の段階であれば、ReferenceImageLibraryにデフォルトのマーカー（SpacesTown）も登録しておくことをおすすめします。

デフォルトのマーカー（SpacesTown）は認識するのに、追加で登録したマーカーが認識しない場合は、以下の理由が考えられます。

マーカーの特徴が少ない
マーカーの設定が間違っている
- 「Keep Texture at Runtime」が有効になっていない
- 「Specify Size」の「Physical Size」が実際のマーカーサイズとかけ離れている

4. 同時に認識できる数の設定

同時に複数の画像のトラッキングを行いたい場合は、以下の変更を行います。

画像トラッキングを行うシーンを開きます。
XR Origin (XR Rig)オブジェクトを選択します。
AR Tracked Image Managerコンポーネントの「Max Number Of Moving Images」の値を指定します。
シーンを保存します。

以上で、新しい画像の登録のセットアップは完了です。

実行時にトラッキング画像を変更する

シーンを切り替えることなく、AR Tracked Image Managerが使用する参照画像ライブラリ(トラッキングする画像)を実行時に変更することが可能です。そのためには、以下の点について考慮する必要があります。

ライブラリの変更を有効にするには、Image Tracking subsystemを再起動する必要があります。これは、AR Tracked Image Managerコンポーネントを再び有効にすることで実現できます。
コンポーネントのSyncTrackingModes関数を使用して、新しいライブラリ用にSpaces Reference Image Configuratorでトラッキングモードを再同期する必要があります。引数として、参照画像名と最初のトラッキングモードのDictionary<string, SpacesImageTrackingMode>を指定します。

WARNING

ライブラリを交換する際、Spaces Reference Image Configuratorでトラッキングモードの再適用を行なわず、前のライブラリに参照イメージ名が見つからない場合、SetTrackingModeForReferenceImage関数が失敗します。
このような場合、Dynamicモードが参照画像のデフォルトのトラッキングモードになります。

以下のサンプルコードでは、実行時に異なる参照画像ライブラリにスワップする関数 SwapTargetLibraryを実装しています。まず、Tracked Image Managerコンポーネントを無効にし、Spaces Reference Image ConfiguratorコンポーネントのSyncTrackingModes関数でトラッキングモードを再同期します。参照画像名と最初のトラッキングモードのDictionary<string, SpacesImageTrackingMode>は、補助関数CreateTrackingModesDictionaryによって提供されます。最後に、新しい参照ライブラリがAR Tracked Image Managerコンポーネントに適用され、後者が再度有効になります。

public ARTrackedImageManager TrackedImageManager;
public SpacesReferenceImageConfigurator ReferenceImageConfigurator;

void SwapTargetLibrary(XRReferenceImageLibrary library)
{
    TrackedImageManager.enabled = false;
    ReferenceImageConfigurator.SyncTrackingModes(CreateTrackingModesDictionary(library));
    TrackedImageManager.referenceLibrary = library;
    TrackedImageManager.enabled = true;
}

Dictionary<string, SpacesImageTrackingMode> CreateTrackingModesDictionary(XRReferenceImageLibrary library)
{
    Dictionary<string, SpacesImageTrackingMode> trackingModes = new Dictionary<string, SpacesImageTrackingMode>();
    foreach (var referenceImage in library)
    {
        trackingModes[referenceImage.name] = SpacesImageTrackingMode.DYNAMIC;
    }

    return trackingModes;
}

機能の有効化​

機能の設定​

Spaces Reference Image Configurator​

トラッキングモード​

トラッキング画像を変更(追加)する​

1. 画像のインポート​

良い例​

認識が難しい例​

2. 画像の設定​

3. ReferenceImageLibraryの設定​

4. 同時に認識できる数の設定​

実行時にトラッキング画像を変更する​