# iFlow 上下文文档 ## 项目概述 这是一个基于 Panda3D 和 PyQt5 的 3D 虚拟现实 (VR) 应用程序框架。该项目旨在提供一个功能齐全、模块化的 3D 环境，支持 VR 设备（如 HTC Vive, Oculus Rift）的集成，包含场景管理、模型导入、GUI 系统、脚本系统、地形系统、碰撞检测、视频播放、插件系统以及完整的 VR 交互功能。 核心架构围绕 `MyWorld` 类构建，该类继承自 `CoreWorld`，并集成了各种管理器模块，如选择系统、工具管理器、脚本管理器、GUI 管理器、场景管理器、项目管理器、地形管理器、碰撞管理器、视频管理器、资源管理器和 VR 管理器。 ## 核心技术栈 - **核心引擎**: Panda3D 1.10.15 - **图形渲染**: 可选择普通渲染或 RenderPipeline 高级渲染管线 - **VR 支持**: OpenVR/SteamVR 2.2.0 - **用户界面**: PyQt5 5.15.9 + ImGui 集成 - **3D 模型格式**: 支持 glTF, FBX (需转换), BAM, EGG, OBJ 等 - **脚本语言**: Python (内嵌脚本系统) - **物理/碰撞**: Panda3D 内置碰撞系统 - **视频支持**: MovieTexture (MP4, AVI, MOV, MKV, WebM) - **插件架构**: 动态插件加载系统 - **资源管理**: 文件浏览、拖拽、右键菜单集成 ## 项目结构 ``` . ├── core/ # 核心模块 │ ├── world.py # CoreWorld 基础世界类 │ ├── vr/ # VR 子模块 (完整模块化结构) │ │ ├── __init__.py │ │ ├── config/ # VR 配置管理 │ │ ├── interaction/ # VR 交互系统 (动作、抓取、摇杆、传送) │ │ ├── performance/ # VR 性能监控 │ │ ├── rendering/ # VR 渲染相关 (RenderPipeline 集成) │ │ ├── testing/ # VR 测试模式 │ │ ├── tracking/ # VR 设备跟踪 │ │ └── visualization/ # VR 可视化 (控制器模型) │ ├── drag_drop/ # 拖拽文件监控系统 │ ├── 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 # 装配交互系统 ├── demo/ # 示例和测试文件 (包含大量测试和演示) ├── gui/ # GUI 相关模块 ├── project/ # 项目管理模块 ├── scene/ # 场景管理模块 ├── scripts/ # 脚本文件目录 ├── ui/ # UI 组件和主窗口 │ ├── widgets.py # 自定义UI组件 │ ├── property_panel.py # 属性面板 │ ├── interface_manager.py # 界面管理器 │ ├── main_window.py # 主窗口 │ ├── icon_manager.py # 图标管理器 │ └── maintenance_system.py # 维护系统UI ├── plugins/ # 插件系统 │ ├── core/ # 核心插件 │ ├── third_party/ # 第三方插件 │ ├── user/ # 用户插件 │ ├── plugin_manager.py # 插件管理器 │ └── plugin_interface_spec.py # 插件接口规范 ├── QPanda3D/ # Panda3D 与 PyQt 集成库 ├── QMeta3D/ # Meta3D 集成库 ├── RenderPipelineFile/ # RenderPipeline 高级渲染管线 ├── Resources/ # 资源文件 (模型、纹理等) ├── config/ # 配置文件 │ └── vr_settings.json # VR 配置文件 ├── requirements/ # 依赖项文件 │ ├── requirements.txt # 主要依赖项 │ ├── conda-requirements.txt # Conda环境依赖 │ └── clean-requirements.txt # 精简依赖项 ├── vr_actions/ # VR动作配置 ├── icons/ # 图标资源 ├── templates/ # 模板文件 ├── tools/ # 工具脚本 ├── tex/ # 纹理资源 ├── main.py # 程序入口点 ├── demo.py # ImGui演示程序 ├── gui_preview_window.py # GUI预览窗口 ├── Start_Run.py # 启动脚本 └── imgui.ini # ImGui配置文件 ``` ## 核心功能模块 ### 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/) - **GUIManager**: 管理 2D 和 3D GUI 元素的创建、编辑、删除。 - **功能**: - 创建按钮、标签、输入框、2D/3D 图像、视频屏幕等。 - GUI 编辑模式，支持拖拽创建和属性编辑。 - 与场景树和属性面板集成。 - 独立的 GUI 预览窗口 (`gui_preview_window.py`)。 - ImGui 集成支持现代化的界面设计。 ### 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` 实例并启动 PyQt5 主窗口。 - `demo.py`: ImGui演示程序，展示现代化界面功能。 - `Start_Run.py`: 启动脚本。 - `gui_preview_window.py`: GUI预览窗口，用于独立测试GUI元素。 ### 运行方式 1. 确保已安装所有依赖项（详见 requirements/requirements.txt）。 2. 运行 `python main.py` 启动主应用程序。 3. 运行 `python demo.py` 启动ImGui演示程序。 4. 如果连接了 VR 设备并安装了 SteamVR，可以在应用内启用 VR 模式。 5. VR配置可通过 `config/vr_settings.json` 进行调整。 ### 依赖项 项目提供完整的依赖项文件在 `requirements/` 目录： - **requirements.txt**: 主要依赖项，包含： - `Panda3D==1.10.15` (核心3D引擎) - `PyQt5==5.15.9` (GUI框架) - `openvr==2.2.0` (VR支持) - `p3dimgui` (ImGui集成) - `QPanda3D==0.2.10` (Panda3D与PyQt5集成) - 以及其他辅助库 - **conda-requirements.txt**: Conda环境依赖项 - **clean-requirements.txt**: 精简依赖项 安装命令： ```bash pip install -r requirements/requirements.txt ``` ## 开发约定 - **模块化设计**: 功能被分解到不同的管理器类中，`MyWorld` 主要起到集成和代理的作用。 - **VR 子模块化**: VR 功能被组织在 `core/vr/` 目录下，具有清晰的子模块划分。 - **配置驱动**: VR 设置通过 `config/vr_settings.json` 文件进行管理，ImGui配置通过 `imgui.ini` 管理。 - **性能意识**: VR 模块包含大量性能优化措施，如对象池、缓存、智能同步等。 - **向后兼容**: `MyWorld` 通过属性代理保持与旧代码的兼容性。 - **测试模式**: VR 系统包含专门的测试模式，便于调试和验证不同功能。 - **插件架构**: 支持动态插件加载，核心插件、第三方插件和用户插件分离管理。 - **资源管理**: 使用ImGui风格的资源管理器，支持拖拽、右键菜单等现代交互。 - **视频集成**: 完整的视频播放支持，包括2D/3D屏幕和360度球形视频。 - **国际化支持**: 内置中文字体支持，适合中文环境开发。 - **事件驱动**: 完善的事件处理系统，支持键盘快捷键（如F键聚焦、P键巡检）。 - **命令模式**: 使用命令系统实现撤销/重做功能。 - **演示系统**: demo/ 目录包含大量测试和演示文件，便于功能验证和学习。