Manager

AR Foundation における Manager (マネージャー) とは、シーン内の AR (拡張現実) 機能用にスクリプトインターフェースを提供するコンポーネントです。例えば、Plane Manager を使用すると平面検出機能が有効になり、アプリケーションコード内で検出された平面に対応できます。

AR Plane Manager コンポーネント
AR Plane Manager コンポーネント

AR Foundation は、サブシステム を使用してその AR 機能を定義します。マネージャーはサブシステムデータをシーン内でゲームオブジェクトやコンポーネントとしてアクセスできるようにし、サブシステムのライフサイクルの管理も行います (Manager は SubsystemLifecycleManager の略語です)。例えば、XRPlaneSubsystem によって環境内に平面が検出されると、Plane Manager がその平面を表すゲームオブジェクトを作成します。Plane Manager を有効または無効にすると、それに応じてアプリケーションでの平面検出も有効または無効になります。

すべての AR 関連サブシステムに、対応するマネージャーがあります。このパッケージ内のサブシステムは、XR<機能>Subsystem という命名規則に従い、そのマネージャーは、ARSession コンポーネントを除き、AR<機能>Manager という規則で命名されています。

シーンへのマネージャーの追加

シーンにマネージャーを追加するには、コンポーネントを追加するのと同じ手順に従います。

Note

特殊なケースである AR Session コンポーネント と Mesh Manager を除き、すべてのマネージャーを、シーン内の XR Origin と同じゲームオブジェクトに追加する必要があります。

  1. 最初に Hierarchy ウィンドウで、追加するマネージャーコンポーネントに適したゲームオブジェクトを選択します。
  2. Inspector で Add Component ボタンをクリックします。
  3. 最後に、追加するマネージャーコンポーネントを検索して選択します。

AR Plane Manager コンポーネントの追加
AR Plane Manager コンポーネントの追加

マネージャーがシーンに XR Origin の子として新しい trackable (トラッカブル) を追加し、その位置、回転、スケールを XR Origin を基準にして定義します。

XR Origin ゲームオブジェクトと各種マネージャー
XR Origin ゲームオブジェクトと各種マネージャー

マネージャーの有効化と無効化

関連するマネージャーを有効または無効にすることで、AR 機能を有効または無効にできます。例えば、AR Plane Manager コンポーネントを有効または無効にして、平面検出のオン/オフを切り替えることができます。

有効にするマネージャーは、常に 1 シーンあたり 1 タイプのみにする必要があります。複数のマネージャーインスタンスを有効にすると、各マネージャーインスタンスが基盤となる同じサブシステムを操作することになるので、望ましくない動作が起こることがあります。

AR 機能を有効にすると、デバイスの消費電力が増えることがあるので、アプリケーションでその機能を使用していないときは、マネージャーを無効にすることをお勧めします。

マネージャーは、該当する サブシステムのライフサイクル メソッドを呼び出すことで、有効化や無効化に対応します。

  • OnEnable: サブシステムの Start を呼び出す
  • OnDisable: サブシステムの Stop を呼び出す

プロバイダープラグイン に特定のサブシステムが実装されていない場合、対応するマネージャーはそれ自体を自動的に無効にします。例えば、現在 Google ARCore XR Plug-in には XRObjectTrackingSubsystem が実装されていないので、ARTrackedObjectManager は常に Android プラットフォーム上でそれ自体を無効にします。ターゲットプラットフォームでどのサブシステムが利用可能かを確認するには、対応プラットフォーム またはプロバイダーのドキュメントを参照してください。

トラッカブルとトラッカブルマネージャー

多くの AR Foundation サブシステムは、物理環境内のオブジェクトを検出して追跡します。これらのサブシステムは トラッキングサブシステム と呼ばれ、そのマネージャーは Trackable (トラッカブル) マネージャーと呼ばれています。トラッカブルマネージャーは、トラッキングサブシステムのデータを使用して、トラッカブルコンポーネントとそのゲームオブジェクトを作成、維持します。

