FactVerse Omniverse Adaptor 使用指南

创建于2025年4月25日

上次更新时间2026年1月28日

概述

FactVerse Omniverse Adaptor 是一款连接 FactVerse 平台与 NVIDIA Omniverse 的扩展插件，旨在帮助用户将数字孪生场景快速导入 Omniverse 环境，并结合 DFS（Data Fusion Services）实现 USD 场景中的动态仿真与联动。

核心功能

该插件在 Omniverse 应用中提供以下核心能力：

快速导入：从 FactVerse 平台加载 USD 模型和配置；
实时驱动：接入 DFS 数据，动态驱动场景变化；
多应用兼容：可集成至 USD Composer、Viewer、Explorer 等应用中使用；
灵活部署：支持本地运行或嵌入定制应用；
Web 可视化：搭配 WebRTC 与 Web 前端，实现浏览器内远程交互与查看。

使用场景示例

插件适用于以下典型场景：

使用场景	描述
场景导入与开发集成	将在 FactVerse 中构建的数字孪生场景快速导入 Omniverse 应用（如 USD Composer 或 Isaac Sim），支持在 Omniverse 内进行进一步开发。
实时数据可视化	接入 DFS 平台提供的实时或模拟数据，驱动场景中对象属性（如位置、角度、状态等）动态变化，实现数据与 3D 场景的联动展示。
仿真逻辑演示	插件内置行为树引擎可在本地运行场景中的逻辑（如设备状态变化、自动化流程等），并将结果同步渲染到 Omniverse 中，用于功能验证与场景仿真演示。
远程可视化展示	插件集成于 Streaming 应用中，结合 WebRTC 向浏览器端推送画面，实现 Web 远程交互。

插件加载方式说明

加载方式	适用场景	操作说明
Import Extension	测试连接与功能验证适用于 USD Composer / Isaac Sim 环境下的手动导入	通过菜单 Window > Extensions > Options > Import Extension 导入 .zip 插件包，快速测试插件是否连接平台、数据是否驱动成功
Extension Search Path	代码开发与调试阶段适用于本地自定义应用调试环境	在 USD Composer 或 Kit 应用中配置 Extension Search Path 指向 source/extensions/，便于热更新插件 Python 代码、查看实时日志输出
作为依赖配置	项目初始化阶段适用于定制 App（如 USD Viewer Streaming App）	在 .kit 应用配置文件及插件 extension.toml 中添加依赖声明，构建时统一加载插件模块

系统环境要求

操作系统支持

Enterprise Nucleus Server 在以下作系统上兼容并经过验证：

Ubuntu 22.04 LTS

注意：不支持在 Windows 环境中使用 Nano Server 或 WSL（Windows 子系统 Linux）运行 Enterprise Nucleus Server。

更多详细的系统需求和配置，请参考官方文档：Omniverse Nucleus 安装规划。

安全

根据 NVIDIA 官方建议，为确保 Nucleus Server 安装与运行顺利，请在部署前关闭以下系统安全服务：

SELinux
防火墙

说明：如需在生产环境中更改相关安全策略，请根据企业 IT 安全要求进行配置，以确保网络与服务访问正常。

准备工作

在开始使用 FactVerse Omniverse Adaptor 插件前，请确保完成以下准备工作，包括环境配置、工具包下载、场景搭建与数据准备等步骤，为后续插件集成与功能验证奠定基础。

安装开发工具与依赖项

工具	说明
Git	用于下载 kit-app-template 模板和插件代码库
Omniverse Nucleus	Omniverse Nucleus Server 是 Omniverse 的数据库和协作引擎，支持多个用户在多个应用程序中实时协作。参考附录 A：安装 Omniverse Nucleus
VS Code（推荐）	插件开发调试环境，Omniverse 提供官方 VS Code 插件支持 Kit 开发
Node.js + npm（可选）	构建 Web Client（远程交互与 WebRTC 可视化）

下载插件工具包

请访问 DataMesh 提供的下载链接，获取最新版本的 FactVerse Omniverse Adaptor 插件工具包（当前版本：v1.1.0），并解压使用。

工具包内容：

文件名	简称	功能说明
datamesh.factverse_ovadaptor_extension-1.1.0.zip	Adaptor 插件主程序	连接 FactVerse，驱动 USD 场景并写入至 Nucleus
datamesh.factverse_viewer_messaging_extension-0.2.0.zip	Messaging 插件	处理 Web 请求，控制场景加载与状态反馈
datamesh.toolkit-1.0.0.zip	USDP 资源解析插件	用于加载和解析 USDP 格式模型资源
glb_to_mdl_replacer.py	Blender插件	替换材质并生成 USDP 文件

试用插件

您可以参考动手实验室相关文章《快速接入Omniverse，开启高保真工业视觉》体验 FactVerse Omniverse Adaptor 插件的基本功能。

如在试用过程中遇到问题，欢迎发送邮件至 hol@datamesh.com 联系技术支持。

完成试用后，您可根据项目需求，按以下正式流程完成插件集成。

