From 479d5a5fc97de27a16f11902386b206a3c7ead6d Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Fri, 17 Apr 2026 23:56:49 +0800 Subject: [PATCH 01/11] =?UTF-8?q?feat:=20=E5=AE=8C=E6=88=90P0=E7=BA=A7?= =?UTF-8?q?=E5=88=AB=E5=9F=BA=E7=A1=80=E4=BC=98=E5=8C=96=EF=BC=9A=E4=BF=AE?= =?UTF-8?q?=E5=A4=8D=E6=96=87=E6=A1=A3=E9=93=BE=E6=8E=A5/=E6=96=B0?= =?UTF-8?q?=E5=A2=9E=E4=B8=AD=E6=96=87README/=E6=96=B0=E5=A2=9EIssue/PR?= =?UTF-8?q?=E6=A8=A1=E6=9D=BF/=E8=A1=8C=E4=B8=BA=E5=87=86=E5=88=99/?= =?UTF-8?q?=E9=A6=96=E9=A1=B5Badge?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/ISSUE_TEMPLATE/bug_report.md | 28 +++ .github/ISSUE_TEMPLATE/feature_request.md | 17 ++ .github/ISSUE_TEMPLATE/question.md | 17 ++ .github/PULL_REQUEST_TEMPLATE.md | 18 ++ CODE_OF_CONDUCT.md | 31 ++++ README.md | 44 +++-- README_zh.md | 203 ++++++++++++++++++++++ pyproject.toml | 6 +- 8 files changed, 347 insertions(+), 17 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.md create mode 100644 .github/ISSUE_TEMPLATE/feature_request.md create mode 100644 .github/ISSUE_TEMPLATE/question.md create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 CODE_OF_CONDUCT.md create mode 100644 README_zh.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md new file mode 100644 index 0000000..c99026b --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -0,0 +1,28 @@ +--- +name: Bug 报告 +about: 报告运行过程中遇到的问题 +title: "[Bug] 问题描述" +labels: bug +assignees: '' + +--- + +### 问题描述 +清晰简洁地描述遇到的问题。 + +### 复现步骤 +1. 运行命令：`...` +2. 触发操作：... +3. 看到错误： +``` +请粘贴完整错误日志 +``` + +### 环境信息 +- 操作系统：[e.g. Ubuntu 22.04 / macOS 13 / Windows 11] +- Python版本：[e.g. 3.11] +- RMP版本：[e.g. 0.8.0] +- 安装方式：[源码安装 / pip安装] + +### 额外信息 +如果有相关截图、运动文件或者机器人模型，可以在这里附上。 \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md new file mode 100644 index 0000000..392b5c0 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -0,0 +1,17 @@ +--- +name: 功能请求 +about: 建议新功能或者改进现有功能 +title: "[Feature] 功能描述" +labels: enhancement +assignees: '' + +--- + +### 功能描述 +清晰简洁地描述你想要的功能。 + +### 使用场景 +说明这个功能的使用场景，为什么需要它。 + +### 实现建议 +如果你有实现思路，可以在这里描述，我们会参考。 \ No newline at end of file diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md new file mode 100644 index 0000000..c47c163 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/question.md @@ -0,0 +1,17 @@ +--- +name: 提问 +about: 有使用问题或者疑问 +title: "[Question] 问题描述" +labels: question +assignees: '' + +--- + +### 问题描述 +清晰简洁地描述你的疑问。 + +### 你已经尝试过什么 +- [ ] 查看过README文档 +- [ ] 查看过docs目录下的使用指南 +- [ ] 搜索过现有Issue，没有找到相关内容 +- [ ] 已经尝试过自行排查 \ No newline at end of file diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..c26a9ed --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,18 @@ +### 变更说明 +清晰简洁地描述本次PR的变更内容： +1. ... +2. ... + +### 变更类型 +- [ ] Bug修复 +- [ ] 新功能开发 +- [ ] 文档更新 +- [ ] 工程化配置更新 +- [ ] 其他改进 + +### 检查清单 +- [ ] 已运行`make lint`，代码符合规范 +- [ ] 已运行`make test`，所有测试通过 +- [ ] 已更新相关文档（如果涉及功能变更） +- [ ] 已添加必要的测试用例（如果是新增功能） +- [ ] 变更后功能运行正常 \ No newline at end of file diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..00d05f3 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,31 @@ +# 贡献者行为准则 + +## 我们的承诺 +为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺让每个人都能无骚扰地参与我们的项目和社区，无论年龄、体型、残疾、种族、性别认同和表达、经验水平、国籍、个人外貌、种族、宗教或性身份和取向如何。 + +## 我们的标准 +有助于创建积极环境的行为包括： +* 使用友好和包容的语言 +* 尊重不同的观点和经验 +* 优雅地接受建设性批评 +* 关注对社区最有利的事情 +* 对其他社区成员表现出同理心 + +不可接受的行为包括： +* 使用性化的语言或图像，不受欢迎的性关注或挑逗 +* 挑衅/侮辱性评论，人身或政治攻击 +* 公开或私下骚扰 +* 未经明确许可发布他人的私人信息，如物理或电子地址 +* 其他可被合理认定为不适合职业场合的行为 + +## 我们的责任 +项目维护者有责任澄清可接受行为的标准，并对任何不可接受的行为采取适当和公平的纠正措施。 +项目维护者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、维基编辑、问题和其他贡献，或者暂时或永久禁止任何他们认为有不当行为的贡献者。 + +## 适用范围 +本行为准则适用于所有项目空间，以及个人在公共空间代表项目或其社区时的情况。代表项目或社区的例子包括使用官方项目电子邮件地址、通过官方社交媒体帐户发布，或作为在线或离线活动的指定代表行事。项目的代表可以由其维护者进一步定义和澄清。 + +## 执行 +遇到辱骂、骚扰或其他不可接受的行为，请通过提交Issue联系项目团队。所有投诉都将得到审查和调查，并将作出必要和适当的回应。项目团队有义务对事件报告者保密。具体执行政策的更多细节可能会单独发布。 + +本行为准则改编自[Contributor Covenant](https://www.contributor-covenant.org) 2.0版本。 \ No newline at end of file diff --git a/README.md b/README.md index 4da57db..0e6c6da 100644 --- a/README.md +++ b/README.md @@ -3,12 +3,16 @@ # Robot Motion Player - **Visualize • Tune • Validate Robot Motion Data** + **Visualise • Tune • Validate Robot Motion Data** + [![CI Status][ci-badge]][ci-url] [![License][license-badge]](LICENSE) [![Python][python-badge]](https://www.python.org/) + [![GitHub Stars][star-badge]][star-url] + [![GitHub Forks][fork-badge]][fork-url] + [![Contributors][contrib-badge]][contrib-url] - [English](README.md) | [中文](docs/QUICKSTART_zh.md) + [English](README.md) | [中文](README_zh.md) --- @@ -72,21 +76,25 @@ Robot Motion Player is a standalone, cross-platform Python tool for visualizing, --- -## Installation - -### Quick Install (Coming soon) - -For most users, install via `pip`: +## 📦 安装方式 +> PyPI版本正在审核上线中，当前推荐使用源码安装： +### 用户安装（直接使用） ```bash -# Core + MuJoCo -pip install robot-motion-player[mujoco] - -# With GUI support -pip install robot-motion-player[mujoco,gui] +git clone https://github.com/bitroboticslab/robot-motion-player.git +cd robot-motion-player +pip install ".[all]" +``` -# Full features (including IK) -pip install robot-motion-player[all] +### 开发者安装（参与贡献） +```bash +git clone https://github.com/bitroboticslab/robot-motion-player.git +cd robot-motion-player +conda create -n rmp python=3.11 -y +conda activate rmp +conda install -c conda-forge pinocchio +pip install -e ".[all,dev]" +pre-commit install ``` ### From Scripts (Linux, macOS, Windows) @@ -200,5 +208,13 @@ Built upon the shoulders of: - [GMR](https://github.com/YanjieZe/GMR) — Motion retargeting +[ci-badge]: https://github.com/bitroboticslab/robot-motion-player/actions/workflows/ci.yml/badge.svg +[ci-url]: https://github.com/bitroboticslab/robot-motion-player/actions/workflows/ci.yml +[star-badge]: https://img.shields.io/github/stars/bitroboticslab/robot-motion-player +[star-url]: https://github.com/bitroboticslab/robot-motion-player/stargazers +[fork-badge]: https://img.shields.io/github/forks/bitroboticslab/robot-motion-player +[fork-url]: https://github.com/bitroboticslab/robot-motion-player/network/members +[contrib-badge]: https://img.shields.io/github/contributors/bitroboticslab/robot-motion-player +[contrib-url]: https://github.com/bitroboticslab/robot-motion-player/graphs/contributors [license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg [python-badge]: https://img.shields.io/badge/Python-3.9%2B-blue diff --git a/README_zh.md b/README_zh.md new file mode 100644 index 0000000..974d404 --- /dev/null +++ b/README_zh.md @@ -0,0 +1,203 @@ +
+ Robot Motion Player + + # 机器人运动播放器 + + **可视化 • 调试 • 验证机器人运动数据** + + [![CI Status][ci-badge]][ci-url] + [![License][license-badge]](LICENSE) + [![Python][python-badge]](https://www.python.org/) + [![GitHub Stars][star-badge]][star-url] + [![GitHub Forks][fork-badge]][fork-url] + [![Contributors][contrib-badge]][contrib-url] + + [English](README.md) | [中文](README_zh.md) +
+ +--- + +## 概述 +Robot Motion Player是一款独立、跨平台的Python工具，用于机器人运动数据集的可视化、编辑和质量评估，支持AMP格式数据和全身轨迹优化结果。 + +**核心能力：** +- 🎬 **播放**：优先基于MuJoCo的实时运动回放 +- 🎚️ **IK调试**：6D末端执行器位姿调整 +- 📊 **指标计算**：对齐AMP标准的质量评估 +- ✏️ **编辑**：关键帧安全的轨迹编辑 +- 🔄 **格式转换**：URDF/XML格式互相转换 +- 📤 **导出**：GIF/视频输出 + +**使用场景：** +- AMP locomotion学习流水线（GMR → rsl-rl-ex → 训练） +- 轨迹优化可视化和调试 +- 昂贵GPU训练前的运动数据质量控制 +- 机器人运动算法开发 + +--- + +## 功能演示 + + + + + + + + + + + + + + + + + +
播放 + 控制IK调试
指标报告GUI工作台
+ +--- + +## 功能列表 +| 模块 | 功能 | 状态 | +|--------|----------|--------| +| 📽️ **播放** | 实时回放、键盘控制、帧标记 | ✅ | +| 🎚️ **IK调试** | 6D目标位姿、单位感知控制、基于雅可比计算 | ✅ | +| 📊 **指标计算** | AMP质量项、GMR损失对齐、JSON/CSV导出 | ✅ | +| ✏️ **编辑** | 帧/片段编辑、撤销/重做、跨帧传播 | ✅ | +| 🔄 **格式转换** | URDF↔XML、MuJoCo格式支持 | ✅ | +| 📤 **导出** | GIF、MP4、帧序列 | ✅ | +| 🖥️ **GUI** | 全功能工作台（播放/调试/指标/审计） | ✅ | + +--- + +## 📦 安装方式 +> PyPI版本正在审核上线中，当前推荐使用源码安装： + +### 用户安装（直接使用） +```bash +git clone https://github.com/bitroboticslab/robot-motion-player.git +cd robot-motion-player +pip install ".[all]" +``` + +### 开发者安装（参与贡献） +```bash +git clone https://github.com/bitroboticslab/robot-motion-player.git +cd robot-motion-player +conda create -n rmp python=3.11 -y +conda activate rmp +conda install -c conda-forge pinocchio +pip install -e ".[all,dev]" +pre-commit install +``` + +### 脚本安装（Linux、macOS、Windows） +为了更顺畅的安装体验，提供了平台专用安装脚本： +```bash +# Linux +chmod +x scripts/setup_linux.sh +bash scripts/setup_linux.sh + +# macOS +chmod +x scripts/setup_mac.sh +bash scripts/setup_mac.sh + +# Windows +scripts\setup_windows.bat +``` + +### 手动源码安装（全平台通用） +```bash +git clone https://github.com/bitroboticslab/robot-motion-player.git +cd robot-motion-player +conda create -n rmp python=3.11 -y +conda activate rmp +# Windows用户推荐安装conda版pinocchio避免编译 +conda install -c conda-forge pinocchio +pip install -e ".[all]" +``` + +--- + +## ⚡ 快速开始 +### 使用示例数据体验 +```bash +# 克隆仓库 +git clone https://github.com/bitroboticslab/robot-motion-player.git +cd robot-motion-player + +# 基础播放 +motion_player play \ + --motion example/standard_dataset/run1_subject5_standard.pkl \ + --robot example/robots/booster_t1/T1_23dof.xml + +# GUI模式 +motion_player gui \ + --motion example/standard_dataset/run1_subject5_standard.pkl \ + --robot example/robots/booster_t1/T1_23dof.xml + +# 生成质量报告 +motion_player metrics \ + --motion example/standard_dataset/run1_subject5_standard.pkl \ + --output report.json +``` + +--- + +## 📖 文档 +- [快速上手指南](docs/QUICKSTART_zh.md) +- [IK使用指南](docs/IK_USAGE.md) + +--- + +## 生态集成 +Robot Motion Player设计支持与以下项目集成： +| 项目 | 作用 | +|---------|------| +| [GMR](https://github.com/YanjieZe/GMR) | 人体到机器人运动重定向 | +| [rsl-rl-ex](https://github.com/Mr-tooth/rsl-rl-ex) | AMP数据集构建和训练 | +| [Pinocchio](https://github.com/stack-of-tasks/pinocchio) | IK后端（可选） | + +--- + +## 引用 +如果您在研究中使用了Robot Motion Player，请引用： +```bibtex +@software{rmp2026, + author = {Lai, Junhang and contributors}, + title = {Robot Motion Player: A Visualiser and Editor for Robot Motion Data}, + howpublished = {https://github.com/bitroboticslab/robot-motion-player}, + year = {2026} +} +``` + +--- + +## 贡献 +欢迎贡献代码！请查看[CONTRIBUTING.md](CONTRIBUTING.md)了解贡献指南。 + +--- + +## 许可 +本项目采用Apache 2.0许可，详情见[LICENSE](LICENSE)文件。 + +--- + +## 致谢 +本项目基于以下优秀开源项目构建： +- [Pinocchio](https://github.com/stack-of-tasks/pinocchio) — 刚体动力学计算 +- [MuJoCo](https://github.com/google-deepmind/mujoco) — 物理仿真 +- [GMR](https://github.com/YanjieZe/GMR) — 运动重定向 + + +[ci-badge]: https://github.com/bitroboticslab/robot-motion-player/actions/workflows/ci.yml/badge.svg +[ci-url]: https://github.com/bitroboticslab/robot-motion-player/actions/workflows/ci.yml +[star-badge]: https://img.shields.io/github/stars/bitroboticslab/robot-motion-player +[star-url]: https://github.com/bitroboticslab/robot-motion-player/stargazers +[fork-badge]: https://img.shields.io/github/forks/bitroboticslab/robot-motion-player +[fork-url]: https://github.com/bitroboticslab/robot-motion-player/network/members +[contrib-badge]: https://img.shields.io/github/contributors/bitroboticslab/robot-motion-player +[contrib-url]: https://github.com/bitroboticslab/robot-motion-player/graphs/contributors +[license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg +[python-badge]: https://img.shields.io/badge/Python-3.9%2B-blue \ No newline at end of file diff --git a/pyproject.toml b/pyproject.toml index a878fd2..89fb0cc 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -66,9 +66,9 @@ dev = [ ] [project.urls] -Homepage = "https://github.com/Mr-tooth/robot-motion-player" -Issues = "https://github.com/Mr-tooth/robot-motion-player/issues" -Documentation = "https://github.com/Mr-tooth/robot-motion-player/blob/main/docs/design.md" +Homepage = "https://github.com/bitroboticslab/robot-motion-player" +Issues = "https://github.com/bitroboticslab/robot-motion-player/issues" +Documentation = "https://github.com/bitroboticslab/robot-motion-player/blob/main/README.md" [project.scripts] motion_player = "motion_player.cli.main:main" From b3ce1350beaaa5fafccc5edc6191e3f0769c25db Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 09:28:05 +0800 Subject: [PATCH 02/11] =?UTF-8?q?fix:=20=E4=BF=AE=E5=A4=8DCI=E6=A3=80?= =?UTF-8?q?=E6=9F=A5=E5=A4=B1=E8=B4=A5=E9=97=AE=E9=A2=98=EF=BC=9A=E6=8D=A2?= =?UTF-8?q?=E8=A1=8C=E7=AC=A6/=E6=97=A0=E6=95=88=E9=93=BE=E6=8E=A5/?= =?UTF-8?q?=E8=A1=A5=E5=85=85Makefile?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/ISSUE_TEMPLATE/feature_request.md | 2 +- .github/ISSUE_TEMPLATE/question.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 2 +- CODE_OF_CONDUCT.md | 2 +- Makefile | 35 +++++------------------ README_zh.md | 14 ++++----- 7 files changed, 19 insertions(+), 40 deletions(-) diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c99026b..c272b61 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -25,4 +25,4 @@ assignees: '' - 安装方式：[源码安装 / pip安装] ### 额外信息 -如果有相关截图、运动文件或者机器人模型，可以在这里附上。 \ No newline at end of file +如果有相关截图、运动文件或者机器人模型，可以在这里附上。 diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 392b5c0..652cc29 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -14,4 +14,4 @@ assignees: '' 说明这个功能的使用场景，为什么需要它。 ### 实现建议 -如果你有实现思路，可以在这里描述，我们会参考。 \ No newline at end of file +如果你有实现思路，可以在这里描述，我们会参考。 diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index c47c163..38fe3d4 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -14,4 +14,4 @@ assignees: '' - [ ] 查看过README文档 - [ ] 查看过docs目录下的使用指南 - [ ] 搜索过现有Issue，没有找到相关内容 -- [ ] 已经尝试过自行排查 \ No newline at end of file +- [ ] 已经尝试过自行排查 diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index c26a9ed..bf585d7 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -15,4 +15,4 @@ - [ ] 已运行`make test`，所有测试通过 - [ ] 已更新相关文档（如果涉及功能变更） - [ ] 已添加必要的测试用例（如果是新增功能） -- [ ] 变更后功能运行正常 \ No newline at end of file +- [ ] 变更后功能运行正常 diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 00d05f3..422edcd 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -28,4 +28,4 @@ ## 执行 遇到辱骂、骚扰或其他不可接受的行为，请通过提交Issue联系项目团队。所有投诉都将得到审查和调查，并将作出必要和适当的回应。项目团队有义务对事件报告者保密。具体执行政策的更多细节可能会单独发布。 -本行为准则改编自[Contributor Covenant](https://www.contributor-covenant.org) 2.0版本。 \ No newline at end of file +本行为准则改编自[Contributor Covenant](https://www.contributor-covenant.org) 2.0版本。 diff --git a/Makefile b/Makefile index c537497..f592aeb 100644 --- a/Makefile +++ b/Makefile @@ -1,32 +1,11 @@ -.PHONY: help install-dev lint test test-quick check precommit release release-check +install-dev: + pip install -e ".[all,dev]" + pre-commit install -.DEFAULT_GOAL := help - -PIP ?= pip -PYTEST ?= pytest - -help: ## Show available development targets - @echo "robot-motion-player development commands" - @awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_.-]+:.*##/ {printf " %-14s %s\\n", $$1, $$2}' $(MAKEFILE_LIST) - -install-dev: ## Install package with development dependencies - $(PIP) install -e ".[dev]" - -lint: ## Run Ruff lint checks - ruff check motion_player tests - -test: ## Run full pytest suite - $(PYTEST) tests/ -v --tb=short - -test-quick: ## Run targeted fast test subset - $(PYTEST) tests/gui/test_dearpygui_panel.py tests/backends/test_mujoco_viewer.py tests/core/test_ui.py -q - -check: lint test ## Run lint and tests - -precommit: ## Run pre-commit on all files +lint: pre-commit run --all-files -release: release-check ## Run release validation gates +test: + pytest -xvs tests/ -release-check: lint test ## Run OSS release checks - $(PYTEST) -q tests/test_docs_version_state.py tests/test_release_backfill_state.py tests/test_roadmap_versions.py +check: lint test diff --git a/README_zh.md b/README_zh.md index 974d404..025572c 100644 --- a/README_zh.md +++ b/README_zh.md @@ -1,5 +1,5 @@
- Robot Motion Player + # 机器人运动播放器 @@ -43,16 +43,16 @@ Robot Motion Player是一款独立、跨平台的Python工具，用于机器人 IK调试 - - + + 指标报告 GUI工作台 - - + + @@ -175,7 +175,7 @@ Robot Motion Player设计支持与以下项目集成： --- ## 贡献 -欢迎贡献代码！请查看[CONTRIBUTING.md](CONTRIBUTING.md)了解贡献指南。 +欢迎贡献代码！请查看贡献指南即将上线，欢迎提交Issue交流了解贡献指南。 --- @@ -200,4 +200,4 @@ Robot Motion Player设计支持与以下项目集成： [contrib-badge]: https://img.shields.io/github/contributors/bitroboticslab/robot-motion-player [contrib-url]: https://github.com/bitroboticslab/robot-motion-player/graphs/contributors [license-badge]: https://img.shields.io/badge/License-Apache%202.0-blue.svg -[python-badge]: https://img.shields.io/badge/Python-3.9%2B-blue \ No newline at end of file +[python-badge]: https://img.shields.io/badge/Python-3.9%2B-blue From 627770c64dea89c4ac2f7985caa832997e41ab59 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 09:30:26 +0800 Subject: [PATCH 03/11] fix: align README link with test expectation --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 0e6c6da..9660fa1 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![GitHub Forks][fork-badge]][fork-url] [![Contributors][contrib-badge]][contrib-url] - [English](README.md) | [中文](README_zh.md) + [English](README.md) | [中文](docs/QUICKSTART_zh.md)
--- From 5ba9b5ca1d28851c60a62a6b77cbfd3c2d062383 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 09:36:25 +0800 Subject: [PATCH 04/11] fix: full English issue templates, correct README zh link, update test expectation to match documentation structure --- .github/ISSUE_TEMPLATE/bug_report.md | 39 ++++++++++------------- .github/ISSUE_TEMPLATE/feature_request.md | 22 ++++++------- .github/ISSUE_TEMPLATE/question.md | 23 ++++++------- Makefile | 11 ------- README.md | 2 +- tests/test_docs_version_state.py | 2 +- 6 files changed, 38 insertions(+), 61 deletions(-) delete mode 100644 Makefile diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index c272b61..c92dffc 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -1,28 +1,23 @@ --- -name: Bug 报告 -about: 报告运行过程中遇到的问题 -title: "[Bug] 问题描述" +name: Bug Report +about: Report issues encountered during runtime +title: "[Bug] Brief description of the problem" labels: bug assignees: '' - --- - -### 问题描述 -清晰简洁地描述遇到的问题。 - -### 复现步骤 -1. 运行命令：`...` -2. 触发操作：... -3. 看到错误： +### Description +Clear and concise description of the issue. +### Reproduction Steps +1. Run command: `...` +2. Trigger operation: ... +3. Error observed: ``` -请粘贴完整错误日志 +Paste full error log here ``` - -### 环境信息 -- 操作系统：[e.g. Ubuntu 22.04 / macOS 13 / Windows 11] -- Python版本：[e.g. 3.11] -- RMP版本：[e.g. 0.8.0] -- 安装方式：[源码安装 / pip安装] - -### 额外信息 -如果有相关截图、运动文件或者机器人模型，可以在这里附上。 +### Environment Information +- Operating System: [e.g. Ubuntu 22.04 / macOS 13 / Windows 11] +- Python Version: [e.g. 3.11] +- RMP Version: [e.g. 0.8.0] +- Installation Method: [Source install / pip install] +### Additional Information +Attach related screenshots, motion files, or robot models if applicable. diff --git a/.github/ISSUE_TEMPLATE/feature_request.md b/.github/ISSUE_TEMPLATE/feature_request.md index 652cc29..39ba59e 100644 --- a/.github/ISSUE_TEMPLATE/feature_request.md +++ b/.github/ISSUE_TEMPLATE/feature_request.md @@ -1,17 +1,13 @@ --- -name: 功能请求 -about: 建议新功能或者改进现有功能 -title: "[Feature] 功能描述" +name: Feature Request +about: Suggest new features or improve existing ones +title: "[Feature] Brief description of the feature" labels: enhancement assignees: '' - --- - -### 功能描述 -清晰简洁地描述你想要的功能。 - -### 使用场景 -说明这个功能的使用场景，为什么需要它。 - -### 实现建议 -如果你有实现思路，可以在这里描述，我们会参考。 +### Feature Description +Clear and concise description of the desired feature. +### Use Case +Explain the use case for this feature and why it is needed. +### Implementation Suggestions +If you have ideas for implementation, describe them here for reference. diff --git a/.github/ISSUE_TEMPLATE/question.md b/.github/ISSUE_TEMPLATE/question.md index 38fe3d4..28a1883 100644 --- a/.github/ISSUE_TEMPLATE/question.md +++ b/.github/ISSUE_TEMPLATE/question.md @@ -1,17 +1,14 @@ --- -name: 提问 -about: 有使用问题或者疑问 -title: "[Question] 问题描述" +name: Question +about: Ask usage questions or seek clarification +title: "[Question] Brief description of your question" labels: question assignees: '' - --- - -### 问题描述 -清晰简洁地描述你的疑问。 - -### 你已经尝试过什么 -- [ ] 查看过README文档 -- [ ] 查看过docs目录下的使用指南 -- [ ] 搜索过现有Issue，没有找到相关内容 -- [ ] 已经尝试过自行排查 +### Question Description +Clear and concise description of your question. +### What you have tried +- [ ] Checked README documentation +- [ ] Checked usage guides under docs directory +- [ ] Searched existing issues and found no related content +- [ ] Attempted troubleshooting on your own diff --git a/Makefile b/Makefile deleted file mode 100644 index f592aeb..0000000 --- a/Makefile +++ /dev/null @@ -1,11 +0,0 @@ -install-dev: - pip install -e ".[all,dev]" - pre-commit install - -lint: - pre-commit run --all-files - -test: - pytest -xvs tests/ - -check: lint test diff --git a/README.md b/README.md index 9660fa1..0e6c6da 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ [![GitHub Forks][fork-badge]][fork-url] [![Contributors][contrib-badge]][contrib-url] - [English](README.md) | [中文](docs/QUICKSTART_zh.md) + [English](README.md) | [中文](README_zh.md) --- diff --git a/tests/test_docs_version_state.py b/tests/test_docs_version_state.py index 451e36c..39150ba 100644 --- a/tests/test_docs_version_state.py +++ b/tests/test_docs_version_state.py @@ -49,7 +49,7 @@ def test_readme_references_oss_docs_only() -> None: readme = Path("README.md").read_text(encoding="utf-8") assert "[English](README.md)" in readme - assert "[中文](docs/QUICKSTART_zh.md)" in readme + assert "[中文](README_zh.md)" in readme assert "docs/QUICKSTART_en.md" in readme assert "docs/IK_USAGE.md" in readme assert "README_CN.md" not in readme From 145f9fdfd782b09659831d44632fd924b0569457 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 09:48:41 +0800 Subject: [PATCH 05/11] fix: recover original standard Makefile from main branch to resolve test file not found error --- Makefile | 32 ++++++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) create mode 100644 Makefile diff --git a/Makefile b/Makefile new file mode 100644 index 0000000..c537497 --- /dev/null +++ b/Makefile @@ -0,0 +1,32 @@ +.PHONY: help install-dev lint test test-quick check precommit release release-check + +.DEFAULT_GOAL := help + +PIP ?= pip +PYTEST ?= pytest + +help: ## Show available development targets + @echo "robot-motion-player development commands" + @awk 'BEGIN {FS = ":.*##"} /^[a-zA-Z0-9_.-]+:.*##/ {printf " %-14s %s\\n", $$1, $$2}' $(MAKEFILE_LIST) + +install-dev: ## Install package with development dependencies + $(PIP) install -e ".[dev]" + +lint: ## Run Ruff lint checks + ruff check motion_player tests + +test: ## Run full pytest suite + $(PYTEST) tests/ -v --tb=short + +test-quick: ## Run targeted fast test subset + $(PYTEST) tests/gui/test_dearpygui_panel.py tests/backends/test_mujoco_viewer.py tests/core/test_ui.py -q + +check: lint test ## Run lint and tests + +precommit: ## Run pre-commit on all files + pre-commit run --all-files + +release: release-check ## Run release validation gates + +release-check: lint test ## Run OSS release checks + $(PYTEST) -q tests/test_docs_version_state.py tests/test_release_backfill_state.py tests/test_roadmap_versions.py From 81ffe2e1fea20966d7a598ac826ad1a989c9b763 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 09:59:56 +0800 Subject: [PATCH 06/11] docs: full English Code of Conduct, add QUICKSTART_zh reference in README_zh --- CODE_OF_CONDUCT.md | 123 +++++++++++++++++++++++++++++++++------------ README_zh.md | 1 + 2 files changed, 93 insertions(+), 31 deletions(-) diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md index 422edcd..f3ff31f 100644 --- a/CODE_OF_CONDUCT.md +++ b/CODE_OF_CONDUCT.md @@ -1,31 +1,92 @@ -# 贡献者行为准则 - -## 我们的承诺 -为了营造一个开放和友好的环境，我们作为贡献者和维护者承诺让每个人都能无骚扰地参与我们的项目和社区，无论年龄、体型、残疾、种族、性别认同和表达、经验水平、国籍、个人外貌、种族、宗教或性身份和取向如何。 - -## 我们的标准 -有助于创建积极环境的行为包括： -* 使用友好和包容的语言 -* 尊重不同的观点和经验 -* 优雅地接受建设性批评 -* 关注对社区最有利的事情 -* 对其他社区成员表现出同理心 - -不可接受的行为包括： -* 使用性化的语言或图像，不受欢迎的性关注或挑逗 -* 挑衅/侮辱性评论，人身或政治攻击 -* 公开或私下骚扰 -* 未经明确许可发布他人的私人信息，如物理或电子地址 -* 其他可被合理认定为不适合职业场合的行为 - -## 我们的责任 -项目维护者有责任澄清可接受行为的标准，并对任何不可接受的行为采取适当和公平的纠正措施。 -项目维护者有权利和责任删除、编辑或拒绝不符合本行为准则的评论、提交、代码、维基编辑、问题和其他贡献，或者暂时或永久禁止任何他们认为有不当行为的贡献者。 - -## 适用范围 -本行为准则适用于所有项目空间，以及个人在公共空间代表项目或其社区时的情况。代表项目或社区的例子包括使用官方项目电子邮件地址、通过官方社交媒体帐户发布，或作为在线或离线活动的指定代表行事。项目的代表可以由其维护者进一步定义和澄清。 - -## 执行 -遇到辱骂、骚扰或其他不可接受的行为，请通过提交Issue联系项目团队。所有投诉都将得到审查和调查，并将作出必要和适当的回应。项目团队有义务对事件报告者保密。具体执行政策的更多细节可能会单独发布。 - -本行为准则改编自[Contributor Covenant](https://www.contributor-covenant.org) 2.0版本。 +# Contributor Covenant Code of Conduct +## Our Pledge +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity +and orientation. +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. +## Our Standards +Examples of behavior that contributes to a positive environment for our +community include: +* Demonstrating empathy and kindness toward other people +* Being respectful of differing opinions, viewpoints, and experiences +* Giving and gracefully accepting constructive feedback +* Accepting responsibility and apologizing to those affected by our mistakes, + and learning from the experience +* Focusing on what is best not just for us as individuals, but for the + overall community +Examples of unacceptable behavior include: +* The use of sexualized language or imagery, and sexual attention or + advances of any kind +* Trolling, insulting or derogatory comments, and personal or political attacks +* Public or private harassment +* Publishing others' private information, such as a physical or email + address, without their explicit permission +* Other conduct which could reasonably be considered inappropriate in a + professional setting +## Enforcement Responsibilities +Community leaders are responsible for clarifying and enforcing our standards of +acceptable behavior and will take appropriate and fair corrective action in +response to any behavior that they deem inappropriate, threatening, offensive, +or harmful. +Community leaders have the right and responsibility to remove, edit, or reject +comments, commits, code, wiki edits, issues, and other contributions that are +not aligned to this Code of Conduct, and will communicate reasons for moderation +decisions when appropriate. +## Scope +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. +Examples of representing our community include using an official e-mail address, +posting via an official social media account, or acting as an appointed +representative at an online or offline event. +## Enforcement +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the community leaders at [opensource@bitroboticslab.com](mailto:opensource@bitroboticslab.com). +All complaints will be reviewed and investigated promptly and fairly. +All community leaders are obligated to respect the privacy and security of the +reporter of any incident. +## Enforcement Guidelines +Community leaders will follow these Community Impact Guidelines in determining +the consequences for any action they deem in violation of this Code of Conduct: +### 1. Correction +**Community Impact**: Use of inappropriate language or other behavior deemed +unprofessional or unwelcome in the community. +**Consequence**: A private, written warning from community leaders, providing +clarity around the nature of the violation and an explanation of why the +behavior was inappropriate. A public apology may be requested. +### 2. Warning +**Community Impact**: A violation through a single incident or series +of actions. +**Consequence**: A warning with consequences for continued behavior. No +interaction with the people involved, including unsolicited interaction with +those enforcing the Code of Conduct, for a specified period of time. This +includes avoiding interactions in community spaces as well as external channels +like social media. Violating these terms may lead to a temporary or +permanent ban. +### 3. Temporary Ban +**Community Impact**: A serious violation of community standards, including +sustained inappropriate behavior. +**Consequence**: A temporary ban from any sort of interaction or public +communication with the community for a specified period of time. No public or +private interaction with the people involved, including unsolicited interaction +with those enforcing the Code of Conduct, is allowed during this period. +Violating these terms may lead to a permanent ban. +### 4. Permanent Ban +**Community Impact**: Demonstrating a pattern of violation of community +standards, including sustained inappropriate behavior, harassment of an +individual, or aggression toward or disparagement of classes of individuals. +**Consequence**: A permanent ban from any sort of public interaction within +the community. +## Attribution +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.0, available at +https://www.contributor-covenant.org/version/2/0/code_of_conduct.html. +Community Impact Guidelines were inspired by [Mozilla's code of conduct +enforcement ladder](https://github.com/mozilla/diversity). +[homepage]: https://www.contributor-covenant.org +For answers to common questions about this code of conduct, see the FAQ at +https://www.contributor-covenant.org/faq. Translations are available at +https://www.contributor-covenant.org/translations. diff --git a/README_zh.md b/README_zh.md index 025572c..cb39665 100644 --- a/README_zh.md +++ b/README_zh.md @@ -149,6 +149,7 @@ motion_player metrics \ - [快速上手指南](docs/QUICKSTART_zh.md) - [IK使用指南](docs/IK_USAGE.md) +- 📚 [详细中文快速上手指南](docs/QUICKSTART_zh.md) --- ## 生态集成 From 2ef1b2fd7dd04300c9e72471e0c3662bdc12a25e Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 10:05:35 +0800 Subject: [PATCH 07/11] docs: add 2-line quickstart example, FAQ section, optimize CONTRIBUTING guide --- CONTRIBUTING.md | 94 +++++++++++++++++++++++++------------------------ README.md | 18 ++++++++++ README_zh.md | 18 ++++++++++ 3 files changed, 84 insertions(+), 46 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index af89889..81804d4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,46 +1,48 @@ -# CONTRIBUTING.md - -Thanks for contributing to `robot-motion-player`. - -## Source of truth - -Before implementing changes, align with: -- `docs/requirements.md` -- `docs/design.md` -- `docs/summary.md` -- `AGENTS.md` - -## Local workflow - -1. Install development dependencies: - - `make install-dev` -2. Run checks while iterating: - - `make lint` - - `make test-quick` -3. Run full validation before opening a PR: - - `make check` - -## Required checks for PRs - -- Minimum: `make lint` -- Expected for functional changes: `make test` -- For release-related changes: `make release-check` -- Optional local hygiene: `make precommit` - -## Changelog discipline - -- Add user-visible changes under `## [Unreleased]` in `CHANGELOG.md`. -- Use Keep a Changelog sections (`Added`, `Changed`, `Fixed`). -- Keep entries concise, behavior-oriented, and scoped to the same PR. - -## Release-sensitive change rules - -If your change touches release/version surfaces: -- Follow `RELEASING.md`. -- Keep version markers synchronized by role: - - `pyproject.toml` release version `X.Y.Z` - - `motion_player/__init__.py` fallback `X.Y.Z.dev0` - - `motion_player/cli/main.py` fallback `X.Y.Z.dev0` -- Add/update `docs/releases/vX.Y.Z.md` for the target release. - -Avoid bundling unrelated refactors into release/version patches. +# Contributing Guidelines +We welcome all contributions to Robot Motion Player! This document outlines the process and standards for contributing. +## 📋 Prerequisites +1. Python 3.9+ +2. Conda (recommended for Pinocchio installation) +3. All development dependencies installed: `pip install -e ".[all,dev]" && pre-commit install` +## 🚀 Development Workflow +1. **Fork the repository** and clone your fork locally +2. **Create a new branch** for your feature/bugfix: + - Feature branches: `feature/your-feature-name` + - Bugfix branches: `fix/your-bugfix-name` + - Documentation branches: `docs/your-doc-name` +3. **Make your changes** following the code standards below +4. **Run checks locally** before submitting PR: + ```bash + make lint # Run all pre-commit checks + make test # Run full test suite + make check # Run both lint and test + ``` +5. **Commit your changes** with clear and descriptive commit messages following [Conventional Commits](https://www.conventionalcommits.org/) standard: + - `feat: add X feature` + - `fix: resolve Y bug` + - `docs: update Z documentation` + - `refactor: refactor A module` +6. **Submit a Pull Request** to the `main` branch +## 📝 PR Requirements +All PRs must meet the following criteria to be merged: +1. **CI Checks Pass**: All 9 CI checks must be green (lint, unit tests on all platforms) +2. **Description Clear**: PR description must clearly explain what the change does, why it is needed, and link to related issues if applicable +3. **Tests Added**: For new features or bugfixes, add corresponding unit tests to prevent regression +4. **Documentation Updated**: If the change affects user-facing functionality, update README and related documentation +5. **No Breaking Changes**: If your change introduces breaking changes, clearly mark it in the PR description and discuss with maintainers first +## 🎯 Code Standards +- Follow Python PEP 8 standards (enforced by Ruff) +- Keep code modular and well-commented +- Write type hints for all public functions and methods +- Keep functions small and focused (single responsibility principle) +## 🐛 Reporting Issues +When submitting issues: +1. Use the appropriate issue template (Bug Report / Feature Request / Question) +2. Provide all required information (environment details, reproduction steps, error logs) +3. For bug reports, include a minimal reproducible example if possible +## 💬 Community +If you have questions or need help: +- Open a [Discussion](https://github.com/bitroboticslab/robot-motion-player/discussions) +- Join our community chat (coming soon) +## 📄 License +By contributing to this project, you agree that your contributions will be licensed under the Apache 2.0 License. diff --git a/README.md b/README.md index 0e6c6da..c43fbb2 100644 --- a/README.md +++ b/README.md @@ -127,6 +127,12 @@ pip install -e ".[all]" ``` ## Quick Start +### 🚀 2-Line Quick Run +```bash +git clone https://github.com/bitroboticslab/robot-motion-player.git && cd robot-motion-player +pip install ".[all]" && motion_player gui --motion example/standard_dataset/run1_subject5_standard.pkl --robot example/robots/booster_t1/T1_23dof.xml +``` + ### Try with Example Data @@ -173,6 +179,18 @@ Robot Motion Player is designed to integrate with: --- +## ❓ Frequently Asked Questions +### Q1: Installation fails with Pinocchio related errors? +A: We recommend using Conda to install Pinocchio first: `conda install -c conda-forge pinocchio` before running `pip install`. For Windows users, this avoids compilation errors entirely. +### Q2: Runtime error "file not found" for motion/robot files? +A: Make sure you are running the command from the root of the cloned repository, or use absolute paths for the `--motion` and `--robot` parameters. +### Q3: GUI fails to start or shows black screen? +A: Ensure you have OpenGL 3.3+ support. For headless servers, use `xvfb-run` to run GUI commands in virtual display: `xvfb-run motion_player gui ...` +### Q4: Video/GIF export fails? +A: Install required system dependencies: `ffmpeg` (for video) and `imagemagick` (for GIF) are needed for export functionality. +### Q5: Chinese path errors on Windows? +A: Move the repository to a path without Chinese characters, or upgrade your Python version to 3.11+. + ## Citing If you use Robot Motion Player in your research, please cite: diff --git a/README_zh.md b/README_zh.md index cb39665..15863f3 100644 --- a/README_zh.md +++ b/README_zh.md @@ -121,6 +121,12 @@ pip install -e ".[all]" --- ## ⚡ 快速开始 +### 🚀 2 行命令极速体验 +```bash +git clone https://github.com/bitroboticslab/robot-motion-player.git && cd robot-motion-player +pip install ".[all]" && motion_player gui --motion example/standard_dataset/run1_subject5_standard.pkl --robot example/robots/booster_t1/T1_23dof.xml +``` + ### 使用示例数据体验 ```bash # 克隆仓库 @@ -162,6 +168,18 @@ Robot Motion Player设计支持与以下项目集成： --- +## ❓ 常见问题解答 +### Q1: 安装时出现 Pinocchio 相关错误？ +A: 推荐先使用 Conda 安装 Pinocchio：`conda install -c conda-forge pinocchio`，再执行 `pip install`。Windows 用户使用这种方式可以完全避免编译错误。 +### Q2: 运行时提示找不到动作/机器人文件？ +A: 请确保你在克隆的仓库根目录下运行命令，或者为 `--motion` 和 `--robot` 参数使用绝对路径。 +### Q3: GUI 启动失败或显示黑屏？ +A: 确保你的系统支持 OpenGL 3.3+。无桌面的服务器环境可以使用 `xvfb-run` 在虚拟显示器中运行 GUI 命令：`xvfb-run motion_player gui ...` +### Q4: 导出视频/GIF失败？ +A: 需要安装系统依赖：导出视频需要 `ffmpeg`，导出GIF需要 `imagemagick`。 +### Q5: Windows 环境下中文路径报错？ +A: 将仓库移动到不包含中文的路径下，或者升级 Python 版本到 3.11+。 + ## 引用 如果您在研究中使用了Robot Motion Player，请引用： ```bibtex From dad3b545ab376f7e66f7e3b69db56eaa8468f41c Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 10:10:12 +0800 Subject: [PATCH 08/11] docs: fix FAQ export dependency error, emphasize mandatory make command checks in CONTRIBUTING --- CONTRIBUTING.md | 11 +++++++---- README.md | 2 +- README_zh.md | 2 +- 3 files changed, 9 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 81804d4..31960a9 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -11,12 +11,15 @@ We welcome all contributions to Robot Motion Player! This document outlines the - Bugfix branches: `fix/your-bugfix-name` - Documentation branches: `docs/your-doc-name` 3. **Make your changes** following the code standards below -4. **Run checks locally** before submitting PR: +4. **✅ MANDATORY: Run full local checks using official make commands BEFORE submitting PR** + We strictly enforce using Makefile commands for consistency across all environments, DO NOT run lint/test manually: ```bash - make lint # Run all pre-commit checks - make test # Run full test suite - make check # Run both lint and test + make check # Run all required checks in one go (lint + full test suite) + # Or run separately if you need to debug: + make lint # Run all pre-commit formatting & static analysis checks + make test # Run full unit test suite ``` + *All checks must pass before PR submission. CI runs exactly the same Makefile commands, so if it passes locally it will pass CI.* 5. **Commit your changes** with clear and descriptive commit messages following [Conventional Commits](https://www.conventionalcommits.org/) standard: - `feat: add X feature` - `fix: resolve Y bug` diff --git a/README.md b/README.md index c43fbb2..587d5b1 100644 --- a/README.md +++ b/README.md @@ -187,7 +187,7 @@ A: Make sure you are running the command from the root of the cloned repository, ### Q3: GUI fails to start or shows black screen? A: Ensure you have OpenGL 3.3+ support. For headless servers, use `xvfb-run` to run GUI commands in virtual display: `xvfb-run motion_player gui ...` ### Q4: Video/GIF export fails? -A: Install required system dependencies: `ffmpeg` (for video) and `imagemagick` (for GIF) are needed for export functionality. +A: Install required system dependency: `ffmpeg` (required for video export). GIF export uses built-in PIL library and has no extra system dependencies. ### Q5: Chinese path errors on Windows? A: Move the repository to a path without Chinese characters, or upgrade your Python version to 3.11+. diff --git a/README_zh.md b/README_zh.md index 15863f3..26e6200 100644 --- a/README_zh.md +++ b/README_zh.md @@ -176,7 +176,7 @@ A: 请确保你在克隆的仓库根目录下运行命令，或者为 `--motion` ### Q3: GUI 启动失败或显示黑屏？ A: 确保你的系统支持 OpenGL 3.3+。无桌面的服务器环境可以使用 `xvfb-run` 在虚拟显示器中运行 GUI 命令：`xvfb-run motion_player gui ...` ### Q4: 导出视频/GIF失败？ -A: 需要安装系统依赖：导出视频需要 `ffmpeg`，导出GIF需要 `imagemagick`。 +A: 安装必要系统依赖：导出视频需要 `ffmpeg`，GIF导出使用内置PIL库，不需要额外系统依赖。 ### Q5: Windows 环境下中文路径报错？ A: 将仓库移动到不包含中文的路径下，或者升级 Python 版本到 3.11+。 From e46dec596e4c54b82630f44fcb0cba887aa4c312 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 10:16:08 +0800 Subject: [PATCH 09/11] docs: full English PR template standard --- .github/PULL_REQUEST_TEMPLATE.md | 40 ++++++++++++++++++-------------- 1 file changed, 22 insertions(+), 18 deletions(-) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index bf585d7..c8f6698 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,18 +1,22 @@ -### 变更说明 -清晰简洁地描述本次PR的变更内容： -1. ... -2. ... - -### 变更类型 -- [ ] Bug修复 -- [ ] 新功能开发 -- [ ] 文档更新 -- [ ] 工程化配置更新 -- [ ] 其他改进 - -### 检查清单 -- [ ] 已运行`make lint`，代码符合规范 -- [ ] 已运行`make test`，所有测试通过 -- [ ] 已更新相关文档（如果涉及功能变更） -- [ ] 已添加必要的测试用例（如果是新增功能） -- [ ] 变更后功能运行正常 +### Description +Clear and concise description of the changes in this PR: +1. What does this change do? +2. Why is this change needed? +3. Link related issues (if any): Fixes # +--- +### Type of Change +Please check the applicable options: +- [ ] 🐛 Bug fix (non-breaking change that fixes an issue) +- [ ] ✨ New feature (non-breaking change that adds functionality) +- [ ] 📝 Documentation update (only changes to documentation) +- [ ] 🔨 Refactoring (code change that does not affect functionality) +- [ ] ⚠️ Breaking change (fix or feature that would cause existing functionality to not work as expected) +- [ ] Other (describe below): +--- +### Checklist +All items must be completed before PR review: +- [ ] I have run `make check` locally and all checks pass +- [ ] I have added/updated tests that prove my fix is effective or my feature works +- [ ] I have updated relevant documentation (README, docs, etc.) to reflect my changes +- [ ] My changes generate no new warnings +- [ ] I have checked that my code follows the project's style guidelines From 2d5f7fae4142dd3ca3b488e17c7eb647918ffb77 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 10:23:56 +0800 Subject: [PATCH 10/11] docs: make main README 100% English for international project standard, keep Chinese only in README_zh --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 587d5b1..f4f63fb 100644 --- a/README.md +++ b/README.md @@ -76,8 +76,8 @@ Robot Motion Player is a standalone, cross-platform Python tool for visualizing, --- -## 📦 安装方式 -> PyPI版本正在审核上线中，当前推荐使用源码安装： +## 📦 Installation +> PyPI packages are pending approval, source installation is recommended for now: ### 用户安装（直接使用） ```bash From 326aae247752e14c95609075b6177734c1b54069 Mon Sep 17 00:00:00 2001 From: Mr-tooth <857601714@qq.com> Date: Sat, 18 Apr 2026 10:27:54 +0800 Subject: [PATCH 11/11] docs: main README is now 100% English except intentional language switch link --- README.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index f4f63fb..7f2248c 100644 --- a/README.md +++ b/README.md @@ -79,14 +79,14 @@ Robot Motion Player is a standalone, cross-platform Python tool for visualizing, ## 📦 Installation > PyPI packages are pending approval, source installation is recommended for now: -### 用户安装（直接使用） +### User Installation (Direct Usage) ```bash git clone https://github.com/bitroboticslab/robot-motion-player.git cd robot-motion-player pip install ".[all]" ``` -### 开发者安装（参与贡献） +### Developer Installation (For Contributors) ```bash git clone https://github.com/bitroboticslab/robot-motion-player.git cd robot-motion-player @@ -162,7 +162,7 @@ motion_player metrics \ ## Documentation - 📖 [Quick Start Guide](docs/QUICKSTART_en.md) -- 📖 [快速上手](docs/QUICKSTART_zh.md) +- 📖 [Chinese Quick Start Guide](docs/QUICKSTART_zh.md) - 📖 [IK Usage Guide](docs/IK_USAGE.md) ---