AR 資料流

本文介紹了 EasyAR Sense 中的資料流。EasyAR Sense 中使用元件化 API，元件之間透過資料流來連接。

輸入輸出資料

fundamentals dataflow input output

InputFrame：輸入幀。包含影像、camera 參數、時間戳、攝影機相對於世界座標系的變換和跟踪狀態。其中，camera 參數、時間戳、攝影機相對於世界座標系的變換和跟踪狀態均為可選，但特定的演算法元件會對輸入有特定的要求。

OutputFrame：輸出幀。包含輸入幀和同步處理元件的輸出結果。

FeedbackFrame：反饋幀。包含一個輸入幀和一個歷史輸出幀，用於 ImageTracker 等反饋式同步處理元件。

Camera元件

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 函式，可用於判斷該元件是否可用。

元件不可用的情況有

當前作業系統上沒有實作。
元件所需要的依賴不存在，例如 ARKit、ARCore。
元件在當前版本（variant）上不存在，例如一些精簡版本中某些功能不存在。
元件在當前 License 下不可用。

使用元件之前務必要判斷元件是否可用，並進行相應的 fallback 或者提示。

資料流

元件的連接方式如下圖所示。

fundamentals dataflow

有一種特殊的輸入為反饋式幀的用法，如下圖所示。

fundamentals dataflow feedback

資料流輔助類

資料流的發出和接收端口，各元件需要包含這些端口

SignalSink / SignalSource：接收/發出一個訊號(無資料)。
InputFrameSink / InputFrameSource：接收/發出一個 InputFrame。
OutputFrameSink / OutputFrameSource：接收/發出一個 OutputFrame。
FeedbackFrameSink / FeedbackFrameSource：接收/發出一個 FeedbackFrame。

資料流的分支與合併

InputFrameFork：將一個 InputFrame 分成多個並行發出。
OutputFrameFork：將一個 OutputFrame 分成多個並行發出。
OutputFrameJoin：將多個 OutputFrame 合併成一個，並將所有的結果合併到 Results 中。需要注意其多個輸入的連接不應該在有資料流入的同時進行，否則可能會陷入不能輸出的狀態。（推薦在 Camera 啟動之前完成資料流連接。）
FeedbackFrameFork：將一個 FeedbackFrame 分成多個並行發出。

資料流的限流與快取

InputFrameThrottler：接收並發出 InputFrame，但一次只發出一個，只有在接收到一個觸發訊號後才會發出下一個 InputFrame，接收到多個 InputFrame 時，後續的 InputFrame 可能會覆蓋前面的 InputFrame。
OutputFrameBuffer：接收 OutputFrame 並快取，等待使用者輪詢，接收到 OutputFrame 的時候可以發出一個訊號。
將 OutputFrameBuffer 發出的訊號接到 InputFrameThrottler 上，即可完成整個限流過程。

資料流的轉換

InputFrameToOutputFrameAdapter：可以將一個 InputFrame 直接包裝成 OutputFrame，用於渲染顯示。
InputFrameToFeedbackFrameAdapter：可以將一個 InputFrame 和一個 FeedbackFrame 包裝成 FeedbackFrame，用於回饋式同步處理元件。

InputFrame數量的限制

CameraDevice 可以設定 bufferCapacity，即發出 InputFrame 的最大數量，當前的預設值為8。

自訂攝影機可以使用 BufferPool 實作。

各元件需要的 InputFrame 數量，參考各元件的 API 文件。

如果 InputFrame 數量不足，可能造成資料流卡住，導致渲染卡住。

如果 InputFrame 數量不足，也可能出現第一次啟動渲染不卡住但切換到後台或暫停/啟動各元件後渲染卡住的情況，測試時需要注意覆蓋。

連接和斷開連接

不推薦在資料流執行過程中連接和斷開連接。

若需要在執行過程中進行連接和斷開連接，需要注意只能在割邊（去掉這條邊後資料流會一分為二）上進行，不能在環的邊（這裏的環指的是將資料流看作無向圖時邊構成的環）上、 OutputFrameJoin 的輸入或者 InputFrameThrottler 的 sideInput 上進行，否則可能會陷入資料流卡在 OutputFrameJoin 和 InputFrameThrottler 等結點無法輸出的狀態。

演算法元件均有 start/stop 功能，在 stop 的時候，幀將不會被處理，但仍然會從元件中輸出，只是不帶有結果。