orca-gym 26.3.2

OrcaGym Core - Cloud-native robotics simulation platform compatible with Gymnasium API

OrcaGym

欢迎来到 OrcaGym！这是 OrcaGym 的核心库，提供与 OpenAI Gym/Gymnasium 接口兼容的机器人仿真环境。与松应科技的 OrcaStudio、OrcaLab 平台联合开发，OrcaGym 为多物理引擎和分布式仿真提供强大支持，同时保持与流行 RL 框架的编程接口兼容性。

样例与数据采集已迁移
原仓库中的遥操作、数据采集与相关示例已独立至 OrcaManipulation，欢迎体验：

• 克隆：https://github.com/openverse-orca/OrcaManipulation.git
• 主页：https://github.com/openverse-orca/OrcaManipulation

注意: orca-gym PyPI 包仅包含核心功能模块。强化学习、模仿学习、输入设备、数据采集等应用层示例请前往上述 OrcaManipulation 仓库，并按其文档安装依赖；本仓库仍可通过可选依赖 pip install orca-gym[rl] 等安装算法侧常用库。

背景

机器人仿真作为具身智能训练的关键平台，需要物理准确性和可扩展的基础设施。传统解决方案往往在保真度和计算效率之间面临权衡，特别是在扩展到分布式系统时。OrcaGym 通过将实时物理仿真与云原生架构相结合来弥合这一差距，使研究人员能够在高保真环境中原型化算法并在大规模部署。

目的

OrcaGym 旨在：

1. 提供与 OpenAI Gym/Gymnasium API 兼容的 GPU 加速仿真环境
2. 通过 OrcaStudio、OrcaLab 集成支持多种物理后端（Mujoco、PhysX、ODE）
3. 实现跨异构计算节点的分布式训练场景
4. 通过光线追踪为基于视觉的 RL 任务提供逼真的渲染

主要特性

• 🎮 Gym/Gymnasium API 兼容性 - 与现有 RL 算法无缝集成
• ⚡ 多物理后端 - 同时进行 Mujoco/PhysX/ODE 仿真
• 🌐 分布式部署 - 通过 gRPC 实现混合本地/远程操作
• 🔍 光线追踪渲染 - 逼真的视觉观察
• 🤖 多智能体支持 - 原生异构智能体管理

安装

从 PyPI 安装（推荐）

# 安装核心包
pip install orca-gym

# 或者安装带可选依赖的版本
pip install orca-gym[rl]          # 强化学习训练
pip install orca-gym[imitation]   # 模仿学习
pip install orca-gym[devices]     # 输入设备支持
pip install orca-gym[sensors]     # 相机和传感器
pip install orca-gym[all]         # 所有可选依赖

从源码安装（开发者）

# 克隆仓库
git clone https://github.com/openverse-orca/OrcaGym.git
cd OrcaGym

# 初始化资源和子模块（如果需要运行示例）
git lfs install
git lfs pull
git submodule update --init --recursive

# 创建 Python 环境
conda create -n orca python=3.12
conda activate orca

# 安装核心包
pip install -e .

# 全量安装
pip install -e ".[all]"

# 或者安装开发依赖
pip install -e ".[dev]"

# 安装可选依赖
pip install -e ".[rl]"
pip install -e ".[imitation]"
pip install -e ".[devices]"
pip install -e ".[sensors]"

应用示例与数据采集

• 遥操作、HDF5 采集、数据增强等：请克隆 OrcaManipulation，跟随其 README.md / QUICK_START.md 安装与运行。
• 本包可选依赖（算法与工具链，按需安装）：
  • pip install orca-gym[rl] — 强化学习常见依赖（如 SB3）
  • pip install orca-gym[imitation] — 模仿学习相关
  • pip install orca-gym[devices] — 输入设备支持

OrcaStudio、OrcaLab 配置

从官方门户下载并安装 OrcaStudio、OrcaLab

使用 orcagym-loop 命令启动仿真循环

orcagym-loop 是一个用于测试的常用脚本，用于启动基本的仿真循环。安装 orca-gym 后，可以直接使用该命令。

使用 OrcaStudio 的情况：

