Rowland/EG

2026-01-27 10:04:02 +08:00

16 KiB

Raw Blame History

iFlow 上下文文档

项目概述

这是一个基于 Panda3D 和 PyQt5 的 3D 虚拟现实 (VR) 应用程序框架。该项目旨在提供一个功能齐全、模块化的 3D 环境，支持 VR 设备（如 HTC Vive, Oculus Rift）的集成，包含场景管理、模型导入、GUI 系统、脚本系统、地形系统、碰撞检测、视频播放、插件系统以及完整的 VR 交互功能。

核心架构围绕 MyWorld 类构建，该类继承自 CoreWorld，并集成了各种管理器模块，如选择系统、工具管理器、脚本管理器、GUI 管理器、场景管理器、项目管理器、地形管理器、碰撞管理器、视频管理器、资源管理器和 VR 管理器。

项目目前处于 "imgui" 分支，已全面转向基于 ImGui 的现代化用户界面，提供了完整的 dockable 界面系统，包括菜单栏、工具栏、场景树、资源管理器、属性面板和控制台等组件。

核心技术栈

核心引擎: Panda3D 1.10.15
图形渲染: 可选择普通渲染或 RenderPipeline 高级渲染管线
VR 支持: OpenVR/SteamVR 2.2.0
用户界面: PyQt5 5.15.9 + ImGui 集成 (imgui_bundle)
3D 模型格式: 支持 glTF, FBX (需转换), BAM, EGG, OBJ 等
脚本语言: Python (内嵌脚本系统)
物理/碰撞: Panda3D 内置碰撞系统
视频支持: MovieTexture (MP4, AVI, MOV, MKV, WebM)
插件架构: 动态插件加载系统
资源管理: 文件浏览、拖拽、右键菜单集成
GUI 框架: p3dimgui + imgui_bundle (支持 docking 功能)
拖拽系统: 跨平台拖拽文件监控系统 (core/drag_drop/)

项目结构

