ハンドヘルド AR テンプレート テクニカル リファレンス

ハンドヘルド AR テンプレートの主要機能が実装される場所とその機能に関するリファレンス ページ

Windows
MacOS
Linux

ハンドヘルド AR テンプレートは、iOS および Android デバイス向けの拡張現実プロジェクトを作成するためのスタート ポイントになるものです。「ハンドヘルド AR テンプレート クイックスタート」ではテンプレートを設定してモバイル デバイスにデプロイする手順を記載していますが、このガイドでは、テンプレートが機能する仕組み、主要機能が実装される場所、および機能を変更する方法についてより技術的なガイダンスを提供します。

基礎原理

ハンドヘルド AR テンプレートには、次の 2 つの部分の表示が含まれます。

  • ユーザーのカメラのフィード

  • バーチャル シーン。これは、Unreal Engine の 3D ワールドに存在します。

ユーザーが AR セッション を開始すると、ユーザーのカメラ フィードが自動的に取得され、同時にそのフィードにバーチャル シーンのレンダリングが重ねられます。ユーザーを表現するものとして、 ポーン にバーチャル シーン内でオブジェクトとインタラクションを行うためのロジックが含められています。これには、最初のスキャンによって定義されるプレーンや配置可能なオブジェクトなどがあります。この複合ディスプレイに HUD がオーバーレイで表示され、構成オプションやその他のツールを利用できます。

ハンドヘルド AR テンプレートのユーザー ジャーニーの詳細については、「ハンドヘルド AR テンプレート クイックスタート」を参照してください。

アプリケーション フロー

ハンドヘルド AR テンプレートは、エディタとアプリケーション起動時の両方で、 HandheldARBlankMap を直接開きます。このマップは、モバイル デバイスの設定時にドキュメンテーションをポイントするためのヘルパー アクタを除き、アクタの機能を利用しません。その主な機能は、ゲーム モードを BP_ARGameMode にオーバーライドし、アプリケーションの実行とバーチャル シーンの設定を行う ゲーム フレームワーク クラスをアプリケーションで使用することです。

The template project displaying HandheldARBlankMap

BP_ARGameMode は、 BP_ARPawn を使用してプレイヤーを起動します。これにより、 BP_MainMenu をユーザーのビューポートに追加することで UI の初期化を行います。BP_MainMenu が設定されると、環境のスキャンを開始するようユーザーにプロンプトが表示されます。これによって AR セッション が開始され、ユーザーのカメラ フィードが表示されます。続いて、環境内の利用可能な平らなサーフェスに基づいて一連のプレーンを定義するよう BP_ARPawn に指示します。

BP_ARPawn では、単純なステート マシンを使用し、アプリケーションの現在のユーザー ジャーニーのステップを追跡します。このステート マシンは、以下の要因を追跡します。

  • ユーザーは環境をスキャンし、バーチャル シーン内にプレーンを設定したか。

  • ユーザーはインタラクションを行うプレーンを選択したか。

  • ユーザーはその選択したプレーンにオブジェクトを配置したか。

ユーザー ジャーニーでのユーザーの進捗状況に基づき、ポーンは、入力に対するアプリケーションの応答方法に変更を加え、ユーザーにセットアップ ステップの概要を説明するプロンプトを HUD 内にトリガーします。

アクタ

AR ポーン

ハンドヘルド AR テンプレートは、 BP_ARPawn というカスタムのポーンを使用します。このポーンは、バーチャル シーンの初期化、構築、および更新とユーザー入力の処理を行います。

初期化

AR ポーンは、BeginPlay のユーザーのビューポートに BP_MainMenu を追加します。これにより、BP_MainMenu は、現在のアプリケーションの状態に基づいて AR シーンの設定とプロンプトの処理を行います。

ステート コントロール

AR ポーンは、単純なステート マシンを使用し、上記セクションで概要を説明したユーザー ジャーニーの異なるステップをサポートします。このステートは、 State カテゴリの一連のブール値によって制御されます。