搭建数字孪生场景

为搭建孪生体模板与数字孪生场景，您需要安装以下必备工具：

DataMesh Importer：用于导入与预处理模型；
FactVerse Designer：用于模板创建、场景搭建和交互逻辑配置。

操作步骤

1. 准备模型：

a) 在 DataMesh Importer 中打开模型。

b) 根据实际运动需求，选择模型层级中的节点，以用于数据驱动。

c) 上传模型至您的 FactVerse 资源库。

2. 创建并配置模板：

a) 在 FactVerse Designer 中新建模板。

b) 拖入模型，添加属性。例如旋转角度。

c) 在数据绑定区域，将模型层级与属性进行关联，完成后保存模板。

3. 搭建孪生场景：

a) 新建孪生场景，根据已创建的模板批量生成孪生体。

b) 孪生体即代表实际设备，注意明确命名，便于后续数据绑定。

c) 调整孪生体位置和布局，完成基础场景构建并保存。

上传 USD 模型资源

在通过 FactVerse Omniverse Adaptor 导入数字孪生场景并实现数据驱动前，请确保场景中所用的模型资源均已绑定 USD 文件，以确保在 Omniverse 中能够正确渲染与运行。

支持的文件格式

目前 FactVerse 平台支持通过以下格式绑定模型资源：

文件格式	说明
.usdp	DataMesh 自定义封装格式，推荐使用。支持高保真渲染与多属性数据驱动，适用于复杂场景。
.usdz	通过 USDConverter 转换生成的 .usdz 文件可能存在坐标偏移等兼容性问题，不建议在Adaptor 1.1.0版本中继续使用。

注意事项：

内置小工具（如名称面板、进度条等）已预置 .usdp 文件，无需用户上传，具体支持范围请参考 [1.1.0 版本更新说明]。
自定义模型请按以下步骤上传 .usdp 文件完成绑定；
当前版本（v1.1.0）不支持动画同步，相关功能将在后续版本中通过工具链提供支持。

操作步骤
1. 准备USD 文件：请根据实际模型需求制作 .usdp 文件，详见附录 “制作 USD 模型资源”。如有疑问，可联系 DataMesh 支持团队 (hol@datamesh.com) 获取技术支持。

2. 上传模型资源

a) 登录 FactVerse平台。

b) 打开目标模型的资源详情页。

c) 在“平台扩展支持”区域，点击【Omniverse】按钮右侧的 “+” 图标。

d) 在弹出窗口中，点击打开资源文件夹或将 .usdp 文件直接拖拽至上传区域。每个模型仅支持绑定一个 USD 文件。

e) 点击【上传】按钮，成功绑定后，页面提示“上传成功”，【Omniverse】按钮左侧图标变为绿色圆点。如需替换附件，可点击按钮右侧的刷新图标重新上传。

接入数据

您可以通过 DFS（Data Fusion Services）平台 将设备数据接入 FactVerse 场景，实现孪生体的实时或模拟数据驱动。

可根据实际需求选择以下方式：

模拟数据驱动：适用于调试、展示场景，推荐参考《DFS 用户手册》中“示例一：基于历史/模拟数据源的仿真回放”；
实时数据驱动：适用于接入现场设备数据，推荐参考《DFS 用户手册》中“示例三：实时接入机械臂数据驱动孪生体”。

接入数据后，请返回 FactVerse Designer，打开对应孪生场景并点击【播放】，观察孪生体是否按预期运行。

如需详细操作说明，请参见《DataMesh FactVerse DFS 用户手册》。

测试连接与数据驱动效果

您可通过 Omniverse 官方应用（如 USD Composer 或 Isaac Sim）导入 Adaptor 插件，用于验证与 FactVerse 平台的连接能力、DFS 数据驱动效果以及场景是否正确加载。

适用场景：

验证插件是否能成功连接 FactVerse 平台；
测试 DFS 数据驱动是否生效（如机械臂是否正常运动）；
为后续远程部署、自定义 App 开发提供可视化验证支持。

导入插件

以 USD Composer（USD Composer 2023.2.3）为例，导入插件步骤如下：

安装 USD Composer。
设置启动参数（可选）：

当场景中包含 ScriptNode（Python 脚本节点） 时，USD Composer 默认会弹出 ScriptNode Warning 安全确认窗口，需要用户手动点击 Yes 才能继续执行脚本。

若该弹窗未被确认，可能导致以下问题：

- Adaptor 插件无法正常运行
- 场景加载或数据驱动流程被阻断

为确保 FactVerse Omniverse Adaptor 在无人值守或服务化运行场景下稳定工作，建议在启动 Composer 时通过启动参数自动允许 ScriptNode 执行，并关闭该确认弹窗。

- 使用 kit-app-template 构建 Composer

如果您通过 template new 方式基于 kit-app-template 构建 Composer，建议使用自定义 .bat 启动脚本并附加必要参数。

- 进入 Composer 项目目录
- 新建一个启动脚本（如bat），内容示例如下：

