7.4 KiB
7.4 KiB
iFlow 上下文文档
项目概述
这是一个基于 Panda3D 和 PyQt5 的 3D 虚拟现实 (VR) 应用程序框架。该项目旨在提供一个功能齐全、模块化的 3D 环境，支持 VR 设备（如 HTC Vive, Oculus Rift）的集成，包含场景管理、模型导入、GUI 系统、脚本系统、地形系统、碰撞检测以及完整的 VR 交互功能。
核心架构围绕 MyWorld 类构建，该类继承自 CoreWorld，并集成了各种管理器模块，如选择系统、工具管理器、脚本管理器、GUI 管理器、场景管理器、项目管理器、地形管理器、碰撞管理器和 VR 管理器。
核心技术栈
- 核心引擎: Panda3D
- 图形渲染: 可选择普通渲染或 RenderPipeline 高级渲染管线
- VR 支持: OpenVR/SteamVR
- 用户界面: PyQt5
- 3D 模型格式: 支持 glTF, FBX (需转换), BAM 等
- 脚本语言: Python (内嵌脚本系统)
- 物理/碰撞: Panda3D 内置碰撞系统
项目结构
.
├── core/ # 核心模块
│ ├── world.py # CoreWorld 基础世界类
│ ├── vr/ # VR 子模块 (完整模块化结构)
│ │ ├── __init__.py
│ │ ├── 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 # 信息面板管理器
├── demo/ # 示例和测试文件
├── gui/ # GUI 相关模块
├── project/ # 项目管理模块
├── scene/ # 场景管理模块 (部分代码在 core/)
├── scripts/ # 脚本文件目录
├── ui/ # UI 组件和主窗口
├── QPanda3D/ # Panda3D 与 PyQt 集成库
├── Resources/ # 资源文件 (模型、纹理等)
├── config/ # 配置文件
│ └── vr_settings.json # VR 配置文件
├── main.py # 程序入口点
└── Start_Run.py # 启动脚本
核心功能模块
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 预览窗口。
4. 场景与模型管理 (core/scene_manager.py)
- SceneManager: 管理 3D 场景中的所有模型。
- 功能:
- 模型导入 (支持 glTF, FBX 转换)。
- 材质和几何体处理。
- 碰撞体设置。
- 场景保存/加载 (BAM 格式)。
- 场景树更新。
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: 处理对象选择逻辑和相机聚焦。
构建与运行
入口点
main.py: 主程序入口，创建MyWorld实例并启动 PyQt5 主窗口。Start_Run.py: 可能的启动脚本。
运行方式
- 确保已安装所有依赖项（Panda3D, PyQt5, OpenVR 等）。
- 运行
python main.py启动应用程序。 - 如果连接了 VR 设备并安装了 SteamVR，可以在应用内启用 VR 模式。
依赖项
项目未提供 requirements.txt 文件，但根据代码分析，主要依赖包括：
panda3dPyQt5openvr(用于 VR 功能)numpy(在 VR 模块中使用)
开发约定
- 模块化设计: 功能被分解到不同的管理器类中，
MyWorld主要起到集成和代理的作用。 - VR 子模块化: VR 功能被组织在
core/vr/目录下，具有清晰的子模块划分。 - 配置驱动: VR 设置通过
config/vr_settings.json文件进行管理。 - 性能意识: VR 模块包含大量性能优化措施，如对象池、缓存、智能同步等。
- 向后兼容:
MyWorld通过属性代理保持与旧代码的兼容性。 - 测试模式: VR 系统包含专门的测试模式，便于调试和验证不同功能。