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