The booleans that control the state machine for this template

以下のような数多くのさまざまなデバッグ ドロワーがあります。

  • ScanningIsDone: 最初のスキャニング プロセスが完了し、バーチャル シーン内にプレーンが配置されています。

  • PlaneIsSelected: ユーザーがプレーンを選択しました。

  • ObjectIsPlaced: ユーザーが仮想オブジェクトをプレーンに配置し、インタラクションが可能になっています。

ユーザーが HUD からのプロンプトに従うと、これらは false から true に変更され、ユーザー ジャーニーの次のステップにアプリケーションが移行するようトリガーされます。タッチ入力の処理時、および Tick イベントによるシーンの更新処理時に、ポーンはこれらを参照します。

カメラ深度シーン テクスチャ

AR ポーンは、バーチャル シーン内でのオブジェクト配置に使用されるカメラ深度シーン テクスチャの取得も実行します。この情報は、ユーザーがカメラを使用するためのアプリケーションのアクセス許可を付与するとすぐに取得されますが、これはアプリケーションによる AR スキャンの完了前です。深度テクスチャは CameraDepthTexture に格納されます。続いて、ポーンによるプレーンのビジュアル更新時に Create Plane Candidate 関数内でこれが使用されます。CameraDepthTexture が利用できない場合、 CameraDepthFallback が代わりに使用されます。

ライト強度の推定

Tick イベント中に、AR ポーンは Feed Light Estimate 関数を呼び出します。これが現在のライト推定データを AR セッションから取得します。このデータが有効な場合、カメラ フィードに基づくカラーおよび強度設定でマップ内のディレクショナル ライトとスカイライトを更新します。これにより、ユーザーの実世界環境におおよそ一致する、バーチャル シーン内のライティングが作成されます。

AR プレーンの作成

AR セッションによる環境のスキャニングが完了すると、AR ポーンはバーチャル シーン内の PlaneCandidate アクタの更新を開始します。このプロセスでは、環境内で追跡されているオブジェクトが有効な AR プレーン ジオメトリ にフィットしているかどうかがチェックされます。通常、デバイスのセンサーは 5 ~ 20 個のオブジェクトを検出できます。

その後、ポーンは Create Plane Candidate を呼び出して BP_Plane アクタをスポーンし、バーチャル シーン内の適切な場所に配置します。プレーン候補は 1 秒に 1 回更新されます。画面の視覚的な複雑さを軽減するため、所定のタイミングで AR ポーンが 1 つのプレーン候補のみを追跡し、AR セッションによって最も近いオブジェクトの追跡が優先されるようにこのプロセスを設定することができます。ユーザーが環境内を移動すると、さまざまなプレーン候補が現れたりなくなったりします。

ユーザーがプレーン候補を選択すると、代わりに BP_Plane が SelectedPlane としてロックされます。

ジェスチャーの処理とバーチャル シーンの操作

AR ポーンは入力を利用する唯一のブループリントであるため、すべてのジェスチャを認識する必要があります。

InputTouch イベントは、ユーザーがプレーンを選択しているかどうかに応じて、プレーンを選択するため、または仮想オブジェクトを配置するための単一タッチ入力を処理します。ユーザーが仮想オブジェクトを選択するまで 2 本指のジェスチャやスワイプは利用できないため、このタッチ入力は非常に簡単であり、特別な入力アクションを必要としません。

The InputTouch Event

ユーザーがプレーンの配置と仮想オブジェクトの選択の両方を行うと、入力は OneFingerAction 入力アクションおよび TwoFingerAction 入力アクションに加え、 TwoFingerMapping という入力軸によって処理されます。これらは、 [Project Settings (プロジェクト設定)] > [Input (入力)] の入力バインディングで定義されます。

Input Actions displayed in the Project Settings menu