.
├── core/                      # 核心模块
│   ├── world.py               # CoreWorld 基础世界类
│   ├── vr/                    # VR 子模块 (完整模块化结构)
│   │   ├── __init__.py
│   │   ├── README.md
│   │   ├── config/            # VR 配置管理
│   │   ├── interaction/       # VR 交互系统 (动作、抓取、摇杆、传送)
│   │   ├── performance/       # VR 性能监控
│   │   ├── rendering/         # VR 渲染相关 (RenderPipeline 集成)
│   │   ├── testing/           # VR 测试模式
│   │   ├── tracking/          # VR 设备跟踪
│   │   └── visualization/     # VR 可视化 (控制器模型)
│   ├── vr_manager.py          # VR 管理器主文件
│   ├── selection.py           # 选择系统
│   ├── tool_manager.py        # 工具管理器
│   ├── script_system.py       # 脚本系统
│   ├── gui_manager.py         # GUI 管理器
│   ├── terrain_manager.py     # 地形管理器
│   ├── collision_manager.py   # 碰撞管理器
│   ├── event_handler.py       # 事件处理器
│   ├── patrol_system.py       # 巡检系统
│   ├── Command_System.py      # 命令系统
│   ├── InfoPanelManager.py    # 信息面板管理器
│   ├── resource_manager.py    # 资源管理器 (ImGui版本)
│   ├── CustomMouseController.py # 自定义鼠标控制器
│   ├── maintenance_gui.py     # 维护GUI系统
│   ├── assembly_interaction.py # 装配交互系统
│   ├── imgui_style_manager.py # ImGui样式管理器
│   └── [工具模型文件]          # .fbx 格式的工具手柄模型
│       ├── RotationHandleFull.fbx
│       ├── RotationHandleQuarter.fbx
│       ├── TranslateArrowHandle.fbx
│       └── UniformScaleHandle.fbx
├── gui/                       # GUI 相关模块
│   ├── __init__.py
│   └── gui_manager.py         # GUI管理器
├── project/                   # 项目管理模块
│   ├── __init__.py
│   └── project_manager.py
├── scene/                     # 场景管理模块
│   ├── __init__.py
│   ├── scene_manager.py
│   └── util.py
├── scripts/                   # 脚本文件目录
│   └── [各种脚本文件]
├── ui/                        # UI 组件
│   ├── __init__.py
│   └── icon_manager.py        # 图标管理器
├── plugins/                   # 插件系统
│   ├── __init__.py
│   ├── plugin_manager.py
│   ├── plugin_interface_spec.py
│   ├── core/                  # 核心插件
│   ├── third_party/           # 第三方插件
│   └── user/                  # 用户插件
├── QPanda3D/                  # Panda3D 与 PyQt 集成库
├── QMeta3D/                   # Meta3D 集成库
├── RenderPipelineFile/        # RenderPipeline 高级渲染管线
├── Resources/                 # 资源文件 (模型、纹理等)
│   ├── a/                     # 资源子目录
│   ├── animations/
│   ├── c/
│   ├── icons/
│   ├── materials/
│   ├── models/
│   └── textures/
├── config/                    # 配置文件
│   └── vr_settings.json       # VR 配置文件
├── requirements/              # 依赖项文件
│   ├── requirements.txt       # 主要依赖项
│   ├── conda-requirements.txt # Conda环境依赖
│   ├── clean-requirements.txt # 精简依赖项
│   └── DEPLOYMENT_README.md   # 部署说明
├── vr_actions/                # VR动作配置
│   ├── actions.json
│   ├── bindings_index.json
│   ├── bindings_oculus.json
│   └── bindings_vive.json
├── icons/                     # 图标资源
│   └── file_types/            # 文件类型图标
├── templates/                 # 模板文件
│   └── main_template.py
├── tools/                     # 工具脚本
│   └── open_source_rate.py
├── tex/                       # 纹理资源
│   ├── empty_basecolor.png
│   ├── empty_normal.png
│   ├── empty_roughness.png
│   └── empty_specular.png
├── new/                       # 新项目目录
│   └── project.json
├── test_project/              # 测试项目
│   └── project.json
├── main.py                    # 程序入口点 (集成ImGui界面)
├── Start_Run.py               # 启动脚本
├── imgui.ini                  # ImGui配置文件
└── IFLOW.md                   # 项目文档

核心功能模块

1. World (core/world.py, main.py)

CoreWorld: 基础 3D 世界设置，包括相机、光照、地面、资源路径。
MyWorld: 扩展的主世界类，整合所有管理器和功能模块。
- 初始化: 设置资源路径、相机、光照、地面，加载中文字体。
- 兼容性: 提供旧版属性访问接口。
- 功能代理: 将大量功能委托给专门的管理器。
- 新增集成: 视频管理器、资源管理器、插件系统等。

2. VR 系统 (core/vr/)

这是一个高度模块化的 VR 子系统，核心是 VRManager (core/vr_manager.py)。

VRManager:
- 初始化与状态管理: 检查 VR 可用性、初始化 OpenVR、管理启用/禁用状态。
- 渲染系统:
  - 支持普通渲染和 RenderPipeline 高级渲染两种模式。
  - 创建和管理左右眼的渲染缓冲区和相机。
  - 实现高效的纹理提交到 OpenVR Compositor。
  - 支持动态分辨率缩放和质量预设。
- 跟踪系统:
  - 通过 OpenVR 获取 HMD 和控制器的姿态。
  - 使用锚点层级系统 (tracking_space, hmd_anchor 等) 管理设备位置。
  - 坐标系转换 (OpenVR 到 Panda3D)。
- 控制器:
  - LeftController, RightController: 管理具体的手柄输入和可视化。
  - 支持动作系统 (VRActionManager) 或直接输入读取。
- 交互系统:
  - VRInteractionManager: 对象抓取和交互。
  - VRTeleportSystem: 传送功能。
  - VRJoystickManager: 摇杆移动控制。
- 性能优化:
  - 对象池 (Mat4) 减少 GC 压力。
  - 纹理 ID 缓存避免重复 prepare。
  - 智能 GPU 同步策略。
  - 性能模式自动切换。