repo.bat launch datamesh.my_usd_composer.kit — ^
–/omnigraph/autonode/enabled=True ^
–/omnigraph/autonode/runtime_node_types=True ^
–/app/scripting/ignoreWarningDialog=true ^
–/app/omni.graph.scriptnode/enable_opt_in=false

使用源码工程构建 Composer

如果您使用的是源码工程方式启动 Composer，建议在对应的 .kit.bat 启动文件中同样补充以下参数，例如：

@echo off
setlocal
call “%~dp0kit\kit.exe” “%%~dp0apps/datamesh.my_usd_composer.kit” %* –/omnigraph/autonode/enabled=True –/app/scripting/ignoreWarningDialog=true –/omnigraph/autonode/runtime_node_types=True –/app/omni.graph.scriptnode/enable_opt_in=false

确认已安装必需扩展

Adaptor 插件依赖部分 Omniverse 官方扩展，请在确认以下扩展已安装并启用（如未安装，可在 Extensions 中手动安装并启用）：

扩展名	说明
omni.graph.scriptnode	允许在 OmniGraph 中使用 Python Script Node（脚本节点）。
omni.graph.core	OmniGraph 的核心库（节点执行、调度、数据模型）。
omni.graph.action_core	Action Graph 的核心功能（动作触发器、事件）。
omni.graph.action	Action Graph 主扩展（事件驱动逻辑系统）。
omni.anim.graph.bundle	动画图（AnimGraph）资源包。
omni.anim.graph.core	AnimGraph 的核心功能。
omni.kit.scripting	提供 Script Editor（脚本编辑器）以及 Scripting 运行时环境。

导入Adaptor扩展插件：

a) 打开 USD Composer，进入菜单 Window > Extensions。

b) 点击右上角 Options > Import Extension。

c) 导入 datamesh.factverse_ovadaptor_extension-1.1.0.zip和datamesh.toolkit-1.0.0.zip两个插件。

d) 分别启用已导入的插件。

验证连接与数据驱动

注意事项：请确保在进行场景导入和数据集成时，处于编辑模式下。

插件启用后，顶部菜单将新增【DataMesh】菜单项。点击【DataMesh】 > 【FactVerse Omniverse Adaptor】打开连接窗口。

在连接窗口中填写以下信息：

- Nucleus IP：插件访问的资源服务地址。若插件与插件访问的资源服务器在同一主机，可填写 localhost；若为远程部署服务，应填写其服务地址（在nucleus-stack.env 中设置的 SERVER_IP_OR_HOST ）。
- Deploy Code：FactVerse 服务部署标识，用于指定访问的服务区域
- Account ID：FactVerse 账号
- Password：登录密码
- Scene ID：孪生场景 ID
- Record ID：模拟记录数据集ID。仅在回放或播放模拟记录时需要填写

获取 Scene ID：

a) 在 FactVerse 平台中打开目标孪生场景的详情页面。

b) 复制 URL 中类似以下格式的 ID：

https://dtcs-local-demo.datamesh.com/…/6fa55ac9f44f4523ae0c166e299176d9/…

6fa55ac9f44f4523ae0c166e299176d9 即为 Scene ID。

获取Record ID

a) 打开 DFS 平台，进入【通用数据集】页面。

b) 在数据集分类列表中，点击需要使用的目标数据集。

c) 在浏览器中按 F12，打开开发者工具，并刷新当前页面。

d) 在开发者工具中，切换至 Network 页签，找到请求路径包含Network-> /api/dfs-analysis/custom/dataset/query 的请求，在该请求的 Response 内容中，查找字段datesetCategoryId。

示例：

“datesetCategoryId”: “1990319967523528705”

其中1990319967523528705即为该数据集的 Record ID。

点击【CONNECT】按钮后，插件将自动加载场景并绑定数据。

以上步骤完成后，即可在 USD Composer 中看到基于 FactVerse 实时数据驱动的孪生场景效果，为后续远程发布与调试提供验证基础。

测试完成点击【STOP】按钮停止 Adaptor 运行。

插件集成与定制开发

本章将介绍如何基于 Omniverse Kit 框架开发一个定制化的 USD Viewer Streaming应用，并在其中集成 Adaptor 插件。通过该集成，用户可以在应用内实现以下关键能力：

从 FactVerse 平台加载孪生场景；
绑定 DFS （实时或模拟）数据，驱动场景动态变化；
在 USD Viewer Streaming 应用中完成场景渲染；
通过 Web 浏览器实现远程访问与交互控制。

该方案适用于企业级部署、远程可视化展示、项目交付与多用户交互等场景，是插件从本地调试走向正式生产环境的主要集成方式。

数据流说明：

