TiXL FreeDInput 算子详解：基于 UDP 的 FreeD 摄像机跟踪数据接收与虚拟制片集成

TiXL FreeDInput 算子详解基于 UDP 的 FreeD 摄像机跟踪数据接收与虚拟制片集成【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3FreeDInput 是 TiXLtooll3开源实时动态图形软件中 Lib.io.freed 命名空间下负责接收FreeD 摄像机跟踪数据的核心算子它通过 UDP 监听端口解析标准的 29 字节 FreeD 数据包并把每台摄像机的旋转、位置、变焦、聚焦等信息实时输出为 GPU 缓冲、字典与单值输出供虚拟制片、增强现实与广电制播场景使用。读完本文你将掌握 FreeDInput 的全部输入参数与输出语义、底层数据包解析原理24 位大端整数、校验和、缩放比例并能在 TiXL 中完成与 Unreal Engine、Vizrt、Aximmetry 等系统的实时联调。背景FreeD 协议与虚拟制片中的摄像机跟踪FreeD 是一种轻量级 UDP 协议广泛用于将摄像机云台跟踪数据Pan/Tilt/Roll、X/Y/Z 位置、镜头 Zoom/Focus 编码值从跟踪系统实时传输给渲染引擎或合成系统。在虚拟制片Virtual Production、增强现实AR和广电制播流程中虚拟摄像机必须与物理摄像机保持完全同步——这正是 FreeDInput 的用武之地Unreal Engine / Vizrt / Aximmetry等系统通常作为 FreeD 数据包发送端或接收端TiXL 通过 FreeDInput 以同等身份接入这条数据链路把跟踪数据驱动场景中的虚拟摄像机、匹配前景与背景画面配合同一命名空间下的 FreeDOutput发送端可以在 TiXL 内部完成接收—处理—再发送的完整闭环。该算子定义于 Operators/Lib/Symbols/io/freed/FreeDInput.cs与其配套的FreeDInput.t3/FreeDInput.t3ui符号与界面文件位于同一目录文档由算子库自动生成。输入参数FreeDInput 共提供 5 个输入参数覆盖了 UDP 监听所需的全部关键设置名称相关性与类型说明默认值与源码依据ListenBoolean启用后打开 UDP 套接字并开始监听禁用则关闭连接默认false。每次更新时比较新旧状态发生变化才执行启停见 FreeDInput.csLocalIpAddressString监听所用的本机网卡 IP0.0.0.0 (Any)表示监听所有可用网卡通常直接使用该值默认0.0.0.0 (Any)。该输入是一个下拉框ICustomDropdownHolder自动枚举本机所有 IPv4 地址见 FreeDInput.csPortInt32监听的 UDP 端口必须与发送方广播的目标端口一致默认6000FreeDInput.csCameraIdInt32选择输出到单摄像机输出CameraPos、CameraRot 等的特定摄像机 ID设为-1时自动选择 ID 最小的摄像机默认-1见 FreeDInput.csPrintToLogBoolean启用后把详细活动与错误信息打印到 T3 日志控制台便于调试默认false参数源码解读设置变更检测算子每帧比较Listen、LocalIpAddress、Port的当前值与上次状态只有发生变化时才关闭旧套接字并重新监听避免频繁重建 UDP 连接造成丢包或抖动FreeDInput.cs。网卡下拉框GetOptionsForInput会枚举所有状态为 Up 且非回环的网卡的 IPv4 单播地址并在列表头部固定提供0.0.0.0 (Any)与127.0.0.1选择后通过SetTypedInputValue写回输入FreeDInput.cs。地址解析兜底监听循环中若 IP 无法解析或为空则回退到IPAddress.Any监听所有网卡行为与0.0.0.0 (Any)一致FreeDInput.cs。输出参数FreeDInput 提供 8 个输出分为全部摄像机批量与单摄像机精选两组名称类型说明CamerasAsBufferT3.Core.DataTypes.BufferWithViews所有已跟踪摄像机的 GPU 结构化缓冲每个元素一个Point可直接送入渲染管线CameraDataAsDictT3.Core.DataTypes.Dict1[System.Single]以路径为键的字典涵盖每台摄像机的 Pan/Tilt/Roll、PosX/PosY/PosZ、Zoom、Focus、UserIsListeningSystem.Boolean当前是否正在监听监听线程处于 Running 状态CameraPosSystem.Numerics.Vector3选定摄像机的世界位置米CameraRotSystem.Numerics.Vector3选定摄像机的旋转度ZoomSystem.Single选定摄像机的变焦编码值FocusSystem.Single选定摄像机的聚焦编码值UserSystem.Single选定摄像机的自定义用户数据所有输出均标记为DirtyFlagTrigger.Animated并由同一个Update方法驱动FreeDInput.cs。批量输出CamerasAsBuffer 与 CameraDataAsDict当至少收到一台摄像机的数据后算子会按摄像机 ID 升序遍历内部字典生成两个并行视图GPU 缓冲每个摄像机映射为一个 Point 结构体64 字节Stride 16 * 4其中Position保存摄像机位置Orientation保存由yaw/pitch/roll度转弧度经Quaternion.CreateFromYawPitchRoll构造的四元数Scale编码为(Focus, Zoom, User)F1存放摄像机 IDColor为Vector4.OneFreeDInput.cs。字典输出键形如/{id}/Pan、/{id}/Tilt、/{id}/Roll、/{id}/PosX、/{id}/PosY、/{id}/PosZ、/{id}/Zoom、/{id}/Focus、/{id}/User方便用字符串路径在算子图中取任意一台摄像机的任意通道。缓冲通过ResourceManager.SetupStructuredBuffer创建并同时生成 SRV 与 UAVFreeDInput.cs缓冲区尺寸不变时仅用UpdateSubresource增量上传避免每帧重新分配 GPU 资源。单摄像机输出CameraId指定要读取的摄像机大于等于 0 时按该 ID 查找为-1时自动选择当前已跟踪摄像机中 ID 最小的那台。找到后其位置、旋转、变焦、聚焦与用户数据分别写入CameraPos、CameraRot、Zoom、Focus、User五个输出FreeDInput.cs。FreeD 数据包解析原理FreeDInput 内置了完整的 FreeD 协议解析实现这对理解数据精度与排查联调问题至关重要。包格式29 字节解析入口ParseFreeDDataPacket定义了如下布局FreeDInput.cs偏移长度字段解析方式01协议标识符必须为0xD1否则丢弃该包11摄像机 IDbyte作为字典键2 / 5 / 8各 3Pan / Tilt / Roll24 位有符号大端整数除以32768.0得到度11 / 14 / 17各 3PosX / PosY / PosZ24 位有符号大端整数除以64000.0得到米203Zoom24 位无符号大端整数233Focus24 位无符号大端整数262User16 位大端整数(data[26] 8) \| data[27]281校验和必须等于0x40 - Σ(前 28 字节) 0xFF否则丢弃关键实现细节校验和CalculateFreeDChecksum取前 28 字节求和再用0x40u - sum截断为单字节解析时若与末字节不符则整包丢弃有效防止错包污染跟踪数据FreeDInput.cs。24 位有符号数的符号扩展ReadInt24BigEndian将三个字节拼成 32 位整数若最高位0x80置位则或上0xFF000000完成符号扩展正确处理负角度与负坐标FreeDInput.cs。角度/距离缩放旋转原始值除以32768.0即得角度度位置原始值除以64000.0即得米。发送端 FreeDOutput.cs 使用完全相同的两个缩放常量做编码二者严格互逆。去重与覆盖同一摄像机 ID 的新包直接覆盖旧值_trackedValues[newData.CameraId] newData因此同一 ID 的跟踪数据天然最新值优先FreeDInput.cs。内部工作流从 UDP 数据报到 GPU 缓冲从网络字节流到可渲染数据FreeDInput 内部按如下流程工作后台监听线程启用Listen后StartListening启动一个Task.Run的后台任务创建UdpClient设置ReuseAddress套接字选项后Bind到目标 IP 与端口随后循环ReceiveAsyncFreeDInput.cs。队列缓冲收到的原始字节包压入ConcurrentQueuebyte[]FreeDInput.cs网络线程与主线程解耦避免阻塞渲染循环。主线程解析算子在每次求值更新时把队列中的包全部取出并解析写入以摄像机 ID 为键的ConcurrentDictionarybyte, FreeDCameraDataFreeDInput.cs。输出装配如上文所述生成字典输出、单摄像机输出与 GPU 结构化缓冲。状态报告算子实现 IStatusProvider通过状态栏向用户反馈监听中但未收到数据Listening, no camera data received yet.Notice正常跟踪Tracking N cameras.Success监听线程异常退出Listener failed: ...Error未启用监听Not listening.。实操指南在 TiXL 中接入 FreeD 跟踪源以下是以 FreeDInput 为核心的最小联调流程创建算子在算子库的Lib.io.freed分组中拖入FreeDInput。配置监听Listen设为trueLocalIpAddress保留0.0.0.0 (Any)监听所有网卡通常最省心若主机存在多网卡且需要指定可从此参数的下拉框中直接选择具体 IPv4 地址Port设置为与发送端一致的端口双方默认都是6000。确认数据进入观察算子状态栏应显示Tracking N cameras.若一直显示no camera data received检查发送端是否已启动、端口与目标 IP 是否正确。消费数据驱动虚拟摄像机把CameraPos、CameraRot、Zoom连接到对应算子的位置/旋转/参数输入批量渲染把CamerasAsBuffer直接接到点云/粒子类算子的输入逐通道取值用CameraDataAsDict的字符串键如/1/Pan在算子图中按路径读取任意通道。多摄像机发送端可同时发送多台摄像机的数据FreeDInput 会自动按 ID 归类用CameraId切换单摄像机输出的目标或用字典/缓冲输出批量处理全部摄像机。调试打开PrintToLogT3 日志控制台会输出监听绑定信息Bound to ip:port、解析摘要含 Zoom/Focus/User与队列长度等详细日志FreeDInput.cs。无发送端时的自测方法仓库中的 FreeDOutput 算子与 FreeDInput 使用相同的包格式、缩放常量与默认端口 6000。在没有外部跟踪设备时可以用 FreeDOutput 指向 FreeDInput 的监听地址发送测试包验证整条解析链路这也证明了两个算子可以在同一台机器上完成发送—接收闭环联调。常见问题与排查现象可能原因与处理状态栏一直显示no camera data received发送端未启动、端口不一致、或发送目标 IP 未指向本机确认双方端口一致监听失败Listener failed端口被占用或 IP 无效更换端口或改选下拉框中的具体网卡 IP单摄像机输出无数据检查CameraId是否为-1或对应的合法 ID发送端可能没有发送该 ID 的数据数据抖动/乱跳校验和不过的包已被丢弃确认发送端严格遵循 29 字节、0xD1标识与校验规则需要同时处理多台摄像机使用CamerasAsBuffer或CameraDataAsDict批量输出它们会覆盖所有已跟踪的摄像机 ID扩展阅读发送端算子FreeDOutput 与 FreeDOutput.cs命名空间总览Lib.io.freed README、Lib.ioGPU 缓冲元素定义PointPosition/Orientation/Scale/F1布局状态反馈接口IStatusProvider【免费下载链接】t3TiXL is an open source software to create realtime motion graphics.项目地址: https://gitcode.com/GitHub_Trending/t3/t3创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考