OneFingerAction 入力アクションおよび TwoFingerAction 入力アクションは、AR ポーンのイベント グラフでイベントを使用して表現されます。これらのイベントは、プレーンやオブジェクトとインタラクションを行っても関数をトリガーしません。代わりに、一般的な入力の処理時に AR ポーンが適切なジェスチャ タイプを選択するために使用するデータを記録します。

Input Actions displayed in the AR Pawn's blueprint graph

Tick イベントは Reset Recognized Gesture を呼び出して前のジェスチャに関する情報をクリーンアップし、 One Finger Gesture Recognition 関数および Two Finger Gesture Recognition 関数を呼び出して入力アクション イベントから収集したデータを処理します。これには、タッチ入力の位置、方法、移動距離のデルタが含まれます。

これらの関数は、 Current Transformation という適切なジェスチャの列挙を設定します。続いて、Current Transformation のスイッチが、選択された配置可能オブジェクトにTranslate 関数、Rotate 関数、または Scale 関数を使用するかどうかを選択します。このオブジェクト自体が、これらのトランスフォーム関数を処理します。

Gesture controls displayed in the AR Pawn's blueprint graph

配置可能オブジェクト

An example of a placeable object

BP_Placeable ブループリントは、プレーンを含むハンドヘルド AR テンプレートのすべての配置可能オブジェクトの基本クラスです。配置可能な仮想オブジェクトに関連する、ビジュアル、トランスフォーメーション ロジック、およびウィジェット コンポーネントを含む HUD インタラクション ロジックのすべてをカプセル化します。BeginPlay では、 Assign Product Asset 関数で作成する製品のタイプに基づいて配置可能オブジェクトがアセットを選択します。選択されるモデルは、テンプレートの設定時に選択したカテゴリによります。

アプリケーション カテゴリ

モデル

Games

Games placeable object

自動車、プロダクトデザイン、製造

Automotive placeable object

建築、土木、建設

Architectural placeable object

ビジュアルを制御する

配置可能オブジェクトは、 Set Visuals 関数を使用してモデルのマテリアルと、それらとともに表示される UI ウィジェットの両方の表示を制御します。この関数は、 Set Placeable PositionSet Placeable Rotation 、および Set Placeable Scale から呼び出されます。

インタラクションがアクティブな場合、Tick イベントは Update Interaction を呼び出します。この関数は、ユーザーの移動、回転、またはスケーリングなどに基づいて、配置可能オブジェクトの UI ウィジェットを新しい情報で更新します。各トランスフォーメーションに適切なテキストを取得するための、複数のユーティリティ関数があります。

AR プレーンにオブジェクトを配置する

AR ポーンは、BP_Placeable アクタを Input Touch イベントからスポーンし、 Placeable Object 変数に割り当てます。

AR プレーン

ハンドヘルド AR テンプレートは、BP_Plane アクタを使用してバーチャル プレーンを表現します。これらは、 Update Plane Candidate 関数および Create Plane Candidate 関数を使用し、AR ポーンによって作成されます。さらに Create Plane Candidate は Initialize Plane を呼び出し、これによって BP_Plane のマテリアルおよびカラーの設定が処理されます。

BP_Plane にアタッチされるスタティック メッシュは、2 つの三角ポリゴンで構成される単一のプレーンであり、複雑なコリジョンが有効になっていて Collision PresetsBlockAllDynamic に設定されています。これにより、どのようなタイプのトレースを使用しているプレーンのサーフェスも検出できます。

BP_Plane アクタのデフォルトのステートは、未選択のステートです。このステートでは、マテリアル インスタンスとして DM_Scan が使用され、デバイスが現在スキャンしている環境を示す波が表示されます。

BP_Plane using DM_Scan as its material

Get Platform Scan Material 関数は、ユーザーが Android デバイスなのか iOS デバイスなのかによって DM_Scan を ScanMaterial01 または ScanMaterial02 のいずれかに設定します。