Adaptor 插件从 FactVerse 平台下载 USD 模型和孪生场景配置，并负责向本地 Nucleus 写入场景内容与数据变更；
DFS持续推送设备或传感器数据至 Adaptor 插件；
Adaptor 插件将数据按映射关系写入场景中的 USD 属性（如位置、角度、颜色等），实现对场景的动态驱动；
USD Viewer 从 Nucleus 加载并渲染当前场景，反映 Adaptor 写入的实时变化
Messaging 插件响应 Web 请求，通过调用 USD Viewer 接口加载目标场景，并监听场景中的事件与状态变化；
Web Client 发起加载/控制指令至 Messaging 插件，获取反馈信息，实现远程场景控制与状态同步。
Streaming 模块捕获 USD Viewer 的渲染画面，将其编码为视频流，通过 WebRTC 推送至 Web Client，实现浏览器中的 3D 场景可视化。

创建 USD Viewer Streaming 应用

初始化 App 项目：

git clone https://github.com/NVIDIA-Omniverse/kit-app-template

cd kit-app-template

.\repo.bat template new

按提示填写：

- 类型：Application
- 基于模板：[omni_usd_viewer]
- 应用名：datamesh.my_usd_viewer
- 版本号：0.1.0

配置扩展插件信息：

在初始化流程中，需要配置以下两个核心扩展插件：

a) USD Viewer Messaging Extension

此插件负责 Web 客户端与 Viewer 应用之间的指令通信和状态反馈。

项目	配置示例值
文件名	datamesh.factverse_viewer_messaging_extension
名称	My USD Viewer Messaging Extension
版本号	0.2.0

b) USD Viewer Setup Extension

此插件负责处理应用内的配置、通信、布局和其他设置等。

项目	配置示例值
文件名	datamesh.my_usd_viewer.setup
名称	My USD Viewer Setup Extension
版本号	0.1.0

启用流式传输
在初始化 USD Viewer Streaming 应用时，请在 Streaming 配置步骤中，选择以下模块：
• [omni_default_streaming]: Omniverse Kit App Streaming (Default)
该模块将自动为应用集成 WebRTC 流式传输功能，支持将 USD Viewer 的渲染画面实时推送至浏览器前端，从而实现远程可视化与交互控制能力。
构建项目

.\repo.bat build

集成 Adaptor 插件和 Messaging 插件

解压插件至 extensions 目录：将以下文件解压至 source/extensions/ 目录中。

- datamesh.factverse_ovadaptor_extension-1.1.0.zip
- datamesh.factverse_viewer_messaging_extension-0.2.0.zip
- datamesh.toolkit-1.0.0.zip

配置依赖：

a) 在 datamesh.usd_viewer.setup/config/extension.toml 中增加 Messaging 插件依赖。

[dependencies]

“omni.kit.usd.layers” = {}

“omni.activity.ui” = {order=1000} # Progress activity messages

“omni.kit.quicklayout” = {}

“omni.kit.viewport.utility” = {}

“datamesh.factverse_viewer_messaging_extension” = {} # Required messaging extension

b) 编辑 datamesh.factverse_viewer_messaging_extension/config/extension.toml 中增加 Adaptor插件依赖。

[dependencies]

“datamesh.factverse_ovadaptor_extension” = {} # Required Adaptor extension

c) 在 source/apps/datamesh.my_usd_viewer_streaming.kit 中添加Live Session 功能的依赖

[dependencies]

…

“omni.kit.collaboration.channel_manager” = {}

“omni.kit.collaboration.presence_layer” = {}

“omni.kit.collaboration.selection_outline” = {}

“omni.kit.collaboration.telemetry” = {}

“omni.kit.widget.live” = {}

“omni.kit.livestream.webrtc” = {} # Livestream extension

建立硬链接（可选）：为避免 Windows 对路径长度的限制，可使用硬链接方式缩短路径。

mklink /J “路径/_build/…/exts/datamesh.factverse_ovadaptor_extension” “路径/source/extensions/datamesh.factverse_ovadaptor_extension”

mklink /J “路径/_build/…/exts/datamesh.factverse_viewer_messaging_extension” “路径/source/extensions/datamesh.factverse_viewer_messaging_extension”

开发与调试

在 USD Composer 中添加 Extension Search Path挂载Adaptor插件源码，例如：d:/temp/kit-app-template/source/extensions。

启用插件

使用 VSCode 打开插件源码，进入调试开发。

设置启动参数：打开 kit-app-template 构建好的Streaming 应用时，datamesh.my_usd_viewer_streaming.kit.bat：

@echo off

setlocal

call “%~dp0kit\kit.exe” “%%~dp0apps/datamesh.my_usd_viewer_streaming.kit” %* –no-window –/omnigraph/autonode/enabled=True –/app/scripting/ignoreWarningDialog=true –/omnigraph/autonode/runtime_node_types=True –/app/omni.graph.scriptnode/enable_opt_in=false

以管理员权限启动 USD Viewer Streaming 应用

.\repo.bat launch datamesh.my_usd_viewer_streaming.kit

确认开发调试无误后，可执行以下命令打包发布应用：

.\repo.bat package

Web 前端部署

在完成 FactVerse Omniverse Adaptor 插件集成，并成功启动 USD Viewer Streaming 应用后，您可以部署配套的 Web 前端项目，通过浏览器远程访问并交互数字孪生场景。

