跳到主要内容

MuJoCo 场景编辑器 (XML Editor) - DISCOVERSE 模块

1. 引言​

1.1 什么是 MuJoCo 场景编辑器？​

MuJoCo 场景编辑器是一款基于 PyQt5 和 OpenGL 开发的图形界面工具，专门用于创建和编辑 MuJoCo (Multi-Joint dynamics with Contact) 物理引擎的场景描述文件。MuJoCo 使用一种名为 MJCF (MuJoCo XML Format) 的 XML 기반格式来定义仿真环境中的物体、机器人、光照、纹理等元素及其物理属性。

该编辑器提供了一个直观的3D可视化界面，使用户能够：

  • 可视化地构建场景：直接在3D视图中创建和排列物体。
  • 编辑物体属性：调整物体的尺寸、质量、颜色、碰撞特性等。
  • 管理场景层级：通过树状结构组织复杂的场景。
  • 导入和导出 MJCF 文件：方便地与 MuJoCo 仿真流程集成。

与手动编写复杂的 MJCF XML 代码相比，这款编辑器极大地简化了场景创建和调试的过程，尤其适合需要快速迭代和可视化验证的用户。

1.2 在 DISCOVERSE 中的定位​

本 MuJoCo 场景编辑器是 DISCOVERSE 项目的一个重要子模块，位于 submodules/XML-Editor/ 目录下。它为 DISCOVERSE 中的机器人仿真任务提供了便捷的场景搭建和修改能力，使得研究人员和开发者可以更高效地创建和定制用于机器人学习与控制的仿真环境。

1.3 MuJoCo 和 MJCF 简介​

  • MuJoCo (Multi-Joint dynamics with Contact)：是一个功能强大、速度快、精度高的物理引擎，广泛应用于机器人学、生物力学、机器学习等领域。它特别擅长处理复杂的接触动力学和多关节系统。
  • MJCF (MuJoCo XML Format)：是 MuJoCo 用于描述仿真场景的标准文件格式。它是一种层级化的 XML 格式，通过不同的标签（如 <worldbody>, <body>, <geom>, <joint>, <site>, <tendon>, <actuator> 等）来定义场景的各个组成部分及其属性。MJCF 文件不仅定义了物体的几何形状和外观，还详细描述了它们的物理特性（质量、惯性、摩擦力等）、关节类型和限制、以及传感器和执行器等。

理解 MJCF 的基本结构和常用标签对于高效使用此编辑器和进行 MuJoCo 仿真至关重要。编辑器生成的输出即为 MJCF 文件，可以直接被 MuJoCo 引擎加载。

2. 功能特点​

  • 可视化编辑：直观的3D视图，实时预览场景效果。
  • 基础几何体支持：创建和编辑多种 MJCF 标准几何体类型：
    • 盒子 (Box)
    • 球体 (Sphere)
    • 圆柱体 (Cylinder)
    • 胶囊体 (Capsule)
    • 平面 (Plane)
    • （注意：编辑器可能支持更多或部分 MJCF 几何体，具体以实际版本为准）
  • 变换工具：完整的对象变换功能：
    • 平移 (Translate)
    • 旋转 (Rotate)
    • 缩放 (Scale)
    • 支持全局/局部坐标系切换，方便精确调整。
  • 属性编辑：实时编辑对象属性，如：
    • 几何属性 (尺寸、位置、旋转)
    • 材质属性 (颜色、反射率、透明度)
    • （物理属性如质量、惯性等也可能支持，取决于编辑器具体实现）
  • 层级结构管理：通过树状视图直观地管理场景中 <worldbody> 下的 <body> 元素层级关系，支持父子关系设定和组操作。
  • 导入/导出：支持标准 MuJoCo MJCF XML 格式的导入和导出。
  • 射线投射系统：用于在3D视图中精确地选择对象。
  • 自定义控制器 (Gizmo)：为平移、旋转、缩放等操作模式提供专用的3D交互控制器。

3. 安装指南​

3.1 系统要求​

  • 操作系统：Windows / macOS / Linux
  • Python 版本：>= 3.7
  • 显卡：支持 OpenGL 3.3 或更高版本

3.2 依赖库​