Initialize Plane 関数は、DM_Scan を視覚的にカットして環境により良くフィットするように AR ポーンによって取得されたカメラ シーン深度を使用しようとします。また、 Get Plane Color を使用して AR Pawn ポーンにカラーを設定します。この関数は、AR ジオメトリ インデックスを取得し、カラーを選択するためにそれを使用します。AR ツールキットによって環境内に新しいジオメトリが見つかった場合、カラーは変更される場合があります。

ユーザーがオブジェクトを配置するプレーンを選択すると、AR ポーンは BPPlane Is Selected イベント ディスパッチャーを呼び出します。このイベントは、メイン メニューでオブジェクトを配置ステートに切り替えるために使用されます。ユーザーがオブジェクトをプレーンに配置すると、プレーンは非表示になり、より没入感のある表示になります。理想的には、プレーンが表示されない場合でも、インタラクションが直感的と感じられるほど、プレーンはユーザーの環境内でスキャンされたオブジェクトに一致することが望ましいでしょう。

ユーザーが配置可能オブジェクトに対して変換関数を使用した場合、AR ポーンは Switch to Material Translate 関数を使用してプレーンのマテリアル インスタンスを DM_Plain に変更します。これにより、DM_Scan と比較すると邪魔になりにくいアウトラインが表示されます。そのため、ユーザーはオブジェクトを移動できる境界を確認しやすくなります。

HUD および UI ウィジェット

このセクションには、ハンドヘルド AR テンプレートの HUD を構成する要素のリファレンスを掲載しています。UI クラスの構成、およびスタイルやモードの変更などの主要機能の提供方法について以下で説明します。

UI スタイルと BP_StylizedUI

ハンドヘルド AR テンプレートのすべてのメニューは、BP_StylisedUI を親クラスとして使用します。このクラスは、Light、Dark、および Game テーマの間で UI スタイルを切り替えるのに必要な、すべての関数に関連するデータをカプセル化します。これらのテーマは DT_Styles データ テーブルに含まれており、このテーブルには共通する UI カラー、フォント、およびアイコンの情報が含まれています。

The DT_Styles data table

Get Style Data 関数は、現在選択されているスタイルに関する情報を取得し、その情報を他の関数で使用するために出力します。

An example of the Get Style Data function

BP_MainMenu は、 Call Switch Style 関数を使用して各サブメニューのスタイル切り替えをトリガーします。

The Call Switch Style function called from the main menu

これらは、UI を変更するためのイベントを、 Switch Style イベント ディスパッチャーにバインドします。このイベント ディスパッチャーは、BP_StylizedUI で定義されます。

Switch Style event dispatcher

UI_CapsuleButton などのその他のウィジェットは、独自の Change Style 関数を定義します。この関数は、親メニューから手動で呼び出されます。

Example of a manual change style function

この設計により、UI スタイル定義でデータ駆動型の方法を実現し、また UI スタイルやレイアウトの大規模な変更のサポートでも複製が確実に最小限で済むようになっています。

メイン メニュー

BP_MainMenu は、その他すべてのメニューのコンテナかつマネージャーとして機能します。AR ポーンによってビューポートに追加されると、その他すべてのメニューを初期化し、イベント ディスパッチャーをバインドし、ユーザー ジャーニーの特定のステップに対応するイベント ディスパッチャーもバインドします。また、ARセッションを開始します。スタイルに対して独自のビジュアル要素がないため、BP_StylizedUI の代わりにベースのユーザー ウィジェットクラスを拡張します。

初期化とイベントのバインド

On Initialized イベント中、メイン メニューは UI を初期化し、デフォルトの UI スタイルを Light に設定し、イベント ディスパッチャーをすべての UI の主要関数にバインドします。これらには、テンプレートのユーザー ジャーニーを通じた手順、最初のチュートリアルのポップアップのほか、スクリーンショット撮影フローまたは他のサブメニュー間の移動、設定変更の確認などが含まれます。