本节以 DataMesh 提供的 Omniverse Web Viewer 示例项目为参考说明。

1. 初始化 Adaptor 连接配置：

Web 前端在建立与 Omniverse 场景的连接前，需要先向 Adaptor 发送初始化配置，用于完成 FactVerse 与 Nucleus 的连接。

src/views/DashboardView.vue中主要配置参数说明如下

参数项	说明
account_id	FactVerse 平台账号（可选，支持使用 Token 方式）
password	FactVerse 平台账号密码（使用账号登录时填写）

src/utils/mqtt.ts 中主要配置参数说明如下：

参数项

说明

nucleus_ip

Omniverse Nucleus 服务地址

deploy_code

FactVerse 服务部署码

默认值为 cn（中国区部署）；
如需访问其他区域的 FactVerse 服务，请根据实际部署环境修改为对应的部署码。

2. 配置 Streaming 服务与场景信息

Web 前端通过 USD Viewer Streaming 服务获取 Omniverse 渲染画面，相关运行时配置统一在 public/config.js 中设置。

参数说明

参数项	说明
streamServer	USD Viewer Streaming 服务地址（IP/域名）
sceneId	要打开的孪生场景 ID，可从 FactVerse 平台场景详情页 URL 中获取
simulatedId	模拟记录（Record）ID；不播放模拟记录可留空

3. 启动前端应用

npm install

npm run dev

默认访问地址为：http://localhost:8080，在浏览器中打开即可进入 Web 操作界面。

页面加载完成后，将显示 Omniverse 渲染画面，并支持通过 Web 页面与数字孪生场景进行交互操作。

附录 A：安装 Omniverse Nucleus

在正式使用 Adaptor 插件前，必须安装并配置 Omniverse Nucleus。该组件在插件运行过程中承担以下两个关键角色：

角色	描述
USD 场景资源服务器	负责存储、同步插件生成的 .usd 场景文件，供 Omniverse 应用加载与渲染使用。
本地 API 接口提供者	插件运行时依赖本地 Nucleus 接口执行上传、资源查询等操作。

部署前提

系统要求：已安装 Ubuntu 22.04 操作系统；
推荐环境：开发测试阶段建议使用 单机部署，便于快速搭建和调试。

部署方式说明

部署方式

配置说明

插件与资源服务器部署在同一台机器上

只需安装一个 Nucleus 实例，该实例既作为资源服务器，也同时提供 API 接口。插件配置中的 Nucleus IP 可设为 localhost。

插件与资源服务器分别部署（不同机器）

需安装两个 Nucleus 服务器实例：

① 在远程机器上安装 Nucleus 作为资源服务器；

② 在插件所在机器上安装 Nucleus，仅作为本地 API 接口；
插件配置中的 Nucleus IP 必须填写资源服务器的地址（如 192.168.1.1）。

注意事项：

插件运行所在机器必须可访问资源服务器；
网络不通或地址配置错误将导致场景加载失败或数据驱动异常。

推荐部署方式（开发 / 测试）

为方便调试和功能验证，建议在同一台 Ubuntu 服务器上部署：

Omniverse Nucleus
Adaptor 插件
Omniverse 应用程序（如 USD Composer）

A.1 安装准备：注册与下载 Nucleus Server

在部署 Enterprise Nucleus Server 之前，请先完成以下准备步骤：

步骤 1：注册账号并申请试用

NVIDIA 提供 Enterprise Nucleus Server 的 免费试用版本，可用于测试与开发（正式生产环境使用需购买企业许可证）。

打开试用申请页面：申请 90 天试用。
点击【Register for Trial】，注册 NVIDIA 开发者账号并填写相关信息。

提交后将收到试用资格及访问权限通知邮件。
验证登录：打开登录链接，登录后出现如下界面账号注册完成。

步骤 2：下载 Enterprise Nucleus Server

使用已注册的 NVIDIA 开发者账号 登录NGC（NVIDIA Graphics Cloud）平台。
单击此处访问 Enterprise Nucleus Server 集合。

切换至 Artifacts 标签页；
找到 Nucleus Compose Stack，点击打开页面；
切换至 File Browser 标签页，点击Actions列然后单击“Download File”。

步骤 3：安装 Docker

为确保 Nucleus Compose Stack 正常运行，如果运行的是 Enterprise Nucleus Server 2023.2.0 或更高版本，建议使用Docker 20版本。

如果运行的是 Enterprise Nucleus Server 2023.1.0 或更低版本，建议使用Docker 18 或 19版本。

以下为经过验证的版本：

服务名	版本
Docker	version 20.10.24, build 297e128
docker-compose	version 1.29.2, build 5becea4c
Omniverse Nucleus	2023.2.9

1. 更新本地apt存储库

sudo apt-get update

2. 安装依赖包

sudo apt-get install apt-transport-https ca-certificates curl gnupg lsb-release

3. 添加Docker 存储库