- 配置管理:
  - VRConfigManager: 从 config/vr_settings.json 加载/保存配置。
- 测试与调试:
  - VRTestMode: 提供不同的测试显示模式和功能开关。
  - VRPerformanceMonitor: 性能监控和报告。

3. GUI 系统 (core/gui_manager.py, gui/, core/imgui_style_manager.py)

GUIManager: 管理 2D 和 3D GUI 元素的创建、编辑、删除。
ImGui 集成: 完整的 ImGui 界面系统，支持 docking 功能。
功能:
- 创建按钮、标签、输入框、2D/3D 图像、视频屏幕等。
- GUI 编辑模式，支持拖拽创建和属性编辑。
- 与场景树和属性面板集成。
- 现代化界面: 基于 imgui_bundle 的完整 docking 界面系统，包括：
  - 菜单栏 (文件、编辑、创建、视图、工具、VR、帮助)
  - 工具栏 (选择、移动、旋转、缩放工具)
  - 场景树 (层级结构显示和管理)
  - 资源管理器 (文件浏览、拖拽导入)
  - 属性面板 (对象属性编辑)
  - 控制台 (信息输出)
  - 脚本管理面板
- ImGui 样式管理: ImGuiStyleManager 提供统一的界面风格管理。
- 中文字体支持: 自动加载中文字体，适合中文环境开发。
- 快捷键支持: 完整的键盘快捷键系统。

4. 场景与模型管理 (scene/scene_manager.py)

SceneManager: 管理 3D 场景中的所有模型。
功能:
- 模型导入 (支持 glTF, FBX 转换, BAM, EGG, OBJ)。
- 材质和几何体处理。
- 碰撞体设置。
- 场景保存/加载 (BAM 格式)。
- 场景树更新。
- Cesium 3D Tiles 支持 (load_cesium_tileset)。

5. 脚本系统 (core/script_system.py)

ScriptManager: 嵌入式 Python 脚本系统。
功能:
- 脚本文件的创建、加载、重载。
- 为游戏对象挂载/卸载脚本。
- 热重载支持。
- 脚本信息查询。

6. 地形系统 (core/terrain_manager.py)

TerrainManager: 管理 3D 地形。
功能:
- 从高度图或创建平面地形。
- 地形 LOD 更新。
- 地形高度查询和编辑。

7. 碰撞系统 (core/collision_manager.py)

CollisionManager: 处理场景中的碰撞检测。
功能:
- 模型间碰撞检测。
- 碰撞历史和统计。

8. 工具与选择系统 (core/tool_manager.py, core/selection.py)

ToolManager: 管理当前使用的工具 (选择、移动、旋转、缩放)。
SelectionSystem: 处理对象选择逻辑和相机聚焦。
CustomMouseController: 自定义鼠标控制器，增强交互体验。

9. 视频系统 (demo/video_integration.py)

VideoManager: 视频播放管理器。
功能:
- 支持多种视频格式 (MP4, AVI, MOV, MKV, WebM)。
- 2D/3D 视频屏幕创建。
- 360度球形视频播放。
- 视频控制 (播放、暂停、时间定位)。

10. 资源管理系统 (core/resource_manager.py)

ResourceManager: ImGui风格的资源管理器。
功能:
- 文件浏览和导航。
- 图标显示和文件类型识别。
- 右键菜单操作。
- 搜索和过滤功能。
- 拖拽支持。
- 文件系统监控和自动刷新。

11. 插件系统 (plugins/)

PluginManager: 动态插件加载和管理系统。
功能:
- 插件生命周期管理 (初始化、启用、禁用、清理)。
- 核心插件、第三方插件和用户插件分类。
- 插件接口规范 (BasePlugin 基类)。
- 插件配置管理。

12. 信息面板系统 (core/InfoPanelManager.py)

InfoPanelManager: 信息面板管理器。
功能:
- 实时信息显示。
- 系统状态监控。
- 调试信息输出。