确保已安装以下 Python 库：

  • PyQt5 >= 5.15.0
  • NumPy >= 1.20.0
  • PyOpenGL >= 3.1.0
  • PyOpenGL_accelerate >= 3.1.0 (可选，但建议安装以提高性能)

3.3 安装步骤​

由于此编辑器是 DISCOVERSE 的子模块，其代码已包含在 DISCOVERSE/submodules/XML-Editor/ 目录中。

  1. 确保子模块已检出： 如果在克隆 DISCOVERSE 仓库时没有使用 --recurse-submodules 选项，或者子模块内容为空，请在 DISCOVERSE 仓库的根目录下执行以下命令来初始化并拉取子模块代码：

    git submodule update --init --recursive

  2. 进入子模块目录并安装依赖：

    cd submodules/XML-Editor
    pip install -r requirements.txt

    建议在您的 Python 虚拟环境中执行此操作。

4. 启动与界面概览​

4.1 启动程序​

在已安装依赖并位于 DISCOVERSE/submodules/XML-Editor/ 目录下时，通过以下命令启动编辑器：

python -m xml_editor.main

4.2 主界面介绍​

编辑器启动后，您会看到一个包含以下主要区域的窗口：

  • 3D 视图 (Central Widget)：占据窗口中心区域，用于显示和交互式编辑您的 MuJoCo 场景。
  • 控制面板 (Control Panel - 通常在左侧)：
    • 创建几何体 (Create Geometry)：列出可供拖拽到3D视图中创建的几何体按钮（如立方体、球体等）。
    • 操作模式 (Operation Mode)：切换鼠标在3D视图中的行为，如观察 (Observe)、平移 (Translate)、旋转 (Rotate)、缩放 (Scale)。
    • 坐标系 (Coordinate System)：切换变换工具使用全局坐标系还是局部坐标系。
    • 存档管理 (Save Management)：提供临时存档和加载功能。
  • 层级结构 (Hierarchy - 通常在左侧)：以树状列表显示场景中所有对象的父子关系（对应 MJCF 中的 <body> 层级）。
  • 属性面板 (Properties - 通常在右侧)：显示当前选中对象的详细属性，并允许您编辑这些属性。
  • 菜单栏 (Menu Bar - 顶部)：提供文件操作（新建、打开、保存）、编辑操作（撤销、重做、复制、粘贴、删除）等功能。

5. 详细使用说明​

5.1 场景导航 (3D 视图)​

在 观察 (Observe) 模式下（通常是默认模式，或在控制面板中选择）：

  • 旋转视图：按住鼠标左键并拖动。
  • 平移视图：按住鼠标右键并拖动。
  • 缩放视图：滚动鼠标滚轮。
  • 取消选择：点击场景空白处或按 Esc 键。

5.2 创建几何体​

  • 方法：在左侧的 "控制面板" 中找到 "创建几何体" 部分。这里列出了各种基础几何体类型。
  • 操作：
    1. 将鼠标指针悬停在您想创建的几何体按钮上（例如，"立方体"）。
    2. 按住鼠标左键。
    3. 将鼠标拖拽到主窗口中间的 3D 视图 区域。
    4. 松开鼠标左键，几何体将被放置在鼠标指针指示的位置。
  • 提示：新创建的几何体将自动被选中，其属性会显示在右侧的属性面板中。

5.3 对象选择与编辑​

  • 选择对象：
    • 在3D视图中：左键点击场景中的对象。
    • 在层级结构树中：左键点击对象名称。
  • 多选对象：按住 Ctrl 键，然后依次点击多个对象（在3D视图或层级树中）。
  • 查看属性：选中对象后，在右侧 "属性" 面板中查看其详细属性。
  • 编辑属性：在属性面板中直接修改参数值，更改会实时反映在3D视图中。常见可编辑属性包括：
    • 名称 (Name): 对象的唯一标识符。
    • 可见性 (Visible): 控制对象是否在视图中渲染（通常不影响物理特性）。
    • 位置 (Position): X, Y, Z 坐标。
    • 旋转 (Rotation): X, Y, Z 欧拉角（单位：度）。
    • 尺寸/缩放 (Scale/Size):
      • 立方体 (Box): X, Y, Z 轴的半尺寸。
      • 球体 (Sphere): 半径 (Radius)。
      • 圆柱体 (Cylinder), 胶囊体 (Capsule): 半径 (Radius) 和半长度 (Half-length/Height)。
      • 平面 (Plane): 尺寸通常由其纹理或默认设置决定，可能不可直接编辑或以特定方式编辑。
    • 颜色 (Color): 点击颜色选择器修改。
    • 透明度 (Opacity/Alpha): 调整对象的透明度。