トラッカブルは、現実世界で検出および追跡できるすべてのものを表す特別なコンポーネントです。平面、点群、アンカー、環境プローブ、顔、体、画像、3D オブジェクトは、いずれも対応するトラッカブルコンポーネントをもつオブジェクトの例です。

各タイプのトラッカブルは、一致するタイプのトラッカブルマネージャーによって作成、維持されます。トラッカブルマネージャーは、トラッキングサブシステムをラップし、そのデータを使用してトラッカブルとそのゲームオブジェクトを管理します。例えば、ARPlaneManager は XRPlaneSubsystem のデータを使用して ARPlane というトラッカブルを生成します。

以下の表は、トラッカブルマネージャーとそのトラッカブルのタイプをまとめたものです。

トラッカブルマネージャー トラッカブル 目的
ARPlaneManager ARPlane サーフェスを検出して追跡します。
ARTrackedImageManager ARTrackedImage 2D 画像を検出して追跡します。
ARTrackedObjectManager ARTrackedObject 3D オブジェクトを検出して追跡します。
ARFaceManager ARFace 人物の顔を検出して追跡します。
ARHumanBodyManager ARHumanBody 人物の体を検出して追跡します。
ARPointCloudManager ARPointCloud 特徴点を検出して追跡します。
ARRaycastManager ARRaycast フレームごとにレイキャストを繰り返します。
ARAnchorManager ARAnchor スペース内の任意の点を追跡します。
AREnvironmentProbeManager AREnvironmentProbe 環境のキューブマップを生成します。
ARParticipantManager ARParticipant 共有 AR セッションで他のデバイスを追跡します。

トラッカブルの列挙

トラッカブルは、そのマネージャーの trackables プロパティによって列挙できます。以下はその例です。

var planeManager = GetComponent<ARPlaneManager>();
foreach (ARPlane plane in planeManager.trackables)
{
    // ARPlane で何かを実行する
}

trackables プロパティから返される TrackableCollection は、上の例のように foreach ステートメントで列挙できます。また、TryGetTrackable メソッドで特定のトラッカブルを照会することもできます。

トラッカブルのライフサイクル

トラッカブルは、追加、更新、削除できます。更新や削除の前に、必ず追加が行われます。いったん削除すると更新できません。フレームごとに、マネージャーがサブシステムを照会して、前のフレーム以降にトラッカブルの変更が生じているか判断します。トラッカブルマネージャーには、それぞれ以下のように変更の通知が届くようサブスクライブできるイベントがあります。

トラッカブルマネージャー イベント
ARPlaneManager planesChanged
ARTrackedImageManager trackedImagesChanged
ARTrackedObjectManager trackedObjectsChanged
ARFaceManager facesChanged
ARHumanBodyManager humanBodiesChanged
ARPointCloudManager pointCloudsChanged
ARAnchorManager anchorsChanged
AREnvironmentProbeManager environmentProbesChanged
ARParticipantManager participantsChanged

これらのイベントへの応答の詳細については、各マネージャーのドキュメントを参照してください。

トラッカブルの追加

アンカーや環境プローブなど、一部のトラッカブルは、手動で追加および削除できます。平面、画像、オブジェクト、点群などの他のトラッカブルは、マネージャーが自動的に追加および削除します。手動と自動のどちらでも追加できるトラッカブルもあります。サポートされている場合は、トラッカブルマネージャーが手動での追加と削除のためのメソッドを備えています。

トラッカブルを手動で追加した場合、基盤となるサブシステムがすぐにそのトラッカブルを追跡しないことがあります。追加されたことをサブシステムが (通常は次のフレームで) レポートするまで、そのトラッカブルの added イベントを受信することはありません。手動での追加から added イベントまでの間、トラッカブルは 保留 ステートになります。これはすべてのトラッカブルの pending プロパティで確認できます。

例えばアンカーを追加すると、多くの場合、次のフレームまで保留になります。

var anchor = AnchorManager.AddAnchor(new Pose(position, rotation));
Debug.Log(anchor.pending); // "true"

// -- 次のフレーム --
void OnAnchorsChanged(ARAnchorsChangedEventArgs eventArgs)
{
    foreach (var anchor in eventArgs.added)
    {
        // 上で追加したアンカーがこのリストに表示されます。
    }
}

