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 的時候，幀將不會被處理，但仍然會從組件中輸出，只是不帶有結果。