5.4 变换工具 (Gizmo)​

编辑器使用 3D 控制器 (Gizmo) 来辅助对象的平移、旋转和缩放。

  • 选择操作模式：
    • 在左侧 "控制面板" 的 "操作模式" 部分，选择：
      • 观察 (Observe): 仅用于导航场景，不操作对象。
      • 平移 (Translate): 移动选中的对象。
      • 旋转 (Rotate): 旋转选中的对象。
      • 缩放 (Scale): 调整选中对象的大小。
  • 使用 Gizmo：
    • 选中一个对象并进入平移、旋转或缩放模式后，该对象中心会出现一个 Gizmo。
    • Gizmo 通常由红 (X轴)、绿 (Y轴)、蓝 (Z轴) 三个轴组成。
    • 平移：点击并拖动 Gizmo 的轴柄，沿对应轴向移动对象。
    • 旋转：点击并拖动 Gizmo 的圆环，绕对应轴旋转对象。
    • 缩放：点击并拖动 Gizmo 的轴末端方块，沿对应轴缩放对象。
    • 当鼠标悬停在 Gizmo 的某个可操作部分上时，该部分会高亮显示。
  • 全局与局部坐标系：
    • 切换：
      • 点击 "控制面板" > "操作模式" 下方的 "局部坐标系 (Local)" / "全局坐标系 (Global)" 按钮。
      • 或者，在 3D 视图获得焦点时，按 空格键 (Spacebar) 进行切换。
    • 区别：
      • 局部坐标系 (Local)：Gizmo 的轴向会跟随对象自身的旋转方向。
      • 全局坐标系 (Global)：Gizmo 的轴向始终与世界坐标系对齐。

5.5 层级结构管理 (Hierarchy Panel)​

左侧的 "层级结构 (Hierarchy)" 面板以树状视图展示了场景中所有对象的父子关系，这对应 MJCF 中 <body> 元素的嵌套。

  • 理解层级:
    • 父节点 (Parent): 通常是一个 组 (Group) (在 MJCF 中是一个包含其他 <body> 或 <geom> 的 <body> 元素)。父节点的变换会影响其所有子节点。
    • 子节点 (Child): 隶属于某个父节点的对象。其坐标和旋转是相对于父节点的。
  • 查看与选择:
    • 点击树中的项来选择对象。
    • 点击组节点旁的 ▶ (展开) 或 ▼ (折叠) 符号可显示或隐藏其子对象。
  • 创建对象 (通过层级树):
    • 创建顶层对象/组: 在层级树面板的空白区域右键点击 -> "新建 (New)" -> 选择类型。
    • 创建子对象/组: 在一个组节点上右键点击 -> "新建子对象 (New Child)" -> 选择类型。
  • 组合对象 (Grouping):
    1. 使用 Ctrl+点击 选择多个对象。
    2. 在任一选中对象上右键点击 -> "组合到新组 (Group into New Group)"。
  • 修改层级 (Reparenting - 拖放):
    1. 在层级树中，用鼠标左键点击并按住要移动的对象。
    2. 拖拽对象：
      • 到另一个组节点上：成为该组的子节点。
      • 到一个非组几何体上：通常会创建一个新组，并将两者放入其中。
      • 到层级树的空白区域：移动到场景顶层。
  • 复制与粘贴:
    • 复制: 选中对象 -> 右键 -> "复制 (Copy)" (或 Ctrl+C)。
    • 粘贴:
      • 在目标组节点上右键 -> "粘贴到这个组 (Paste into this group)"。
      • 在空白区域右键 -> "粘贴 (Paste)" (或 Ctrl+V)，通常粘贴到顶层。
  • 删除: 选中对象 -> 按 Delete 键 或 右键 -> "删除 (Delete)"。
  • 重命名: 右键点击单个对象 -> "重命名 (Rename)"，或在属性面板中修改名称。