トラッカブルが保留ステートのままである正確な時間は、基盤となる実装によって異なります。

トラッカブルの削除

アンカーを除き、トラッカブルコンポーネントやそのゲームオブジェクトに対して Destroy (除去) を実行しないでください。トラッカブルは、トラッカブルサブシステムによって表面化したデータを表すものであり、そのシーン表現を除去しても、サブシステムの実装には影響しません。トラッカブルが手動削除に対応している場合、通常はそのマネージャーがトラッカブルを削除するメソッドを備えています。例えば、永続化されたレイキャストは ARRaycastManager.RemoveRaycast(ARRaycast) を呼び出すことで削除できます。

このルールの例外となるのがアンカーです。アンカーはそのゲームオブジェクトを除去することで安全に削除できます。アンカーの追加と削除の詳細については、アンカー を参照してください。

平面、画像、オブジェクト、点群など、多くのトラッカブルは、どのような形の手動削除にも対応していません。これらのトラッカブルは、そのマネージャーのみが削除でき、基盤となるサブシステムから削除通知を受信した場合に、マネージャーが自動的に削除します。この方法でマネージャーがトラッカブルを削除するときは、destroyOnRemoval が false でない限り、そのトラッカブルのゲームオブジェクトに対して Destroy を実行します。

AR Plane コンポーネントと Destroy On Removal フィールド
AR Plane コンポーネントと Destroy on Removal フィールド

トラッカブルのマネージャーの関連イベントをサブスクライブすることで、そのトラッカブルの削除にアプリケーションで対応できます。例えば、ARPlane が削除されると、ARPlaneManager によって、その planesChanged イベントが呼び出され、該当する平面が ARPlanesChangedEventArgs 構造体の removed 平面のリストに含まれます。トラッカブルのライフサイクルイベントの詳細については、各トラッカブルマネージャーのドキュメントを参照してください。

トラッキングステートの監視

トラッカブルマネージャーが無効にされたときや、追跡対象オブジェクトが AR デバイスのカメラのフレーム外に移動したときなど、トラッキング品質が変化するケースで、関連サブシステムがトラッカブルを削除せず、代わりに、そのトラッカブルの trackingState 値を変更することがあります。トラッカブルが追加または更新されたときにその trackingState プロパティを読み取ることにより、アプリケーションでトラッキングステートの変化に対応できます。

トラッカブルの非アクティブ化

トラッカブルのマネージャーを無効にすることなく、そのトラッカブルに関連付けられている動作の実行を停止することが必要になる場合があります。例えば、平面検出を停止することなく、検出された平面のレンダリングを停止したい場合などです。

そのためには、各トラッカブルのゲームオブジェクトを非アクティブ化します。

var planeManager = GetComponent<ARPlaneManager>();
foreach (var plane in planeManager.trackables)
{
    plane.gameObject.SetActive(false);
}

トラッカブルの可視化

トラッカブルコンポーネントは独自に何かを実行するわけではなく、トラッカブルコンポーネントには各トラッカブルの関連データが含まれています。トラッカブルはさまざまな方法で可視化できるので、AR Foundation にはいくつかのビジュアライザーが含まれており、デバッグや、アプリケーションに適したビジュアライザーを作成する出発点として利用できます。

トラッカブルのゲームオブジェクトの設定

新しいトラッカブルが検出されると、そのマネージャーが Inspector で指定されたプレハブのコピーか、プレハブが null の場合は空のゲームオブジェクトをインスタンス化します。

AR Tracked Image Manager と Tracked Image Prefab フィールド
AR Tracked Image Manager コンポーネントと Tracked Image Prefab フィールド

インスタンス化したゲームオブジェクトには、そのタイプのトラッカブル用に ARTrackable コンポーネントが必要なので、プレハブが null である場合は、マネージャーによって空のゲームオブジェクトが作成され、関連する ARTrackable コンポーネントのみが追加されます。同様に、null 以外のプレハブに関連する ARTrackable コンポーネントがない場合は、マネージャーによって追加されます。