移行ガイド
このガイドでは、AR Foundation 3.x と 4.x の違いについて説明します。
カメラとトラッキングノードの選択
以前のバージョンの AR Foundation では、パススルー映像に使用するカメラテクスチャを提供するカメラを明示的に選択することはできませんでした。また、目的のトラッキングの種類 (例えば、3 自由度または 6 自由度) を指定することもできませんでした。AR Foundation 4 では、以下のことが可能になりました。
- 特定のカメラを明示的にリクエストできます。AR Foundation では、"ワールドフェイシング" カメラと "ユーザーフェイシング" カメラが区別されます。スマートフォンでは、それぞれ背面カメラと自撮りカメラに対応します。
- トラッキングの種類を明示的にリクエストできます。
以前のバージョンの AR Foundation では、これは暗黙的な選択でした。例えば、顔検出を有効にすると、ユーザーフェイシングカメラを使用する 3 DOF (回転のみ) セッションを取得する可能性がありました。
ARKit 3 では、以前のバージョンの AR Foundation では表現できなかった動作モードが追加されました。具体的には、ARKit 3 では、ユーザーフェイシングカメラを使用してフェイストラッキングを実行する際に、3 DOF (degrees of freedom、自由度) と 6 DOF の両方のトラッキングがサポートされます。また、映像フィードにワールドフェイシングカメラを使用するだけでなく、ユーザーフェイシングカメラを使用してフェイストラッキングを実行するモードもサポートされます。
以下の表は、AR Foundation 3 で提供されるフェイストラッキングのサポートを示しています。
| 3 DOF | 6 DOF | |
|---|---|---|
| ユーザーカメラ | ✓ | |
| ワールドカメラ | ✓* |
* これは、ワールドフェイシングカメラを必要とする別の機能 (平面検出など) を有効にした場合にのみ利用可能でした。
以下の表は、ARKit3 のサポート状況を示しています。
| 3 DOF | 6 DOF | |
|---|---|---|
| ユーザーカメラ | ✓ | ✓ |
| ワールドカメラ | ✓ |
ご覧のとおり、6 DOF トラッキングでユーザーフェイシングカメラを使用することはできず、ワールドフェイシングカメラでフェイストラッキングを使用することは困難でした。
すべての機能を同時に使用できるわけではありません。例えば、ARCore では、顔検出と平面検出は相互に排他的な機能です。つまり、両方を同時に使用することはできません。ARKit では、これはハードウェアによって異なります。ただし、機能の特定の組み合わせを有効にした場合にどうなるかを知る方法はありませんでした。ワールドフェイシングカメラを使用したフェイストラッキングには、新しい iOS デバイスでのみ利用可能な特定のハードウェアが必要であるため、一般的な方法でサポートの有無を照会することができませんでした。
設定セレクター
この問題を解決するために、個々の動作モード ("設定記述子") を列挙し、その機能のリストを表示するメソッドが追加されました。設定記述子のすべての機能を現在のデバイスで同時に使用できます。
AR Foundation 4 では、現在リクエストされている機能セット (例: "オートフォーカス"、"平面検出"、および "顔検出") を使用し、使用できる最適な設定記述子を選択する "設定セレクター" の概念も導入されています。これにより、特定の機能セットを有効にする前に、それを有効にした場合にどうなるかを照会することも可能になっています。
デフォルトの設定セレクターでは、リクエストされた機能を最も多くサポートする設定が選択されますが、独自のロジックを実行するカスタム設定セレクターを実装することもできます。ARSubsystems パッケージの XRSessionSubsystem.configurationChooser を参照してください。
既存のプロジェクトの適応
ここでの互換性に影響する変更は、主に動作に関するものです。以前のバージョンでは、フェイストラッキングが他の機能よりも優先される傾向があったため、フェイストラッキングを有効にすると、3 DOF のユーザーフェイシングカメラ体験が提供されていました。現在は明示的に指定する必要があり、デフォルトモードは 6 DOF のワールドフェイシングになっています。これにより、フェイストラッキングを使用する以前のアプリケーションは、以前と同様に動作しない可能性があります。同じ結果を得るには、フェイストラッキングを有効にするだけでなく、カメラとトラッキングモードを指定することも必要になる場合があります。設定を選択する際にトラッキングが考慮されないことを意味する "don't care" モードもあります。
AR Foundation 4 では、ARCameraManager (シーン内のカメラ上のコンポーネント) によって、リクエストされるハードウェアカメラが制御され、ARSession コンポーネントによって、リクエストされるトラッキングモードが制御されます。また、これらのモードの新しいスクリプティング API も用意されています。
リクエスされたモードと実際のモード
以前のバージョンの AR Foundation では、いくつかの機能に単純なゲッターとセッターがありました。例えば、ARCameraManager には設定可能な autoFocusMode プロパティがありました。ただし、このプロパティでは、リクエストされたものと実際のモードが区別されませんでした。現在の状態でオートフォーカスモードがサポートされていない場合があります (例えば、ARKit の ARFaceTrackingConfiguration はオートフォーカスをサポートしていません)。
AR Foundation 3 は、そのようなプロパティの処理に一貫性がありませんでした。一部のプロパティにはセッターしかなく、ゲッターを持つプロパティでは、リクエストされたものを返すゲッターもあれば、基盤となるプラットフォーム SDK に照会して実際の値を返すゲッターもありました。
AR Foundation 4 では、これが明示的になりました。パラメーターに "リクエスト" プロパティと "実際" プロパティが追加されました。"リクエスト" プロパティは取得可能かつ設定可能ですが、"実際" プロパティは読み取り専用です。"実際" プロパティでは、リクエストされたものだけでなく、基盤となる SDK で実際に有効になっているものが示されます。
| コンポーネント | 以前 | リクエスト | 実際 |
|---|---|---|---|
| ARCameraManager | autoFocusMode |
autoFocusRequested |
autoFocusEnabled |
| ARCameraManager | lightEstimationMode |
requestedLightEstimation |
currentLightEstimation |
| ARCameraManager | -- | requestedFacingDirection |
currentFacingDirection |
| ARSession | -- | requestedTrackingMode |
currentTrackingMode |
| ARSession | matchFrameRate |
matchFrameRateRequested |
matchFrameRateEnabled |
| ARHumanBodyManager | humanBodyPose2DEstimationEnabled |
pose2DRequested |
pose2DEnabled |
| ARHumanBodyManager | humanBodyPose3DEstimationEnabled |
pose3DRequested |
pose3DEnabled |
| ARHumanBodyManager | humanBodyPose3DScaleEstimationEnabled |
pose3DScaleEstimationRequested |
pose3DScaleEstimationEnabled |
| ARFaceManager | maximumFaceCount |
requestedMaximumFaceCount |
currentMaximumFaceCount |
| AROcclusionManager | humanSegmentationDepthMode |
requestedHumanDepthMode |
currentHumanDepthMode |
| AROcclusionManager | humanSegmentationDepthMode |
requestedHumanStencilMode |
currentHumanStencilMode |
| ARPlaneManager | planeDetectionMode |
requestedPlaneDetectionMode |
currentPlaneDetectionMode |
| ARTrackedImageManager | maxNumberOfMovingImages |
requestedMaxNumberOfMovingImages |
currentMaxNumberOfMovingImages |
| AREnvironmentProbeManager | automaticPlacement |
automaticPlacementRequested |
automaticPlacementEnabled |
| AREnvironmentProbeManager | environmentTextureHDR |
environmentTextureHDRRequested |
environmentTextureHDREnabled |
XRCameraImage から XRCpuImage に名前を変更
パススルー映像を表す Texture2D は、通常、GPU テクスチャです。コンピュータービジョンアプリケーションや他の CPU 側処理アプリケーションは、CPU 上の Raw ピクセルにアクセスする必要があります。しかし、ピクセルを読み取るための通常の Texture2D API は、最初に GPU からデータが転送されない限り機能しないため、非効率的になる可能性があります。ARCore や ARKit などの AR フレームワークでは、非効率な GPU リードバックなしで CPU 上の raw ピクセルデータにアクセスすることができ、AR Foundation はこのデータを XRCameraImage として提供していました。
この "カメラ画像" API は引き続き存在しますが、一般化され、XRCameraImage から XRCpuImage に名前が変更されました。API はほぼ同じですが、AROcclusionManager によって提供される人物の深度バッファや人物のステンシルバッファなど、他の種類の画像データの読み取りに使用できるようになっています。
変更点
XRCameraImageが XRCpuImage になりました。XRCameraImage.FormatSupportedは、カメラ画像を指定の TextureFormat に変換できるかどうかを判断する静的メソッドでした。XRCpuImageはさまざまな種類の画像を処理できるため、このメソッドはXRCpuImageのインスタンスメソッドになりました。ARCameraManager.TryGetLatestImage(out XRCameraImage)が TryAcquireLatestCpuImage(out XRCpuImage) になりました。パラメーターがXRCameraImageからXRCpuImageに変更され、メソッド名がXRCpuImageリソースの生存期間と呼び出し元の責任をより正確に示しています (ただし、動作は変更されていません)。- AROcclusionManager に以下の 2 つの新しいメソッドが追加されました。
サンプル
AR Foundation Samples GitHub リポジトリの "CpuImages" サンプル は、CPU 画像 API の使用方法を示しています。このサンプルが更新され、カラーカメラ画像、人物の深度画像、人物のステンシル画像が追加されました。
XR Plug-in Management
AR Foundation は、XR Plug-in Management に依存するようになりました。これは、編集とランタイムの両方に影響します。
編集時の設定
AR Foundation でプロバイダープラグインを使用するには、プロバイダープラグインを有効にしておく必要があります。XR Plug-in Management ウィンドウ (メニュー: Edit > Project Settings > XR Plug-in Management) から、ターゲットプラットフォームごとに特定のプラグインプロバイダーを有効にすることができます。
ランタイム
以前のバージョンの AR Foundation では、各マネージャーコンポーネント (ARSession、ARPlaneManager、ARPointCloudManager など) によって各サブシステムのライフサイクルが完全に制御されていました (サブシステムは、各プロバイダーパッケージによって実装されるプラットフォームに依存しないインターフェースです)。
AR Foundation 4 では、XR Plug-in Management によってサブシステムの作成と除去が制御されます。AR Foundation のコンポーネントは、これまでと同様にサブシステムを開始および停止しますが、サブシステムの作成と除去は行いません。
| MonoBehaviour イベント | サブシステム |
|---|---|
| OnEnable | 開始 |
| OnDisable | 停止 |
これは、例えば、ARSession コンポーネントを除去すると、セッションは一時停止されますが、除去されないことを意味します。例えば、2 つの AR シーンを切り替えるときには、これが望ましいと考えられます。ただし、これは以前の動作から変更されています。ARSession を除去して再作成すると、同じセッションが一時停止され、再開されます。
セッションを完全に除去する場合は、サブシステムを除去する必要があります。そのためには、XR Plug-in Management から XRLoader に対して Deinitialize を呼び出します。
AR Foundation には、これを容易にするための新しいユーティリティである LoaderUtility が用意されています。
LoaderUtility.Initialize();
または
LoaderUtility.Deinitialize();
を呼び出すと、それぞれサブシステムが作成または除去されます。