5.6 主菜单栏功能​

  • 文件 (File):
    • 新建 (New) (Ctrl+N): 创建空场景。
    • 打开 (Open)... (Ctrl+O): 加载 MJCF XML 文件。
    • 保存 (Save) (Ctrl+S): 保存当前场景到原文件。
    • 另存为 (Save As)... (Shift+Ctrl+S): 将场景另存为新的 MJCF XML 文件。
    • 退出 (Exit) (Ctrl+Q): 关闭编辑器。
  • 编辑 (Edit):
    • 撤销 (Undo) (Ctrl+Z): 撤销上一步操作。
    • 重做 (Redo) (Ctrl+Y / Shift+Ctrl+Z): 恢复被撤销的操作。
    • 复制 (Copy) (Ctrl+C)
    • 粘贴 (Paste) (Ctrl+V)
    • 删除 (Delete) (Delete 键)
  • 视图 (View):
    • 重置视图 (Reset View): 恢复3D视图摄像机和面板布局到默认状态。
  • 帮助 (Help):
    • 关于 (About): 显示编辑器版本等信息。

5.7 撤销与重做​

  • 编辑器会自动记录大部分操作（创建、删除、变换、属性修改、层级变更等）。
  • 使用菜单栏 "编辑 (Edit)" > "撤销 (Undo)" 或 "重做 (Redo)"，或对应快捷键。
  • 注意：关闭程序时，撤销/重做历史会清空。

5.8 存档管理 (JSON Save Points)​

此功能用于快速创建场景的临时存档点 (JSON格式)，不同于标准的 MJCF XML 保存。

  • 位置: 左侧 "控制面板" 底部的 "存档管理"。
  • 创建存档点 (Create Save Point): 点击按钮，当前场景状态保存为带时间戳的 JSON 文件 (通常在 submodules/XML-Editor/save/ 目录下)。
  • 查看存档 (View Saves): 点击按钮，弹出对话框列出最近的 JSON 存档。
    • 加载存档: 在列表中选择存档并点击 "加载 (Load)" 或双击存档。
    • 注意: 加载存档会覆盖当前场景，此操作通常不可撤销。

5.9 操作示例​

  1. 启动编辑器：cd DISCOVERSE/submodules/XML-Editor && python -m xml_editor.main
  2. 创建基础物体：
    • 从 控制面板 > 创建几何体 拖拽一个 "平面 (Plane)" 到3D视图作为地面。
    • 在 属性面板 中调整其名称 (e.g., "ground_plane")、尺寸和颜色。
    • 拖拽一个 "立方体 (Box)"，放置在地面上。修改其名称、颜色。
  3. 变换物体：
    • 选中立方体。
    • 在 控制面板 > 操作模式 中选择 "旋转 (Rotate)"。
    • 使用 Gizmo 绕其局部Y轴旋转。
    • 切换到 "平移 (Translate)" 模式，移动立方体。
    • 尝试切换 "局部/全局坐标系" 并观察 Gizmo 行为。
  4. 层级管理：
    • 创建另一个物体，例如一个 "球体 (Sphere)"。
    • 在 层级结构 面板中，按住 Ctrl 键选中立方体和球体。
    • 右键点击选中项 -> "组合到新组 (Group into New Group)"。
    • 重命名新创建的组 (e.g., "dynamic_objects_group")。
    • 选中该组，使用平移/旋转工具操作整个组。
  5. 属性编辑：
    • 选中任意物体或组。
    • 在 属性面板 中修改其位置、旋转、颜色、透明度等参数。
  6. 文件操作：
    • 保存场景: 文件 (File) -> 另存为 (Save As)... -> 输入文件名 (e.g., my_custom_scene.xml)。
    • (可选) 创建存档点: 控制面板 -> 创建存档点。
    • (可选) 加载存档: 控制面板 -> 查看存档 -> 选择并加载。
  7. 最终检查：加载保存的 my_custom_scene.xml 到 MuJoCo 仿真器中，检查场景是否符合预期。

希望这份指南能帮助您更好地在 DISCOVERSE 项目中使用 MuJoCo 场景编辑器！