sudo mkdir -p /etc/apt/keyrings

sudo curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg –dearmor -o /etc/apt/keyrings/docker.gpg

4. 将 Docker 存储库添加到您的 apt 源文件中

sudo echo \
“deb [arch=$(dpkg –print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu \$(lsb_release -cs) stable” | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

5. 更新本地库

sudo apt-get update

6. 查看可用的 Docker 版本

sudo apt-cache madison docker-ce | awk ‘{ print $3 }’

7. 安装 Docker 及相关组件

VERSION_STRING=5:20.10.24~3-0~ubuntu-jammy

sudo apt-get install docker-ce=$VERSION_STRING docker-ce-cli=$VERSION_STRING containerd.io docker-compose-plugin

8. 验证 Docker 安装成功

docker –version

输出示例：

Docker version 20.10.24, build 297e128

9. 安装 Docker Compose

sudo apt install docker-compose

A.2 安装 Enterprise Nucleus Server

步骤 1：上传并解压安装包

1. 将已下载的 nucleus-stack （.tar.gz）安装包上传至服务器（例如 /tmp）

2. 进入临时目录：

cd /tmp

3. 创建一个安装目录（建议：/opt/ove）：

sudo mkdir /opt/ove

4. 解压安装包到该目录：

sudo tar xzvf nucleus-stack-2023.2.9+tag-2023.2.9.gitlab.31778301.bd3f484c.tar.gz -C /opt/ove –strip-components=1

注意：安装包名称因版本不同而异，注意替换为实际文件名。

步骤 2：配置环境文件

1. 进入配置目录

cd /opt/ove/base_stack

2. 编辑 nucleus-stack.env

sudo nano nucleus-stack.env

按如下要求修改内容：

配置项	设置说明
ACCEPT_EULA=1	接受最终用户协议
SECURITY_REVIEWED=1	确认安全性已评估
SERVER_IP_OR_HOST=192.168.1.1	本机或服务器外部可访问地址
MASTER_PASSWORD=your_password	管理员密码
SERVICE_PASSWORD=your_password	服务密码
DATA_ROOT=/var/lib/omni/nucleus-data	数据存储路径
CONTAINER_SUBNET=192.168.1.0/26	Nucleus Docker 容器的 IP 地址从此子网分配，如有冲突请修改

步骤 3：生成 SSL 密钥（测试环境）

不适用于生产环境，仅用于 PoC 测试。

cd /opt/ove/base_stack

sudo ./generate-sample-insecure-secrets.sh

A.3 部署 Nucleus 服务

步骤 1：下载镜像

wget https://dtcspackage.blob.core.chinacloudapi.cn/installation-package/ov_file_2023.2.9.tar.gz
tar -zxvf ov_file_2023.2.9.tar.gz
cd ./ov_file/ove/images_file
sh l1_ov.sh

步骤 2：启动服务容器

1. 启动容器（前台运行）

sudo docker compose –env-file /opt/ove/base_stack/nucleus-stack.env -f /opt/ove/base_stack/nucleus-stack-no-ssl.yml up

没有报错以“守护进程”模式启动服务

sudo docker compose –env-file /data/ove/base_stack/nucleus-stack.env -f /data/ove/base_stack/nucleus-stack-no-ssl.yml up -d

步骤 3：验证服务

浏览器访问http://<SERVER_IP_OR_HOST>:<WEB_PORT>/login。

默认用户名：omniverse
密码：在 nucleus-stack.env 中设置的 MASTER_PASSWORD

官方文档参考：Nucleus Enterprise 安装指南

附录 B：USDP 文件格式说明

本附录用于帮助用户理解 USDP 文件的用途与能力边界，以便在使用 FactVerse Omniverse Adaptor 时正确准备和使用模型资源。

B.1 什么是 USDP

USDP（USD Package）是 DataMesh 基于 OpenUSD 标准扩展的一种三维资产封装格式，用于在 FactVerse 与 Omniverse 场景中交付 高保真、数据驱动的数字孪生模型。

与普通 USD 文件相比，USDP 可将以下内容统一封装：

三维模型与材质
参数化配置（尺寸、状态等）
行为与交互逻辑
资产元数据（版本、依赖等）

USDP 主要用于 FactVerse 平台内部，不作为通用跨平台资产格式。

B.2 USDP 能做什么

使用 USDP，可以实现：

一套模型，多种规格（参数化配置）
按需加载，提升场景性能

为数据驱动和交互逻辑预留扩展能力
在 Omniverse 中稳定还原 FactVerse 场景效果

USDP 特别适合用于：

数字孪生设备

参数化产线组件
业务可配置的三维资产

B.3 USDP 文件的整体结构

USDP 文件本质上是一个符合 USD 资产组织规范的压缩包（.usdp），其内部采用分层封装结构。

核心组成

组成部分	内容说明	主要作用
USD模型素材库	多个 USD 子模型、材质与贴图	提供可组合的几何与外观资源
动画系统	骨骼动画、动画片段、状态定义	支持动画切换与编排
参数化配置	尺寸、颜色、状态等参数	支持运行时调整与规格适配
交互逻辑	事件定义、控制规则	支持可视化交互与控制逻辑绑定
行为脚本	Python 行为与数据绑定	实现自动化与数据驱动
元数据	ID、版本、依赖、作者等	生命周期与版本管理

B.4 参数化能力说明

B.4.1 支持的参数类型

几何参数（尺寸、位置、缩放）
外观参数（颜色、材质属性）
动画参数（当前状态、速度、过渡时间）
功能参数（数据源、刷新频率、交互开关）

B.4.2 参数化优势

一套资产适配多规格
参数修改可即时生效
支持 JSON 等格式批量配置
具备类型校验与范围约束

B.5 典型应用场景（示例）

USDP 适用于以下数字孪生资产类型：

参数化传送带、产线设备
立体仓储与货架系统
可配置光源与环境组件
具备多状态动画的角色（如工人、机器人）

这些资产可通过参数快速生成不同规格，而无需重复建模。

B.6 文件封装与分发特性

B.6.1 文件格式说明

文件扩展名：.usdp
压缩格式：ZIP
结构：符合 USD 资产目录规范

B.6.2 典型结构示例

AssetName.usdp

├── AssetName.usda             # 主场景文件
├── Scripts/                   # 行为脚本
│   ├── main_controller.py     # 主控制器
│   ├── utils.py               # 工具库
│   └── config.json            # 配置数据
├── Models/                    # 模型资产库
│   ├── ComponentA.usd         # 子组件A
│   ├── ComponentB.usd         # 子组件B
│   └── textures/              # 材质贴图
└── Config/
│   ├── extension.toml         # 扩展元数据

B.7 使用建议与边界说明

USDP 是面向 FactVerse + Omniverse 生态设计的资产格式
当前版本主要用于：
高保真渲染
参数化资产
数据驱动数字孪生
不建议将 USDP 作为通用跨平台分发格式使用

B.8 小结

USDP 并不是对 USD 的替代，而是：

在 USD 标准之上，为数字孪生场景提供工程化、可编程、可交付的资产封装方式

在 FactVerse Omniverse Adaptor 中，USDP 是连接 Designer / 数据 / Omniverse 的关键资产载体。

附录 C：制作 USD 模型资源

本附录用于说明如何将三维模型处理并导出为可用于 FactVerse Omniverse Adaptor 的 USD 模型资源。
为获得最佳渲染与材质表现效果，推荐最终输出为 .usdp 格式。

C.1 模型与材质要求

为确保模型在 Omniverse 场景中具有良好的视觉效果和材质一致性，建议在建模与贴图阶段满足以下要求：

模型要求

模型精度：建议使用中高精度模型；
结构完整：模型层级清晰，避免冗余或无效节点。

材质与贴图要求

建议采用 PBR（Physically-Based Rendering）渲染流程，包含以下常用贴图类型：

基础色（Base Color）
金属度（Metallic）
粗糙度（Roughness）
法线（Normal）
环境光遮蔽（AO）
自发光（Emission）

C.2 所需软件和插件

工具	用途
UnityGLTF 2.15.0	从 Unity 导出 .glb 格式模型
Omniverse Unity Connector	从 Unity 导出 .usd 材质参考文件
Blender4.2 alpha（USD 分支）	编辑与导出 .usd / .usdp 文件
Blender 插件 glb_to_mdl_replacer.py	替换材质并生成 USDP 文件

C.3 模型处理流程

步骤1：在 Unity 中导出 GLB 文件

在 Unity 编辑器中导入模型（.fbx）和相关贴图；

右键点击模型预制体，选择 UnityGLTF > Export Selected as GLB 进行导出。

重要提示：导出前确保模型的位移（Position）、旋转（Rotation）与缩放（Scale）分别为 0，0，0 和 1，1，1，以避免坐标偏差。

步骤2：导出材质参考 USD 文件

通过Omniverse Unity Connector导出 USD 文件，供后续在 Blender 中替换材质参考。

Omniverse Unity Connector 设置

右键选中模型预制体，在弹出菜单中选择【Export to USD】。

步骤3：使用Blender导出USDP文件

打开Blender 2 Alpha（USD 分支），安装Blender 插件 glb_to_mdl_replacer.py

在插件面板中执行以下操作：

a) 选择文件路径：选择步骤 1 的 GLB 文件和步骤 2 的 USD 文件；

b) 点击【1 替换材质】；