The On Initialized event in the Main Menu

これは高度に拡張されたイベント グラフですが、サブメニューのビジュアル要素とアプリケーションの主要機能を一体化する役割を果たすものと考えることができます。

AR セッションを開始する

AR セッションは、スキャンを開始する BP_StartMenu のボタンをユーザーが押すと起動します。

Starting the AR session

ステート変更を処理する

次に、メイン メニューの Tick 関数は、AR セッションが Running ステートになるのをリッスンします。これが発生すると、BP_StartMenu がスキャニング ステータスを開始するよう指示し、ステート変更をハイライトしやすくするための複数の外観の変更がトリガーされます。

State Changes tracked with Tick

同様に、Tick 関数はユーザーがオブジェクトの配置を開始するタイミングもリッスンしています。これらの変更は、AR ポーン内のステート マシンの変更に対応するものです。

サブメニュー

メイン メニューには、複数のサブメニューが組み込まれています。これらのメニューは主に、外観要素やレイアウトを処理し、内部のスタイリング目的の機能を除き、イベント ディスパッチャーが自身の機能を処理します。すべてのサブメニューは、BP_StylizedUI に基づいて、スタイル変更をサポートするための共通関数を提供します。

Start メニュー

The Start Menu as it appears in UMG

BP_StartMenu は、ユーザーがアプリケーションを起動し、ユーザーをユーザー ジャーニーにガイドするオーバーレイおよびプロンプトを処理する際に最初に表示されるメニューで、ステップの移行時にフィードバックを提供します。この [Start] メニューは画面全体にオーバーレイ表示され、ユーザー ジャーニーの異なる各ステートのための個別のオーバーレイを含みます。たとえば、ユーザーが環境内のプレーンをスキャン中の場合、[Start] メニューには UI_Scanning が表示されます。一方で、プレーンを選択し、プレーンにオブジェクトを配置する準備が完了すると、 UI_PlaceObject が表示されます。

Bottom メニュー

The Bottom Menu as it appears in UMG

ユーザーがユーザー ジャーニーのすべてを完了し、オブジェクトを配置すると、画面下部に BP_BottomMenu が表示され、[Options (オプション)] メニュー、[Info (情報)] メニュー、および Snapshot 関数と Reset 関数にアクセスする手段が提供されます。

[Bottom] メニューには、Light および Dark テーマで使用される、水平レイアウト用の独立したオーバーレイのほか、Game テーマで使用される丸いレイアウトが含まれています。これらのレイアウトのバージョンのボタンは、いずれも同じカスタム イベントをバインドして重複を回避します。

Binding an event for two different versions of the same button

オプション メニュー

The Options Menu as it appears in UMG

BP_OptionMenu は、ユーザーが [Bottom] メニューで [Options] ボタンをタップしたときに表示されるメニューです。このメニューでは、UI スタイルを切り替える機能など、いくつかの構成オプションを利用できます。このメニューの UI ボタンはメイン メニューの関数にバインドされており、AR ポーンや、UI のその他の部分でトリガーする必要が生じる可能性のある、その他の関数の可視性を向上します。

An example of calling a function from the Player Pawn with an event dispatcher

Info メニュー

The Info Menu as it appears in UMG

BP_InfoMenu は、ユーザーが [Bottom] メニューで [Info] ボタンをタップしたときに表示されるメニューです。このメニューは、配置可能オブジェクトを操作するためのジェスチャを表示します。

ボタン

UI_CapsuleButton および UI_ToggleButton は、すべてのメニューに使用されます。これらは、カスタムで作成することで、スタイル変更や切り替えなどの特定のボタンのビヘイビアを含む、共通する幅広い関数をサポートします。

タグ
Unreal Engine のドキュメントを改善するために協力をお願いします!どのような改善を望んでいるかご意見をお聞かせください。
調査に参加する
閉じる