1什么是 FreeD 定位系統

FreeD 定位系統（通常稱為 FreeD 協議）是一種業界廣泛應用的攝像機追蹤數據通信協議，主要用于虛擬演播室（AR/VR）、電影虛擬制作等實時追蹤場景。在很多工業數字軟生項目中也有類似接收發送數據協同的需求，可以參考下面的流程作參考。

FreeD 主要傳遞包括攝像機三維位置（XYZ）、旋轉（Pitch、Yaw、Roll）、鏡頭參數（焦點、變焦）。

我們采取的協議包含 29 個字節的數據，其 FreeD 發送的定位設備一般是一個獨立于攝影機的組件，其實現原理大致分為紅外定位點，雙目攝像頭，多攝像頭等。包括著名的 Mosys、Redspy、HTC Vive Mars 等。FreeD 是一個通用的定位協議，常見的定位系統默認都支持 FreeD 協議。

2開始開發

首先創建一個插件，命名為omni.freed.livelink。具體步驟可參考：《NVIDIA Omniverse Extension 開發秘籍：Python/C++ 實戰，附完整代碼》

2.1 背景分析

首先找到 FreeD 的定義文檔，并且分析其協議 （https://www.manualsdir.com/manuals/641433/vinten-radamec-free-d.html?download），然后根據協議在 Omniverse Extension 編寫接收協議，且實時更新 Omniverse USD 的 Camera，讓 Omniverse 的 Camera 跟隨外部的相機定位系統實時同步更新，實現數字孿生效果。

*注：文本下面需要用到很多計算機編程開發的基礎知識。

2.2 開發解析

2.2.1 端口創建

FreeD 協議基于 UPD 協議傳輸，一般默認是廣播方式，接收的端口是 40000 (可以在相機定位設備里更改端口，或者進行點對點傳輸)。

_startUPDServe函數里面創建 Socket 端口（或者使用已有框架比如 python-osc）

2.2.2 協議解析

分析 FreeD 的協議，通用 FreeD 采用的是 Type D1 的數據格式，接收 29 個 Bytes。在文檔的第 30 頁，根據指引“Appendix”去看第 40 頁。

FreeD字段說明

再通過下圖更直觀地表達 FreeD 的 29 個字節所，按照文檔計算 Pan, Tilt, Roll 的數值。

*注：從網絡端口傳來的數據是大端格式， 并且如果是負數的話則需按照負數補碼來解析。

2.2.3計算 Yaw Pitch Roll：

旋轉 Pan,Tilt,Roll(Yaw Pitch Roll)的角度定義

2.2.4計算位置 X, Y, Z：

同理按照文檔計算 Translate 的 X Y Z 數據。

位置信息 X,Y,Z 的定義

按照定義給出代碼。

Zoom 和 Focus 和鏡頭文件相關，由于每一個鏡頭文件對應的解析都不太一樣，這里就不再詳細判斷。

最后把解析得到的 Yaw Pitch Roll 和 X，Y，Z 的數據更新到我們綁定的 Camera 上面實時更新。

3創建 Event 事件

3.1 發現問題

在子線程運行的時候發現無法對 USD Stage 場景的 Prim 操作，調試發現 USD Prim 都是 None。

這時候可以利用AI幫助，描述清楚問題的前因后果。

根據上面 AI 給出的提示，原因是 Omniverse 子線程中無法對 Stage 的 USD Prim 進行操作。 此時需要一個注冊主線程 Event 事件，在這個 Event 事件中去更新每一個 Prim 的操作。

此后還需考慮以下幾件事情：同步性（幀率統一）、設置延時、設置偏移、相機旋轉順序。

3.2 鎖定Omniverse渲染幀率

首先鎖定渲染的幀率。例如 FPS 鎖定在每秒 25 幀，FreeD 的發送幀率也鎖定到 25 幀。目的是保證良好的同步性，同時保證 Genlock 的傳輸接收效果良好。