c) 设置输出路径，勾选“导出后打包为 USDP”；

d) 点击【2 导出USD文件】。

导出完成后，即可获得包含完整材质信息的 .usdp 文件，可用于绑定至 FactVerse 模型资源中。

示例输出文件结构如下图所示：

C.4 说明与支持

本流程主要用于生成适配 FactVerse + Omniverse 的高保真模型资源；
.usdp 文件为 DataMesh 平台内部使用格式，不作为通用跨平台模型分发格式；
如在制作过程中遇到问题，请联系 DataMesh 支持团队：hol@datamesh.com

常见问题

问题 1：在 USD Composer 中导入 Adaptor v1.1.0 扩展后，打开场景时弹出 ScriptNode 警告窗口

现象说明

打开场景时，USD Composer 弹出 ScriptNode（Python 脚本节点）安全确认窗口，要求手动点击确认。

原因说明

USD Composer 默认会对包含 Python ScriptNode 的场景进行安全提示，若未确认，可能阻断 Adaptor 插件的自动运行。

解决方法

请参考 4.1 导入插件章节中 “设置启动参数” 的说明，在启动 Composer 时添加相应参数，以自动允许 ScriptNode 执行，避免弹窗阻断插件运行。

问题 2：Adaptor 连接 FactVerse 过程中出现错误，场景无法正常加载