1. 在 OrcaStudio 中，点击"运行"按钮（或按快捷键 Ctrl+G）启动仿真服务器
2. 在控制台执行 orcagym-loop 命令，启动仿真循环
3. 仿真将在本地 localhost:50051 地址上运行

使用 OrcaLab 的情况：

1. 在 OrcaLab 中点击"运行"按钮启动仿真服务器
2. 选择"无仿真程序"选项
3. 在控制台执行 orcagym-loop 命令，启动仿真循环
4. 仿真将在本地 localhost:50051 地址上运行

命令示例：

# 安装 orca-gym 后，直接运行
orcagym-loop

该命令会启动一个基本的仿真循环，按 Ctrl+C 可以停止仿真。

核心包说明

orca-gym 包含以下核心模块：

• core: 核心仿真接口，支持本地 (Mujoco) 和远程 (gRPC) 模式
• environment: Gymnasium 兼容的环境基类
• protos: gRPC 协议定义
• scene: 场景管理和运行时
• utils: 实用工具函数（旋转、控制器等）

不包含（已迁移）：

• 训练 / 遥操作 / 数据采集等应用示例与配套环境 → 见 OrcaManipulation（克隆地址）

说明：orca-gym 发行包仍包含 orca_gym 下的 adapters / devices / sensor / tools / scripts 等扩展模块；其中部分能力依赖可选安装（如 [rl]、[devices]）。文档、第三方源码（doc/、3rd_party/）不进入 PyPI 包。

使用示例

完整可运行示例（含数据采集、VR 遥控、数据增强等）已迁移至 OrcaManipulation：

git clone https://github.com/openverse-orca/OrcaManipulation.git
cd OrcaManipulation
# 详见仓库内 README / QUICK_START.md

欢迎体验：OrcaManipulation 主页 · Git 克隆地址

本仓库：安装 orca-gym 后，可使用 orcagym-loop 与 OrcaStudio / OrcaLab 联调（见上文「使用 orcagym-loop 命令」）；在自有代码中继承 orca_gym 的环境与核心 API 搭建自定义环境即可。

性能与配置考虑

• 远程模式: 需要配置并运行 OrcaStudio 或 OrcaLab。请参考官方门户获取安装和配置指南。
• 本地模式: 使用 Mujoco 进行本地仿真，适合快速原型开发和测试。
• 兼容性: OrcaGym 完全兼容 Gymnasium API，可以与现有的 RL 框架无缝集成。

开发与维护

开发模式安装

git clone https://github.com/openverse-orca/OrcaGym.git
cd OrcaGym
pip install -e ".[dev]"

发布到 PyPI

项目包含完整的发布自动化脚本。查看详细文档：

# 查看快速参考
cat scripts/release/QUICK_REFERENCE.md

# 查看完整文档
cat scripts/release/README.md

快速发布流程：

# 使用 Makefile（推荐）
make bump-version VERSION=25.10.1  # 更新版本号
make release-test                   # 发布到 TestPyPI
make release-prod                   # 发布到 PyPI

# 或使用脚本
./scripts/release/bump_version.sh 25.10.1
./scripts/release/release.sh test
./scripts/release/release.sh prod

详细信息请参阅：

• 📚 发布脚本文档
• ⚡ 快速参考
• 📝 PyPI 发布指南

贡献

我们欢迎对 OrcaGym 项目的贡献。如果您有建议、错误报告或功能请求，请在我们的 GitHub 仓库上开一个 issue 或提交 pull request。

贡献指南

1. Fork 项目
2. 创建特性分支 (git checkout -b feature/AmazingFeature)
3. 提交变更 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 开启 Pull Request

引用

@software{OrcaGym2024,  
  author = {松应科技},  
  title = {OrcaGym: 云原生机器人仿真平台},  
  year = {2024},  
  publisher = {GitHub},  
  journal = {GitHub 仓库},  
  howpublished = {\url{https://github.com/openverse-orca/OrcaGym}}  
}  

许可证

基于 MIT 许可证分发。详情请参见 LICENSE。

联系方式

如有任何疑问或需要支持，请联系我们：[e-mail]

---

我们希望您发现 OrcaGym 是您机器人和强化学习研究的宝贵工具。祝仿真愉快！