Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
139 changes: 139 additions & 0 deletions src/box/BasicWithEndEffectorPosition.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,139 @@
# 从上级包的base模块导入基础模块类(UITB框架的核心基类)
from ...base import BaseModule
# 导入数值计算库,用于数组操作
import numpy as np


class BasicWithEndEffectorPosition(BaseModule):
"""
本体感知模块:整合关节状态、肌肉激活度和末端执行器位置的观测生成器
核心功能:
1. 标准化关节角度、速度、加速度、肌肉激活值
2. 获取末端执行器(如手部、机械爪)的全局位置
3. 拼接所有感知信息,输出一维观测向量(适配强化学习输入)
继承自:BaseModule(UITB框架的基础模块类,提供模拟器交互接口)
"""

def __init__(self, model, data, bm_model, end_effector, **kwargs):
"""
初始化感知模块实例
Args:
model: Mujoco模拟器的模型实例(存储物理模型结构,如关节、刚体、执行器)
data: Mujoco模拟器的数据实例(存储实时物理数据,如关节角度、速度、力)
bm_model: 生物力学模型实例(继承自uitb.bm_models.base.BaseBMModel,提供关节/执行器映射)
end_effector (list of lists): 末端执行器定义,格式示例:
- 单末端执行器:[["site", "right_hand_site"]]
- 多末端执行器:[["body", "left_hand"], ["geom", "right_foot"]]
每个子列表第一个元素是Mujoco元素类型(geom/body/site),第二个是元素名称
**kwargs: 可选参数(如"rng"随机数种子)
"""
# 调用父类初始化方法,传入模拟器实例和生物力学模型
super().__init__(model, data, bm_model,** kwargs)

# 校验末端执行器参数格式:必须是列表类型
if not isinstance(end_effector, list):
raise RuntimeError(
"end_effector必须是长度为2的列表,或嵌套列表(每个子列表长度为2)"
)

# 检查是否为单层列表(如["site", "hand"]),若是则转为嵌套列表(统一格式)
if isinstance(end_effector[0], str):
end_effector = [end_effector]

# 校验所有嵌套子列表的长度必须为2(类型+名称)
if any(len(pair) != 2 for pair in end_effector):
raise RuntimeError("end_effector的每个子列表必须包含2个元素:类型+名称")

# 保存标准化后的末端执行器配置(实例变量,供后续方法调用)
self._end_effector = end_effector

@staticmethod
def insert(task, **kwargs):
"""
静态方法:用于将模块插入到任务配置中(UITB框架预留接口,暂无实现)
Args:
task: 任务实例(包含模拟器、评估指标等)
**kwargs: 扩展参数
"""
pass

@property
def _default_encoder(self):
"""
属性方法:返回默认的编码器配置(适配强化学习的特征编码)
此处配置:单层全连接编码器,输出特征维度为128
Returns:
dict: 编码器的模块路径、类名、参数
"""
return {
"module": "rl.encoders", # 编码器模块路径
"cls": "OneLayer", # 编码器类名(单层全连接)
"kwargs": {"out_features": 128} # 编码器参数:输出特征维度
}

def get_observation(self, model, data, info=None):
"""
核心方法:生成标准化的感知观测向量
Args:
model: Mujoco模型实例(同__init__)
data: Mujoco数据实例(同__init__,存储实时数据)
info: 额外信息字典(可选,如环境状态)
Returns:
np.ndarray: 一维数组,包含所有标准化的感知特征
"""
# -------------------------- 1. 标准化关节角度(qpos) --------------------------
# 获取独立关节的角度范围(model.jnt_range:[min, max])
jnt_range = model.jnt_range[self._bm_model.independent_joints]
# 复制独立关节的当前角度(避免修改原数据)
qpos = data.qpos[self._bm_model.independent_qpos].copy()
# 第一步归一化:将角度映射到[0, 1]区间
qpos = (qpos - jnt_range[:, 0]) / (jnt_range[:, 1] - jnt_range[:, 0])
# 第二步归一化:将角度映射到[-1, 1]区间(适配神经网络输入)
qpos = (qpos - 0.5) * 2

# -------------------------- 2. 获取关节速度/加速度 --------------------------
# 复制独立自由度的关节速度(原始值,未标准化)
qvel = data.qvel[self._bm_model.independent_dofs].copy()
# 复制独立自由度的关节加速度(原始值,未标准化)
qacc = data.qacc[self._bm_model.independent_dofs].copy()

# -------------------------- 3. 获取末端执行器全局位置 --------------------------
ee_position = [] # 存储所有末端执行器的位置
for pair in self._end_effector:
# pair[0]:Mujoco元素类型(geom/body/site),pair[1]:元素名称
# getattr(data, pair[0])(pair[1]):获取对应元素的实例
# .xpos:获取元素的全局坐标(3维:x,y,z)
ee_pos = getattr(data, pair[0])(pair[1]).xpos.copy()
ee_position.append(ee_pos)
# 将多个末端执行器的位置拼接为一维数组(如2个末端执行器则为6维)
ee_position = np.hstack(ee_position)

# -------------------------- 4. 标准化肌肉/执行器激活值 --------------------------
# data.act:所有执行器的当前激活值(范围通常[0,1]),映射到[-1,1]
act = (data.act.copy() - 0.5) * 2
# 生物力学模型中平滑后的电机激活值,同样映射到[-1,1]
motor_act = (self._bm_model.motor_act.copy() - 0.5) * 2