可能原因

场景中存在 未绑定或未上传 USDP 文件的模型资源。

解决方法

检查当前孪生场景中使用的所有模型资源；
确认每个自定义模型均已在 FactVerse 平台上传并绑定对应的 .usdp 文件；
补充上传缺失的 USDP 文件后，重新加载场景即可。

问题 3：打开 Web 端渲染画面时，画面出现闪烁或不稳定

原因说明

支持USDViewerStreaming（推流服务）的显卡要求较高

解决方法

建议将 USDViewerStreaming（推流服务） 部署并运行在显卡性能较高的设备上，推荐使用 RTX 4090 或以上级别显卡，以保证 Web 端渲染的稳定性和流畅度。

版本更新说明

版本 1.1.0

本版本新增对 USDP 模型格式的支持，并增强了资源工具集功能，进一步提升了与 Omniverse 平台的集成效率与模型表现力。

主要更新内容：

支持 USDP 格式模型资源

新增对 .usdp 格式的支持（基于 USD 标准扩展的 DataMesh 专用封装格式），用于在 FactVerse 平台与 Omniverse 场景之间更高效地传输、加载复杂的三维模型资源。

内置 8 个常用小工具 USDP 资源

本版本默认提供以下小工具的 USDP 模型资源，确保其在 Omniverse 中具备一致的视觉表现和交互能力：

名称面板、进度条、存储区、入口、出口、传送带、球体、立方体

使用这些小工具构建孪生场景时，用户无需手动绑定 USD 文件。通过 FactVerse Omniverse Adaptor 插件，系统将自动加载对应的 USDP 资源，并在 Omniverse 中准确还原其三维外观与功能效果。

硬件	最低配置
内存	32 GB
CPU	16 核, 3.0 GHz 或更高
硬盘	SSD 512 GB

硬件	最低配置
GPU	NVIDIA RTX 系列显卡，如：NVIDIA GeForce RTX 4090 D (VRAM 24GB)、GeFore RTX 5090、NVIDIA RTX 6000 Ada
内存	32 GB
硬盘	SSD 512 GB

我们能帮你什么吗？

FactVerse Omniverse Adaptor 使用指南

概述

核心功能

使用场景示例

插件加载方式说明

系统环境要求

推荐硬件配置

操作系统支持

安全

准备工作

安装开发工具与依赖项

下载插件工具包

试用插件

搭建数字孪生场景

上传 USD 模型资源

接入数据

测试连接与数据驱动效果

导入插件

验证连接与数据驱动

插件集成与定制开发

创建 USD Viewer Streaming 应用

集成 Adaptor 插件和 Messaging 插件

开发与调试

Web 前端部署

附录 A：安装 Omniverse Nucleus

A.1 安装准备：注册与下载 Nucleus Server

步骤 1：注册账号并申请试用

步骤 2：下载 Enterprise Nucleus Server

步骤 3：安装 Docker

A.2 安装 Enterprise Nucleus Server

步骤 1：上传并解压安装包

步骤 2：配置环境文件

步骤 3：生成 SSL 密钥（测试环境）

A.3 部署 Nucleus 服务

步骤 1：下载镜像

步骤 2：启动服务容器

步骤 3：验证服务

附录 B：USDP 文件格式说明

B.1 什么是 USDP

B.2 USDP 能做什么

B.3 USDP 文件的整体结构

B.4 参数化能力说明

B.4.1 支持的参数类型

B.4.2 参数化优势

B.5 典型应用场景（示例）

B.6 文件封装与分发特性

B.6.1 文件格式说明

B.6.2 典型结构示例

B.7 使用建议与边界说明

B.8 小结

附录 C：制作 USD 模型资源

C.1 模型与材质要求

C.2 所需软件和插件

C.3 模型处理流程

C.4 说明与支持

常见问题

问题 1：在 USD Composer 中导入 Adaptor v1.1.0 扩展后，打开场景时弹出 ScriptNode 警告窗口

问题 2：Adaptor 连接 FactVerse 过程中出现错误，场景无法正常加载

问题 3：打开 Web 端渲染画面时，画面出现闪烁或不稳定

版本更新说明

版本 1.1.0