diff --git a/src/Embodied_Human_Arm_Modeling/README.md b/src/Embodied_Human_Arm_Modeling/README.md index 1c875b1653..92d89c64b8 100644 --- a/src/Embodied_Human_Arm_Modeling/README.md +++ b/src/Embodied_Human_Arm_Modeling/README.md @@ -1,96 +1,245 @@ -Shadow Hand 手部动画演示 -项目概述 -这是一个基于 MuJoCo 物理引擎的 Shadow Hand 手部模型动画演示程序。该脚本加载 Shadow Hand 的 MJCF 模型文件,并通过简单的控制指令循环展示三种不同的手部姿态。 - -功能特性 -模型加载:加载 Shadow Hand 的 MJCF 模型文件(left_hand.xml) - -姿态控制:预定义了三种手部姿态: - -张开手:所有关节设置为零位置 - -握拳:模拟握拳动作的关节角度 - -捏取:模拟捏取物体的手部姿态 - -实时动画:每3秒自动切换一种姿态 - -可视化界面:使用 MuJoCo 的被动查看器实时显示手部动作 +Shadow Hand 手部动画演示项目 +📋 项目概述 +本项目基于 Shadow Robot Company 开源的 Shadow Hand E3M5 左手模型(Apache 2.0 License),使用 MuJoCo 物理引擎开发了一个交互式的手部动画演示系统。该系统可以展示多种预设手部姿态,并支持用户通过命令行进行实时控制。 +🚀 快速开始 系统要求 Python 3.8+ -MuJoCo 2.3.0+ +MuJoCo 3.x NumPy -安装与运行 -1. 安装依赖 +安装依赖 bash pip install mujoco numpy -2. 准备模型文件 -确保 left_hand.xml 模型文件与脚本在同一目录下,或修改脚本中的路径指向正确的模型文件。 - -3. 运行程序 +运行演示 bash -python simple_hand_animation.py +python interactive_hand_simulator.py +确保 left_hand.xml 模型文件和 assets/ 目录(包含 OBJ 网格文件)与脚本在同一目录下。 + +🎮 功能特性 +1. 预设手部姿态库 +系统包含 6 种精心设计的手部姿态: + +张开手 🤚 - 所有手指完全展开 -动画循环: +握拳 ✊ - 所有手指完全握紧 -每3秒切换一个预定义姿态 +圆柱体抓握 🫱 - 环绕抓握柱状物体 -实时更新控制指令并同步查看器 +剪刀手 ✌️ - 食指和中指张开呈V形 -使用方法 -运行程序后,MuJoCo 查看器将自动打开 +OK手势 👌 - 拇指和食指形成圆圈 -手部模型将循环展示三种姿态: +指点 👉 - 食指伸直,其他手指握起 -张开手 → 等待3秒 → 握拳 → 等[hand_animation_controller.py](../../../mujoco_menagerie/shadow_hand/hand_animation_controller.py)待3秒 → 捏取 → 等待3秒 → 重复 +2. 交互控制模式 +支持两种控制模式: -按 Ctrl+C 可中断程序并关闭查看器 +自动模式 🤖 - 自动循环播放所有姿态(每姿态保持5秒) -输出信息[hand_animation_controller.py](../../../mujoco_menagerie/shadow_hand/hand_animation_controller.py) -程序运行时会输出以下信息: +手动模式 🎮 - 用户通过命令行控制姿态切换 -✅ 模型加载成功 +3. 动画系统 +平滑过渡动画(1.5秒过渡时间) -📊 关节数: [关节数量] +缓动函数实现自然的运动曲线 -📊 执行器数: [执行器数量] +实时姿态进度显示 -🎭 切换到: [当前姿态名称] +4. 控制命令 +在程序运行期间,可在终端中输入以下命令: -文件结构 +text +pause: 暂停/继续演示 +next: 切换到下一个姿态 +prev: 切换到上一个姿态 +mode: 切换手动/自动模式 +restart:重新开始演示 +help: 显示控制说明 +quit: 退出演示 +📁 文件说明 +核心文件 text . -├── simple_hand_animation.py # 主程序文件 -├── left_hand.xml # Shadow Hand MJCF 模型文件 -└── README.md # 说明文档 -注意事项 -确保 MuJoCo 许可证正确配置 +├── left_hand.xml # Shadow Hand 左手MJCF模型文件 +├── interactive_hand_simulator.py # 主程序 - 交互式手部演示 +└── assets/ # 模型网格文件目录(包含所有.obj文件) +模型结构说明 +left_hand.xml 文件定义了完整的 Shadow Hand 左手模型: + +主要组件: +前臂(lh_forearm) - 包含惯性参数和碰撞几何体 + +手腕(lh_wrist) - 包含两个旋转关节(WRJ1, WRJ2) + +手掌(lh_palm) - 手部基础结构 + +五个手指 - 分别对应索引、中指、无名指、小指和拇指 + +关节配置: +手腕关节:2个自由度(俯仰和横滚) + +拇指关节:5个自由度(THJ1-THJ5) + +其他手指:每个3-4个自由度(包括肌腱耦合) + +执行器系统: +20个位置控制执行器 + +包含肌腱耦合(例如FFJ0同时控制FFJ2和FFJ1) + +💻 代码架构 +HandDemoMujoco3 类 +主程序类,包含以下主要方法: + +初始化方法: +python +__init__(model_path='left_hand.xml') # 加载模型并初始化状态 +姿态创建方法: +python +_create_preset_poses() # 创建6种预设手部姿态 +_create_pose_fist() # 创建握拳姿态 +_create_pose_cylinder() # 创建圆柱体抓握姿态 +_create_pose_scissors() # 创建剪刀手姿态 +_create_pose_ok() # 创建OK手势 +_create_pose_pointing() # 创建指点姿态 +动画控制方法: +python +start_animation(pose_name) # 开始动画到指定姿态 +update_animation() # 更新动画状态 +toggle_pause() # 切换暂停状态 +next_pose() # 切换到下一个姿态 +previous_pose() # 切换到上一个姿态 +toggle_manual_mode() # 切换手动/自动模式 +用户交互方法: +python +process_command(command) # 处理控制台命令 +print_controls() # 打印控制说明 +run_demo() # 运行主演示循环 +多线程设计 +主线程:处理物理仿真和图形渲染 + +输入线程:监听用户命令行输入 + +线程安全:使用锁保护共享状态变量 + +🔧 技术实现细节 +动画插值系统 +python +# 使用缓动函数(ease in-out)实现平滑过渡 +if t < 0.5: + t_eased = 2 * t * t +else: + t_eased = -1 + (4 - 2 * t) * t + +# 线性插值计算 +current_values = start_values + (target_values - start_values) * t_eased +姿态数据适配 +代码根据实际执行器数量自动调整姿态参数: + +支持完整20执行器配置 + +支持简化配置(最少3个执行器) + +容错性设计,避免索引错误 + +📊 运行输出示例 +text +============================================================ +✅ 手部模型加载成功 +📊 执行器数量: 20 +📊 关节数量: 24 +📊 仿真时间步: 0.0020秒 +============================================================ +🎭 创建了 6 种预设姿态 +============================================================ + +🤖 手部抓握姿态全自动演示 (MuJoCo 3.x 兼容版) +============================================================ +🎬 演示序列: 7 个姿态 +⏱️ 每个姿态保持: 5.0秒 +🎥 动画过渡: 1.5秒 + +🎮 控制说明 (在终端中输入命令): + pause: 暂停/继续演示 + next: 下一个姿态 + prev: 上一个姿态 + mode: 切换手动/自动模式 + restart: 重新开始演示 + help: 显示控制说明 + quit: 退出演示 +============================================================ + +演示开始... + +🤚 [张开手 ] 进度: 0.0% - 所有手指完全展开 +🛠️ 故障排除 +常见问题 +找不到模型文件 + +text +❌ 找不到模型文件 'left_hand.xml' +确保 left_hand.xml 和 assets/ 目录与脚本在同一目录下。 + +缺少网格文件 + +text +MuJoCo错误: 无法加载网格文件 +检查 assets/ 目录是否包含所有引用的 .obj 文件。 + +MuJoCo版本不兼容 +确保安装的是 MuJoCo 3.x 版本。 + +📝 扩展开发 +添加新姿态 +要添加新的手部姿态,可在 _create_preset_poses() 方法中添加: + +python +self.poses['新手势'] = { + 'values': self._create_custom_pose(), + 'emoji': '🎯', + 'description': '手势描述' +} +修改动画参数 +可以调整以下参数: + +self.animation_duration - 动画过渡时间 + +hold_duration - 姿态保持时间 + +self.model.opt.timestep - 仿真时间步长 + +📄 许可证说明 +模型文件 +来源:Shadow Robot Company + +许可证:Apache 2.0 License + +原始仓库:https://github.com/shadow-robot/sr_common -模型文件需与脚本在同一目录或指定正确路径 +动画脚本 +作者:项目开发者 -姿态控制值基于原始模型配置,可能需要根据具体模型调整 +用途:学术演示和教育用途 -扩展设想 -基于当前代码,未来可以: +依赖:MuJoCo, NumPy -增加更多预定义手部姿态 +🙏 致谢 +Shadow Robot Company - 提供高质量的开源手部模型 -添加手动控制模式(键盘或GUI) +DeepMind - 开发 MuJoCo 物理引擎 -实现姿态间的平滑过渡动画 +MuJoCo 社区 - 提供技术支持和文档 -记录和回放手部动作序列 +📧 反馈与贡献 +如发现任何问题或有改进建议,请: -添加物理交互对象(如抓取小球) +检查代码注释和错误信息 -致谢 -Shadow Robot Company 提供开源手部模型 +参考 MuJoCo 官方文档 -DeepMind 开发 MuJoCo 物理引擎 +在课程作业仓库中提交问题报告 -许可证 -遵循原始模型的 Apache 2.0 许可证。 \ No newline at end of file +注意:本项目为学术用途,遵循 Apache 2.0 开源许可证。模型版权归 Shadow Robot Company 所有,动画代码为课程作业原创实现。 \ No newline at end of file