關閉 Omniverse, 首先找到你對應的 Build 出來的 Composer 對應的.Kit文件,在“..kit107.3\_buildwindows-x86_64 eleaseapps” 里面包含所有配置的信息，用文本打開。

在[settings]下面添加以下字段, 注意是單獨的[settings]字段。

app.runLoops.main.rateLimitEnabled = true

app.runLoops.main.rateLimitFrequency = 25

app.runLoops.main.rateLimitUsePrecisionSleep = true

app.runLoops.main.syncToPresent = true

app.runLoops.present.rateLimitEnabled = true

app.runLoops.present.rateLimitFrequency = 25

app.runLoops.present.rateLimitUsePrecisionSleep = true

app.runLoops.rendering_0.rateLimitEnabled = true

app.runLoops.rendering_0.rateLimitFrequency = 25

app.runLoops.rendering_0.rateLimitUsePrecisionSleep = true

app.runLoops.rendering_0.syncToPresent = true

app.runLoops.rendering_1.rateLimitEnabled = true

app.runLoops.rendering_1.rateLimitFrequency = 25

app.runLoops.rendering_1.rateLimitUsePrecisionSleep = true

app.runLoops.rendering_1.syncToPresent = true

app.runLoopsGlobal.syncToPresent = true

app.vsync=true

重新打開 Omniverse 的 Composer ，可以看到此時的幀率是 50。原因是我們開啟了 DLSS 的 Frame Generation功能。 如果去掉 Frame Generation ，則會顯示 25 幀率。

3.3 注冊渲染 on_update 事件

要得到渲染事件的事件，需要在每一次渲染 Render 開始的時候取出一幀進行合并。

https://docs.omniverse.nvidia.com/dev-guide/latest/programmer_ref/events.html

Event streams 是以線程安全的方式傳遞數據，是由 Omniverse 的核心組件 carb 來提供，下面就是每一幀渲染的時候都會調用的函數， 后還需要再on_update函數去處理。

注冊 Event:

sub1= update_stream.create_subscription_to_pop(on_update, name="My Subscription Name")

解除注冊：需要把這個 sub1 設置為 None (并沒有 unsubscription 這個函數)

sub1= None

這里需要注意的是，在實際工程中要注意這個 sub1 的生命周期，不能用一個局部變量去存儲注冊的 event，否則在出了這個局部函數sub1以后會自動設置為 None，解決辦法是用一個成員變量去控制

self._sub= update_stream.create_subscription_to_pop,

然后在不需要的時候設置為 None:

self._sub= None

4相機延遲和定位偏移

4.1 相機延遲

相機延遲：在虛擬拍攝當中，除了相機定位，還有動捕數據，綠幕視頻流傳輸數據，這些數據需要處理的時間比 FreeD 要耗時，所有可能會造成不同步，這就需要給相機定位在本地緩沖增加一些延時，例如可以在程序中開一個 Buffer 來緩沖一下

4.2 定位偏移

因為定位設備和實際有偏移，所以利用 Nodal offset 來手動添加偏移量。

5設置 Camera 旋轉順序

歐拉角的旋轉是有順序的，其本質是因為旋轉對應的矩陣乘法不具備交換律。在 Omniverse Rotate 有 6 種方式，我們應該以哪種旋轉指定呢？

在 Omniverse 當中，應 Y 軸向上，按照 FreeD 的解析，即 Y, X, Z 的順序。 我們在 Omniverse 里按照 ZXY 給出旋轉順序的具體原理可以查看知乎中的這篇帖子：https://zhuanlan.zhihu.com/p/85108850

6最終

結合所有的步驟，完成最終所有功能。

iPhone 上面的 JetSet 軟件可以發送 FreeD 定位協議，這樣我們即可通過上面的思路完整做出一個符合工業標準的插件。

文案&技術支持：

宋毅明 NVIDIA Omniverse & OpenUSD 開發者關系經理