# -------------------------- 5. 拼接所有感知特征 --------------------------
# 本体感知特征:关节角度+速度+加速度+末端位置+执行器激活+电机激活
proprioception = np.concatenate([qpos, qvel, qacc, ee_position, act, motor_act])

# 返回最终的观测向量(一维数组,可直接输入强化学习网络)
return proprioception

def _get_state(self, model, data):
"""
辅助方法:获取末端执行器的详细状态(用于日志/评估,非训练观测)
Args:
model: Mujoco模型实例
data: Mujoco数据实例
Returns:
dict: 键为"元素名称_xpos/xmat",值为对应的位置/旋转矩阵
"""
state = {}
for pair in self._end_effector:
# 存储末端执行器的全局位置(xpos:3维坐标)
state[f"{pair[1]}_xpos"] = getattr(data, pair[0])(pair[1]).xpos.copy()
# 存储末端执行器的旋转矩阵(xmat:9维,描述空间姿态)
state[f"{pair[1]}_xmat"] = getattr(data, pair[0])(pair[1]).xmat.copy()
return state
80 changes: 54 additions & 26 deletions src/box/README.md
Original file line number Diff line number Diff line change
@@ -1,32 +1,47 @@
**box — 仿真与强化学习实验箱**
# box — 仿真与强化学习实验箱

简介
- `src/box` 目录包含基于 Gymnasium 和 MuJoCo 的仿真环境与相关辅助脚本,用于开发和测试生物力学/机器人仿真、感知模块与强化学习任务。
## 概述

目录结构(示例)
- `simulator.py`:仿真环境核心(通常继承 `gym.Env`)。
- `test_simulator.py`:示例运行脚本,用于启动仿真并可视化。
- `main.py`:辅助脚本(例如证书或配置检查)。
- `README.md`:本文件,说明目录用途与快速上手指南。
`src/box` 包含若干用于仿真、感知与强化学习实验的环境与辅助脚本。主要面向基于 Gymnasium/MuJoCo 的任务、轻量级可视化示例以及调试/测试工具。

快速上手
1. 创建并激活虚拟环境(以 Windows 为例):
本目录旨在提供:
- 可复现的仿真实验环境模板;
- 启动/调试脚本示例;
- 与主仓库其余模块交互的接口说明(若存在)。

## 推荐目录结构(示例)

- `simulator.py`:仿真环境实现(通常继承自 `gym.Env` 或 `gymnasium.Env`);
- `envs/`:若干子环境模块或封装;
- `agents/`:示例智能体或策略实现(可选);
- `scripts/`:运行/训练/评估脚本(如 `run.py`, `train.py`, `eval.py`);
- `tests/`:小型示例与单元/集成测试脚本(如 `test_simulator.py`);
- `configs/`:默认配置或参数文件(YAML/JSON);
- `README.md`:本文件。

(实际文件以仓库中为准,此处为常见约定。)

## 快速上手

以下示例以 Windows + PowerShell 为例:

1) 进入项目根目录并创建虚拟环境:

```powershell
cd <项目根目录>
python -m venv venv --python=3.9
.\\venv\\Scripts\\Activate.ps1
cd D:\\nn
python -m venv .venv
.\\.venv\\Scripts\\Activate.ps1
```

2. 安装依赖(建议使用清华镜像加速):
2) 安装依赖:

```powershell
pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple
```

如果仓库没有完整的 `requirements.txt`,可参考下列核心库:
如果仓库未包含完整的 `requirements.txt`,可参考核心依赖:

```text
```
gymnasium
mujoco
stable-baselines3
Expand All @@ -36,21 +51,34 @@ numpy
scipy
matplotlib
ruamel.yaml
certifi
```

运行示例
- 启动仿真:
3) 运行示例仿真(示例脚本名以仓库实际文件为准):

```powershell
python test_simulator.py
python scripts/run.py
```

运行后应弹出可视化窗口(若使用 Pygame/SDL),并在终端输出仿真日志。
或:

```powershell
python tests/test_simulator.py
```

运行后通常会在本地弹出可视化窗口或在终端打印日志,具体行为视环境实现而定。

## 开发与调试提示

- MuJoCo:请确保已正确安装 MuJoCo 及其许可证(若使用 mujoco 依赖)。
- 显示/渲染:在无显示的服务器上运行时,可能需要配置虚拟帧缓冲(Linux 下使用 xvfb)。
- 依赖冲突:若出现版本不兼容,建议使用虚拟环境并锁定依赖版本。

## 如何贡献

- 修改或补充说明、示例脚本或配置后提交 Pull Request;
- 提交 Issue 时请包含:操作系统、Python 版本、依赖版本与复现步骤/错误日志。

贡献与问题反馈
- 若需添加说明或示例,请提交 Pull Request。
- 遇到环境或依赖问题,请在 Issue 中描述操作系统、Python 版本与错误日志。
## 参考与更多信息

更多信息
- 若目录中包含更详细的子模块文档,请参阅相应文件(如 `simulator.py` 顶部注释或同目录下的文档)。
- 查看目录下的具体脚本与模块顶部注释,通常包含使用示例与参数说明;
- 若需要,我可以为 `src/box` 中的主要文件生成更详细的文档或示例运行脚本。
Loading
Loading