利用NVIDIA Omniverse Extension开发FreeD定位系统

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 开发者关系经理