Ar データフロー

この文書では、EasyAR Sense におけるデータフローについて説明します。EasyAR Sense ではコンポーネント化された API を使用し、コンポーネント間はデータフローで接続されます。

入力出力データ

fundamentals dataflow input output

InputFrame：入力フレーム。画像、カメラパラメータ、タイムスタンプ、ワールド座標系に対するカメラの変換、トラッキング状態を含みます。カメラパラメータ、タイムスタンプ、変換、トラッキング状態はオプションですが、特定のアルゴリズムコンポーネントは入力に特定の要件を持ちます。

OutputFrame：出力フレーム。入力フレームと同期処理コンポーネントの出力結果を含みます。

FeedbackFrame：フィードバックフレーム。入力フレームと過去の出力フレームを含み、ImageTracker などのフィードバック式同期処理コンポーネントで使用されます。

カメラコンポーネント

CameraDevice：Windows、Mac、iOS、Android 上のデフォルトカメラ。

ARKitCameraDevice：iOS 上の ARKit デフォルト実装。

ARCoreCameraDevice：Android 上の ARCore デフォルト実装。

MotionTrackerCameraDevice：モーション追跡を実装し、マルチセンサーフュージョンによりデバイスの 6DoF 座標を計算します（Android のみサポート）。

ThreeDofCameraDevice：デフォルトカメラに 3DoF の方向を追加します。

InertialCameraDevice：デフォルトカメラに 3DoF の方向と慣性推定に基づく平面の並進を追加します。

custom camera device：カスタムカメラ実装。

アルゴリズムコンポーネント

フィードバック式同期処理コンポーネント：カメラ画像ごとに結果を出力する必要があり、相互干渉を避けるために前フレームの処理結果を必要とします。

ImageTracker：平面画像の検出とトラッキングを実現します。
ObjectTracker：3D物体の検出とトラッキングを実現します。

同期処理コンポーネント：カメラ画像のフレームごとに結果を出力する必要があります。

SurfaceTracker：環境表面のトラッキングを実現します。
SparseSpatialMap：スパース空間マップを実現し、物理空間をスキャンしながら点群マップを生成し、リアルタイム位置推定を行う機能を提供します。
MegaTracker：Mega空間位置推定を実現します。

非同期処理コンポーネント：カメラ画像のフレームごとに結果を出力する必要はありません。

CloudRecognizer：クラウド認識を実現します。
DenseSpatialMap：密空間マップを実現し、衝突やオクルージョンなどの効果の実装に使用できます。

コンポーネントの可用性チェック

すべてのコンポーネントには isAvailable 関数があり、コンポーネントが使用可能か判断するために使用できます。

コンポーネントが利用できない状況：

現在の OS で実装されていない
コンポーネントに必要な依存関係（ARKit、ARCore など）が存在しない
現在のバージョン（variant）でコンポーネントが存在しない（例: 一部機能が存在しない軽量版）
現在のライセンスでコンポーネントが利用不可

コンポーネント使用前には必ず可用性を判断し、適切な代替手段（fallback）や通知を行ってください。

データフロー

コンポーネントの接続方法を下図に示します。

fundamentals dataflow

フィードバックフレームを入力とする特殊な使用法を下図に示します。

fundamentals dataflow feedback

データフロー補助クラス

データフローの送信ポートと受信ポート。各コンポーネントはこれらのポートを含む必要があります。

SignalSink / SignalSource：信号（データなし）の受信/発信。
InputFrameSink / InputFrameSource：InputFrame の受信/発信。
OutputFrameSink / OutputFrameSource：OutputFrame の受信/発信。
FeedbackFrameSink / FeedbackFrameSource：FeedbackFrame の受信/発信。

データフローの分岐とマージ

InputFrameFork：1つの InputFrame を複数に分岐し、並列に発信。
OutputFrameFork：1つの OutputFrame を複数に分岐し、並列に発信。
OutputFrameJoin：複数の OutputFrame を1つにマージし、全ての結果を Results に結合。複数の入力接続は、データが流入している最中に行うべきではないことに注意（出力不能状態に陥る可能性あり）。（カメラ起動前にデータフロー接続を完了することを推奨。）
FeedbackFrameFork：1つの FeedbackFrame を複数に分岐し、並列に発信。

データフローのスロットリングとバッファリング

InputFrameThrottler：InputFrame を受信・発信するが、一度に1つだけ発信。トリガー信号を受信した後で次の InputFrame を発信。複数の InputFrame を受信した場合、後続のフレームが前のフレームを上書きする可能性がある。
OutputFrameBuffer：OutputFrame を受信してバッファリングし、ユーザーのポーリングを待機。OutputFrame を受信したときに信号を発信可能。
OutputFrameBuffer からの信号を InputFrameThrottler に接続することで、スロットリングプロセス全体を完了できる。

データフローの変換

InputFrameToOutputFrameAdapter：InputFrame を直接 OutputFrame にラップし、レンダリング表示に使用。
InputFrameToFeedbackFrameAdapter：1つの InputFrame と1つの FeedbackFrame を FeedbackFrame にラップし、フィードバック型同期処理コンポーネントに使用。

InputFrame 数の制限

CameraDevice は bufferCapacity を設定でき、これは発行する InputFrame の最大数を表します。現在のデフォルト値は 8 です。

カスタムカメラは BufferPool を使用して実装できます。

各コンポーネントが必要とする InputFrame の数は、各コンポーネントの API ドキュメントを参照してください。

InputFrame の数が不足すると、データフローが詰まり、レンダリングが停止する可能性があります。

InputFrame が不足すると、初回起動時はレンダリングが停止しなくても、バックグラウンドへの切り替えやコンポーネントの一時停止/再開後にレンダリングが停止する場合があるため、テスト時にはこのケースをカバーする必要があります。

接続と切断

データフロー実行中の接続と切断は推奨されません。

実行中に接続と切断を行う必要がある場合は、切断可能なのは「橋渡しエッジ」（このエッジを削除するとデータフローが2つに分離する）のみであり、「ループエッジ」（データフローを無向グラフと見なした場合のループを構成するエッジ）、OutputFrameJoin の入力、または InputFrameThrottler の sideInput 上では行わないでください。そうしないと、OutputFrameJoin や InputFrameThrottler などのノードでデータフローが詰まり出力できない状態になる可能性があります。

アルゴリズムコンポーネントには start/stop 機能があり、stop 時にはフレームは処理されませんが、結果なしでコンポーネントから出力されます。