AR data flow

この記事では EasyAR Sense の data flow について説明します。EasyAR Sense はコンポーネント化された API を使用し、コンポーネント間は data flow によって接続されます。

入出力データ

fundamentals dataflow input output

InputFrame: input frame。image、camera parameters、timestamp、world coordinate system に対する camera transform、tracking status を含みます。このうち camera parameters、timestamp、world coordinate system に対する camera transform、tracking status は optional ですが、特定の algorithm components は input に特定の要件を持ちます。

OutputFrame: output frame。input frame と synchronous processing components の output results を含みます。

FeedbackFrame: feedback frame。1 つの input frame と 1 つの historical output frame を含み、ImageTracker などの feedback-style synchronous processing components で使用されます。

Camera components

CameraDevice: Windows、Mac、iOS、Android 上の default camera。

ARKitCameraDevice: iOS 上の ARKit default implementation。

ARCoreCameraDevice: Android 上の ARCore default implementation。

MotionTrackerCameraDevice: motion tracking を実装し、multi-sensor fusion によってデバイスの 6DoF coordinates を計算します。(Android のみ)

ThreeDofCameraDevice: default camera に 3DoF orientation を追加します。

InertialCameraDevice: default camera に 3DoF orientation と inertial estimation に基づく plane translation を追加します。

custom camera device: custom camera implementation。

Algorithm components

Feedback-style synchronous processing component: 各 camera image frame に対して result を出力する必要があり、相互干渉を避けるため前の frame の processing result が必要です。

ImageTracker: 平面画像の検出とトラッキングを実装します。
ObjectTracker: 3D オブジェクトの検出とトラッキングを実装します。

同期処理コンポーネント: 各フレームでカメラ画像に追従して結果を出力する必要があります。

SurfaceTracker: 環境表面のトラッキングを実装します。
SparseSpatialMap: sparse spatial map を実装し、物理空間をスキャンしながら点群マップを生成し、リアルタイムローカリゼーションを行う機能を提供します。
MegaTracker: Mega 空間ローカリゼーションを実装します。

非同期処理コンポーネント: 各フレームでカメラ画像に追従して結果を出力する必要はありません。

CloudRecognizer: cloud recognition を実装します。
DenseSpatialMap: dense spatial map を実装し、collision や occlusion などの効果の実装に使用できます。

コンポーネントの availability チェック

すべてのコンポーネントには isAvailable 関数があり、そのコンポーネントが利用可能かどうかを判断できます。

コンポーネントが利用できない場合には、次のようなものがあります。

現在の operating system に実装されていない。
コンポーネントが必要とする dependencies が存在しない。例: ARKit、ARCore。
現在の version (variant) にコンポーネントが存在しない。たとえば一部の軽量版では特定の機能が存在しない。
現在の License ではコンポーネントを利用できない。

コンポーネントを使用する前に、必ず利用可能か判断し、対応する fallback または prompt を行ってください。

Data flow

コンポーネントの接続方法は次の図のとおりです。

fundamentals dataflow

input が feedback frame となる特殊な使い方があります。次の図のとおりです。

fundamentals dataflow feedback

Data flow helper classes

data flow の送信ポートと受信ポートです。各コンポーネントはこれらのポートを含む必要があります。

SignalSink / SignalSource: データなしの信号を受信/送信します。
InputFrameSink / InputFrameSource: InputFrame を受信/送信します。
OutputFrameSink / OutputFrameSource: OutputFrame を受信/送信します。
FeedbackFrameSink / FeedbackFrameSource: FeedbackFrame を受信/送信します。

data flow の分岐と結合

InputFrameFork: 1 つの InputFrame を複数の並列出力に分割します。
OutputFrameFork: 1 つの OutputFrame を複数の並列出力に分割します。
OutputFrameJoin: 複数の OutputFrame を 1 つに結合し、すべての結果を Results に結合します。複数の入力接続は、データが流入している間に接続しないでください。そうしないと出力できない状態になる可能性があります。Camera 起動前に data flow 接続を完了することを推奨します。
FeedbackFrameFork: 1 つの FeedbackFrame を複数の並列出力に分割します。

data flow のスロットリングとキャッシュ

InputFrameThrottler: InputFrame を受信して送信しますが、一度に 1 つだけ送信します。トリガー信号を受信した後にのみ次の InputFrame を送信します。複数の InputFrame を受信した場合、後続の InputFrame が前の InputFrame を上書きする可能性があります。
OutputFrameBuffer: OutputFrame を受信してキャッシュし、ユーザーのポーリングを待ちます。OutputFrame を受信したときに信号を送信できます。
OutputFrameBuffer が送信する信号を InputFrameThrottler に接続すると、スロットリングプロセス全体が完了します。

data flow の変換

InputFrameToOutputFrameAdapter: InputFrame を直接 OutputFrame にラップし、レンダリング表示に使用できます。
InputFrameToFeedbackFrameAdapter: InputFrame と FeedbackFrame を FeedbackFrame にラップし、フィードバック式同期処理コンポーネントに使用できます。

InputFrame 数の制限

CameraDevice は bufferCapacity を設定できます。これは出力する InputFrame の最大数です。現在の default 値は 8 です。

custom camera は BufferPool を使用して実装できます。

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

InputFrame の数が不足すると、data flow が詰まり、rendering が止まる可能性があります。

InputFrame の数が不足すると、初回起動時には rendering が止まらないが、background へ切り替えた後、または各コンポーネントを pause/start した後に rendering が止まる場合もあります。テストではこの状況を必ずカバーしてください。

接続と切断

data flow の実行中に接続や切断を行うことは推奨されません。

runtime 中に接続または切断が必要な場合は、cut edge (この edge を取り除くと data flow が 2 つに分かれる edge) でのみ行える点に注意してください。cycle 内の edge (ここでの cycle は data flow を undirected graph として見たとき edge が構成する cycle)、OutputFrameJoin の input、または InputFrameThrottler の sideInput では行えません。そうしないと、data flow が OutputFrameJoin や InputFrameThrottler などの nodes で詰まり、output できない状態になる可能性があります。

algorithm components にはすべて start/stop 機能があります。stop 時には frames は処理されませんが、結果を持たない状態でコンポーネントから引き続き出力されます。