Metadata-Version: 2.4
Name: orca-gym
Version: 26.5.1
Summary: OrcaGym Core - Cloud-native robotics simulation platform compatible with Gymnasium API
Author-email: 松应科技 <huangwei@orca3d.cn>
License: MIT
Project-URL: Homepage, https://github.com/openverse-orca/OrcaGym
Project-URL: Documentation, https://github.com/openverse-orca/OrcaGym
Project-URL: Repository, https://github.com/openverse-orca/OrcaGym
Project-URL: Bug Tracker, https://github.com/openverse-orca/OrcaGym/issues
Keywords: robotics,simulation,reinforcement-learning,gymnasium,mujoco
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Requires-Dist: numpy==2.2.6
Requires-Dist: scipy==1.16.2
Requires-Dist: scipy-stubs==1.16.2.4
Requires-Dist: grpcio==1.66.1
Requires-Dist: grpcio-tools==1.66.1
Requires-Dist: gymnasium==1.2.1
Requires-Dist: mujoco==3.7.0
Requires-Dist: aiofiles==25.1.0
Requires-Dist: termcolor>=2.4.0
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Requires-Dist: flake8; extra == "dev"
Requires-Dist: black; extra == "dev"
Requires-Dist: mypy; extra == "dev"
Provides-Extra: rl
Requires-Dist: stable-baselines3>=2.3.2; extra == "rl"
Requires-Dist: sb3_contrib>=2.3.0; extra == "rl"
Requires-Dist: tensorboard; extra == "rl"
Provides-Extra: imitation
Requires-Dist: h5py; extra == "imitation"
Requires-Dist: opencv-python; extra == "imitation"
Requires-Dist: tqdm; extra == "imitation"
Provides-Extra: devices
Requires-Dist: pygame>=2.6.0; extra == "devices"
Provides-Extra: sensors
Requires-Dist: websockets; extra == "sensors"
Requires-Dist: av; extra == "sensors"
Requires-Dist: opencv-python; extra == "sensors"
Requires-Dist: matplotlib; extra == "sensors"
Provides-Extra: tools
Requires-Dist: pyyaml; extra == "tools"
Requires-Dist: trimesh; extra == "tools"
Requires-Dist: requests; extra == "tools"
Requires-Dist: tqdm; extra == "tools"
Provides-Extra: robomimic
Requires-Dist: h5py; extra == "robomimic"
Requires-Dist: termcolor; extra == "robomimic"
Requires-Dist: opencv-python; extra == "robomimic"
Provides-Extra: robosuite
Requires-Dist: numba; extra == "robosuite"
Provides-Extra: all
Requires-Dist: stable-baselines3>=2.3.2; extra == "all"
Requires-Dist: sb3_contrib>=2.3.0; extra == "all"
Requires-Dist: tensorboard; extra == "all"
Requires-Dist: h5py; extra == "all"
Requires-Dist: opencv-python; extra == "all"
Requires-Dist: tqdm; extra == "all"
Requires-Dist: pygame>=2.6.0; extra == "all"
Requires-Dist: websockets; extra == "all"
Requires-Dist: av; extra == "all"
Requires-Dist: matplotlib; extra == "all"
Requires-Dist: pyyaml; extra == "all"
Requires-Dist: trimesh; extra == "all"
Requires-Dist: requests; extra == "all"
Requires-Dist: termcolor; extra == "all"
Requires-Dist: numba; extra == "all"
Requires-Dist: flask; extra == "all"

# OrcaGym

[![PyPI version](https://img.shields.io/pypi/v/orca-gym)](https://pypi.org/project/orca-gym/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)

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

> **样例与数据采集已迁移**  
> 原仓库中的遥操作、数据采集与相关示例已独立至 **[OrcaManipulation](https://github.com/openverse-orca/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 安装（推荐）

```bash
# 安装核心包
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]         # 所有可选依赖
```

### 从源码安装（开发者）

```bash
# 克隆仓库
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](https://github.com/openverse-orca/OrcaManipulation.git)**，跟随其 `README.md` / `QUICK_START.md` 安装与运行。
- **本包可选依赖**（算法与工具链，按需安装）：
  - `pip install orca-gym[rl]` — 强化学习常见依赖（如 SB3）
  - `pip install orca-gym[imitation]` — 模仿学习相关
  - `pip install orca-gym[devices]` — 输入设备支持


## OrcaStudio、OrcaLab 配置

从[官方门户](http://orca3d.cn/)下载并安装 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` 地址上运行

**命令示例**：
```bash
# 安装 orca-gym 后，直接运行
orcagym-loop
```

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

## 核心包说明

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

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

**不包含（已迁移）**：
- 训练 / 遥操作 / 数据采集等**应用示例与配套环境** → 见 **[OrcaManipulation](https://github.com/openverse-orca/OrcaManipulation)**（[克隆地址](https://github.com/openverse-orca/OrcaManipulation.git)）

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

## 使用示例

完整可运行示例（含数据采集、VR 遥控、数据增强等）已迁移至 **[OrcaManipulation](https://github.com/openverse-orca/OrcaManipulation)**：

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

欢迎体验：[OrcaManipulation 主页](https://github.com/openverse-orca/OrcaManipulation) · [Git 克隆地址](https://github.com/openverse-orca/OrcaManipulation.git)

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

## 性能与配置考虑

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

## 开发与维护

### 开发模式安装

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

### 发布到 PyPI

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

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

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

**快速发布流程**：

```bash
# 使用 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
```

详细信息请参阅：
- 📚 [发布脚本文档](scripts/release/README.md)
- ⚡ [快速参考](scripts/release/QUICK_REFERENCE.md)
- 📝 [PyPI 发布指南](PYPI_RELEASE.md)

## 贡献

我们欢迎对 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

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

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

## 联系方式
如有任何疑问或需要支持，请联系我们：huangwei@orca3d.cn

---

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