13. 巡检系统 (core/patrol_system.py)

PatrolSystem: 自动巡检系统。
功能:
- 巡检点管理。
- 自动路径导航。
- 巡检状态控制 (P键切换)。
- 默认巡检路线创建。

14. 命令系统 (core/Command_System.py)

CommandManager: 命令管理模式。
功能:
- 撤销/重做支持。
- 命令历史管理。
- 操作封装和批处理。

15. 装配交互系统 (core/assembly_interaction.py)

AssemblyInteraction: 装配和拆卸交互系统。
功能:
- 装配流程管理。
- 零部件识别和匹配。
- 装配步骤指导。

16. 维护系统 (core/maintenance_gui.py, ui/maintenance_system.py)

MaintenanceGUI: 维护界面系统。
功能:
- 维护任务管理。
- 故障诊断界面。
- 维护记录和报告。

构建与运行

入口点

main.py: 主程序入口，创建 MyWorld 实例并启动基于 ImGui 的现代化界面。
Start_Run.py: 启动脚本。

运行方式

确保已安装所有依赖项（详见 requirements/requirements.txt）。
运行 python main.py 启动主应用程序，将显示完整的 ImGui 界面。
如果连接了 VR 设备并安装了 SteamVR，可以通过菜单 "VR" -> "进入VR模式" 启用 VR 模式。
VR配置可通过 config/vr_settings.json 进行调整，或在界面中通过 "VR" -> "VR设置" 进行配置。

依赖项

项目提供完整的依赖项文件在 requirements/ 目录：

requirements.txt: 完整依赖项，包含：
- Panda3D==1.10.15 (核心3D引擎)
- PyQt5==5.15.9 (GUI框架)
- PySide6>=6.8.1 (Qt6支持)
- openvr==2.2.0 (VR支持)
- p3dimgui (ImGui集成)
- QPanda3D==0.2.10 (Panda3D与PyQt5集成)
- Pillow>=9.0.1 (图像处理)
- python-dotenv>=1.0.1 (环境变量管理)
- pyassimp>=5.2.5 (3D模型导入)
- 以及其他辅助库
clean-requirements.txt: 精简依赖项，仅包含核心库
conda-requirements.txt: Conda环境依赖项 (基础Python环境)
DEPLOYMENT_README.md: 部署说明文档

安装命令：

# 安装完整依赖
pip install -r requirements/requirements.txt

# 或安装精简依赖
pip install -r requirements/clean-requirements.txt

开发约定

模块化设计: 功能被分解到不同的管理器类中，MyWorld 主要起到集成和代理的作用。
VR 子模块化: VR 功能被组织在 core/vr/ 目录下，具有清晰的子模块划分。
配置驱动: VR 设置通过 config/vr_settings.json 文件进行管理，ImGui配置通过 imgui.ini 管理。
性能意识: VR 模块包含大量性能优化措施，如对象池、缓存、智能同步等。
向后兼容: MyWorld 通过属性代理保持与旧代码的兼容性。
测试模式: VR 系统包含专门的测试模式，便于调试和验证不同功能。
插件架构: 支持动态插件加载，核心插件、第三方插件和用户插件分离管理。
资源管理: 使用ImGui风格的资源管理器，支持拖拽、右键菜单等现代交互。
视频集成: 完整的视频播放支持，包括2D/3D屏幕和360度球形视频。
国际化支持: 内置中文字体支持，适合中文环境开发。
事件驱动: 完善的事件处理系统，支持键盘快捷键（如F键聚焦、P键巡检）。
命令模式: 使用命令系统实现撤销/重做功能。
拖拽系统: 跨平台拖拽文件监控系统，支持从外部文件管理器拖拽模型到场景中。
ImGui Docking: 完整的 docking 界面系统，支持窗口自由布局和停靠。
分支管理: 当前开发在 "imgui" 分支，专注于基于 ImGui 的现代化界面开发。
工具集成: 内置多种工具手柄模型，支持专业的3D变换操作。

16 KiB Raw Blame History Unescape Escape