add chinese
build / setup (compute matrix) (push) Has been cancelled
build / ${{ matrix.label }} (push) Has been cancelled
build / macos-15-arm64-studio (push) Has been cancelled
build / ubuntu-24.04-clang-18-studio (push) Has been cancelled
build / ubuntu-24.04-gcc-14-studio (push) Has been cancelled
build / windows-2025-ninja-studio (push) Has been cancelled
build / ubuntu-24.04-clang-18-wasm (push) Has been cancelled
build / ubuntu-24.04-clang-18-mjx (push) Has been cancelled
build / setup (compute matrix) (push) Has been cancelled
build / ${{ matrix.label }} (push) Has been cancelled
build / macos-15-arm64-studio (push) Has been cancelled
build / ubuntu-24.04-clang-18-studio (push) Has been cancelled
build / ubuntu-24.04-gcc-14-studio (push) Has been cancelled
build / windows-2025-ninja-studio (push) Has been cancelled
build / ubuntu-24.04-clang-18-wasm (push) Has been cancelled
build / ubuntu-24.04-clang-18-mjx (push) Has been cancelled
This commit is contained in:
@@ -42,3 +42,4 @@ MUJOCO_LOG.TXT
|
||||
wasm/**/dist/
|
||||
**/node_modules/
|
||||
|
||||
.venv/
|
||||
|
||||
@@ -14,156 +14,112 @@
|
||||
</a>
|
||||
</p>
|
||||
|
||||
**MuJoCo** stands for **Mu**lti-**Jo**int dynamics with **Co**ntact. It is a
|
||||
general purpose physics engine that aims to facilitate research and development
|
||||
in robotics, biomechanics, graphics and animation, machine learning, and other
|
||||
areas which demand fast and accurate simulation of articulated structures
|
||||
interacting with their environment.
|
||||
**MuJoCo** 是 **Mu**lti-**Jo**int dynamics with **Co**ntact（带接触的多关节动力学）的缩写。它是一款通用物理引擎，旨在促进机器人学、生物力学、图形与动画、机器学习以及其他需要对与环境交互的多关节结构进行快速且精确仿真的领域的研究与开发。
|
||||
|
||||
This repository is maintained by [Google DeepMind](https://www.deepmind.com/).
|
||||
本项目由 [Google DeepMind](https://www.deepmind.com/) 维护。
|
||||
|
||||
MuJoCo has a C API and is intended for researchers and developers. The runtime
|
||||
simulation module is tuned to maximize performance and operates on low-level
|
||||
data structures that are preallocated by the built-in XML compiler. The library
|
||||
includes interactive visualization with a native GUI, rendered in OpenGL. MuJoCo
|
||||
further exposes a large number of utility functions for computing
|
||||
physics-related quantities.
|
||||
MuJoCo 提供 C API，面向研究人员和开发者。其实时仿真模块经过专门调优以实现极致性能，并运行在由内置 XML 编译器预先分配的底层数据结构之上。该库包含使用 OpenGL 渲染的原生 GUI 交互式可视化工具。MuJoCo 还提供了大量用于计算物理相关物理量的实用函数。
|
||||
|
||||
We also provide [Python bindings] and a plug-in for the [Unity] game engine.
|
||||
我们还提供了 [Python 绑定][Python bindings] 以及用于 [Unity] 游戏引擎的插件。
|
||||
|
||||
## Documentation
|
||||
## 文档
|
||||
|
||||
MuJoCo's documentation can be found at [mujoco.readthedocs.io]. Upcoming
|
||||
features due for the next release can be found in the [changelog] in the
|
||||
"latest" branch.
|
||||
MuJoCo 的文档可在 [mujoco.readthedocs.io] 查阅。下一个版本即将推出的新特性可以在 “latest” 分支的[更新日志][changelog]中找到。
|
||||
|
||||
## Getting Started
|
||||
## 快速入门
|
||||
|
||||
There are two easy ways to get started with MuJoCo:
|
||||
快速上手 MuJoCo 有两种简便途径：
|
||||
|
||||
1. **Run `simulate` on your machine.**
|
||||
[This video](https://www.youtube.com/watch?v=P83tKA1iz2Y) shows a screen capture
|
||||
of `simulate`, MuJoCo's native interactive viewer. Follow the steps described in
|
||||
the [Getting Started] section of the documentation to get `simulate` running on
|
||||
your machine.
|
||||
1. **在本地运行 `simulate`。**
|
||||
[此视频](https://www.youtube.com/watch?v=P83tKA1iz2Y)展示了 MuJoCo 原生交互式查看器 `simulate` 的录屏。请按照文档中的[快速入门][Getting Started]部分描述的步骤在您的机器上运行 `simulate`。
|
||||
|
||||
2. **Explore our online IPython notebooks.**
|
||||
If you are a Python user, you might want to start with our tutorial notebooks
|
||||
running on Google Colab:
|
||||
2. **探索在线 IPython Notebook 教程。**
|
||||
如果您是 Python 用户，建议从运行在 Google Colab 上的教程 Notebook 开始：
|
||||
|
||||
- The **introductory** tutorial teaches MuJoCo basics:
|
||||
- **入门**教程讲解 MuJoCo 基础知识：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/tutorial.ipynb)
|
||||
- The **Model Editing** tutorial shows how to create and edit models procedurally:
|
||||
- **模型编辑**教程演示如何通过代码程序化创建和编辑模型：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/mjspec.ipynb)
|
||||
- The **rollout** tutorial shows how to use the multithreaded `rollout` module:
|
||||
- **rollout** 教程介绍如何使用多线程 `rollout` 模块：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/rollout.ipynb)
|
||||
- The **LQR** tutorial synthesizes a linear-quadratic controller, balancing a
|
||||
humanoid on one leg:
|
||||
- **LQR** 教程演示如何合成线性二次型控制器（LQR），实现人形机器人单腿平衡：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/LQR.ipynb)
|
||||
- The **least-squares** tutorial explains how to use the Python-based nonlinear
|
||||
least-squares solver:
|
||||
- **最小二乘法**教程解释如何使用基于 Python 的非线性最小二乘求解器：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/least_squares.ipynb)
|
||||
- The **MJX** tutorial provides usage examples of
|
||||
[MuJoCo XLA](https://mujoco.readthedocs.io/en/stable/mjx.html), a branch of MuJoCo written in JAX:
|
||||
- **MJX** 教程提供了 [MuJoCo XLA](https://mujoco.readthedocs.io/en/stable/mjx.html) 的使用示例，它是用 JAX 编写的 MuJoCo 分支版本：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/tutorial.ipynb)
|
||||
- The **differentiable physics** tutorial trains locomotion policies with
|
||||
analytical gradients automatically derived from MuJoCo's physics step:
|
||||
- **可微物理**教程展示如何利用从 MuJoCo 物理计算步中自动推导出的解析梯度来训练运动控制策略：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/training_apg.ipynb)
|
||||
|
||||
## Installation
|
||||
## 安装
|
||||
|
||||
### Prebuilt binaries
|
||||
### 预编译二进制文件
|
||||
|
||||
Versioned releases are available as precompiled binaries from the GitHub
|
||||
[releases page], built for Linux (x86-64 and AArch64), Windows (x86-64 only),
|
||||
and macOS (universal). This is the recommended way to use the software.
|
||||
带有版本号的正式发行版预编译二进制文件可在 GitHub [发布页面][releases page] 获取，支持 Linux（x86-64 和 AArch64）、Windows（仅限 x86-64）和 macOS（通用架构）。这是使用本软件的推荐方式。
|
||||
|
||||
### Building from source
|
||||
### 从源码构建
|
||||
|
||||
Users who wish to build MuJoCo from source should consult the [build from
|
||||
source] section of the documentation. However, note that the commit at
|
||||
the tip of the `main` branch may be unstable.
|
||||
希望从源码构建 MuJoCo 的用户请参阅文档中的[从源码构建][build from source]部分。但请注意，`main` 分支最新的提交可能不够稳定。
|
||||
|
||||
### Python (>= 3.10)
|
||||
|
||||
The native Python bindings, which come pre-packaged with a copy of MuJoCo, can
|
||||
be installed from [PyPI] via:
|
||||
原生 Python 绑定已预打包了 MuJoCo 副本，可以通过 [PyPI] 进行安装：
|
||||
|
||||
```bash
|
||||
pip install mujoco
|
||||
```
|
||||
|
||||
Note that Pre-built Linux wheels target `manylinux2014`, see
|
||||
[here](https://github.com/pypa/manylinux) for compatible distributions. For more
|
||||
information such as building the bindings from source, see the [Python bindings]
|
||||
section of the documentation.
|
||||
请注意，预构建的 Linux wheel 面向 `manylinux2014`，兼容的发行版参见[此处](https://github.com/pypa/manylinux)。有关从源码构建绑定等更多信息，请参阅文档中的 [Python 绑定][Python bindings]部分。
|
||||
|
||||
## Versioning
|
||||
## 版本规范
|
||||
|
||||
We aim to release MuJoCo in the first week of each month. Our versioning
|
||||
standards changed to modified Semantic Versioning in 3.5.0,
|
||||
see [versioning](VERSIONING.md) for details.
|
||||
我们力求在每月的首周发布新版本 MuJoCo。自 3.5.0 版本起，我们的版本命名规范变更为修订版语义化版本控制（modified Semantic Versioning），详情请参阅 [版本规范](VERSIONING.md)。
|
||||
|
||||
## Contributing
|
||||
## 参与贡献
|
||||
|
||||
We welcome community engagement: questions, requests for help, bug reports and
|
||||
feature requests. To read more about bug reports, feature requests and more
|
||||
ambitious contributions, please see our [contributors guide](CONTRIBUTING.md)
|
||||
and [style guide](STYLEGUIDE.md).
|
||||
我们非常欢迎社区参与：包括提问、寻求帮助、错误报告以及功能建议。欲了解更多有关提交 Bug 报告、功能需求以及更深入贡献的指引，请参阅我们的[贡献指南](CONTRIBUTING.md)和[代码风格指南](STYLEGUIDE.md)。
|
||||
|
||||
## Asking Questions
|
||||
## 提问与交流
|
||||
|
||||
Questions and requests for help are welcome as a GitHub
|
||||
["Asking for Help" Discussion](https://github.com/google-deepmind/mujoco/discussions/categories/asking-for-help)
|
||||
and should focus on a specific problem or question.
|
||||
欢迎在 GitHub 的 [“Asking for Help” 讨论区](https://github.com/google-deepmind/mujoco/discussions/categories/asking-for-help) 提出问题或寻求帮助，请尽量聚焦于具体的问题或疑问。
|
||||
|
||||
## Bug reports and feature requests
|
||||
## 错误报告与功能需求
|
||||
|
||||
GitHub [Issues](https://github.com/google-deepmind/mujoco/issues) are reserved
|
||||
for bug reports, feature requests and other development-related subjects.
|
||||
GitHub [Issues](https://github.com/google-deepmind/mujoco/issues) 仅用于提交 Bug 报告、功能需求以及其他与开发相关的主题。
|
||||
|
||||
## Related software
|
||||
MuJoCo is the backbone for numerous environment packages. Below we list several
|
||||
bindings and converters.
|
||||
## 相关软件生态
|
||||
|
||||
### Bindings
|
||||
MuJoCo 是许多仿真环境软件包的核心支撑。下面列出了一些语言绑定与格式转换器。
|
||||
|
||||
These packages give users of various languages access to MuJoCo functionality:
|
||||
### 语言绑定
|
||||
|
||||
#### First-party bindings:
|
||||
这些软件包为不同编程语言的用户提供了访问 MuJoCo 功能的接口：
|
||||
|
||||
- [Python bindings](https://mujoco.readthedocs.io/en/stable/python.html)
|
||||
- [dm_control](https://github.com/google-deepmind/dm_control), Google
|
||||
DeepMind's related environment stack, includes
|
||||
[PyMJCF](https://github.com/google-deepmind/dm_control/blob/main/dm_control/mjcf/README.md),
|
||||
a module for procedural manipulation of MuJoCo models.
|
||||
- [JavaScript bindings and WebAssembly support](/wasm/README.md) (inspired [stillonearth](https://github.com/stillonearth) and [zalo](https://github.com/zalo)'s community projects; [mjswan](https://github.com/ttktjmt/mjswan) extends these with real-time policy control, interactive force
|
||||
application, and more).
|
||||
- [C# bindings and Unity plug-in](https://mujoco.readthedocs.io/en/stable/unity.html)
|
||||
#### 第一方绑定：
|
||||
|
||||
#### Third-party bindings:
|
||||
- [Python 绑定](https://mujoco.readthedocs.io/en/stable/python.html)
|
||||
- [dm_control](https://github.com/google-deepmind/dm_control)，Google DeepMind 的相关环境技术栈，包含了用于程序化操作 MuJoCo 模型的模块 [PyMJCF](https://github.com/google-deepmind/dm_control/blob/main/dm_control/mjcf/README.md)。
|
||||
- [JavaScript 绑定与 WebAssembly 支持](/wasm/README.md)（灵感源于 [stillonearth](https://github.com/stillonearth) 和 [zalo](https://github.com/zalo) 的社区项目；[mjswan](https://github.com/ttktjmt/mjswan) 扩展了其实时策略控制、交互式施力等功能）。
|
||||
- [C# 绑定与 Unity 插件](https://mujoco.readthedocs.io/en/stable/unity.html)
|
||||
|
||||
- **MATLAB Simulink**: [Simulink Blockset for MuJoCo Simulator](https://github.com/mathworks-robotics/mujoco-simulink-blockset)
|
||||
by [Manoj Velmurugan](https://github.com/vmanoj1996).
|
||||
#### 第三方绑定：
|
||||
|
||||
- **MATLAB Simulink**: [Simulink Blockset for MuJoCo Simulator](https://github.com/mathworks-robotics/mujoco-simulink-blockset)（由 [Manoj Velmurugan](https://github.com/vmanoj1996) 开发）。
|
||||
- **Swift**: [swift-mujoco](https://github.com/liuliu/swift-mujoco)
|
||||
- **Java**: [mujoco-java](https://github.com/CommonWealthRobotics/mujoco-java)
|
||||
- **Julia**: [MuJoCo.jl](https://github.com/JamieMair/MuJoCo.jl)
|
||||
- **Rust**: [MuJoCo-rs](https://github.com/davidhozic/mujoco-rs)
|
||||
|
||||
### Converters
|
||||
### 格式转换工具
|
||||
|
||||
- **OpenSim**: [MyoConverter](https://github.com/MyoHub/myoconverter) converts
|
||||
OpenSim models to MJCF.
|
||||
- **SDFormat**: [gz-mujoco](https://github.com/gazebosim/gz-mujoco/) is a
|
||||
two-way SDFormat <-> MJCF conversion tool.
|
||||
- **OBJ**: [obj2mjcf](https://github.com/kevinzakka/obj2mjcf)
|
||||
a script for converting composite OBJ files into a loadable MJCF model.
|
||||
- **onshape**: [Onshape to Robot](https://github.com/rhoban/onshape-to-robot)
|
||||
Converts [onshape](https://www.onshape.com/en/) CAD assemblies to MJCF.
|
||||
- **OpenSim**: [MyoConverter](https://github.com/MyoHub/myoconverter) 将 OpenSim 模型转换为 MJCF。
|
||||
- **SDFormat**: [gz-mujoco](https://github.com/gazebosim/gz-mujoco/) 是 SDFormat 与 MJCF 之间的双向转换工具。
|
||||
- **OBJ**: [obj2mjcf](https://github.com/kevinzakka/obj2mjcf) 用于将组合 OBJ 文件转换为可加载的 MJCF 模型的脚本。
|
||||
- **onshape**: [Onshape to Robot](https://github.com/rhoban/onshape-to-robot) 将 [onshape](https://www.onshape.com/en/) CAD 装配体转换为 MJCF。
|
||||
|
||||
## Citation
|
||||
## 引用
|
||||
|
||||
If you use MuJoCo for published research, please cite:
|
||||
如果您在公开发表的学术研究中使用了 MuJoCo，请按如下格式引用：
|
||||
|
||||
```
|
||||
@inproceedings{todorov2012mujoco,
|
||||
@@ -177,22 +133,17 @@ If you use MuJoCo for published research, please cite:
|
||||
}
|
||||
```
|
||||
|
||||
## License and Disclaimer
|
||||
## 开源许可证与免责声明
|
||||
|
||||
Copyright 2021 DeepMind Technologies Limited.
|
||||
|
||||
Box collision code ([`engine_collision_box.c`](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_collision_box.c))
|
||||
is Copyright 2016 Svetoslav Kolev.
|
||||
盒体碰撞检测代码（[`engine_collision_box.c`](https://github.com/google-deepmind/mujoco/blob/main/src/engine/engine_collision_box.c)）版权所有 © 2016 Svetoslav Kolev。
|
||||
|
||||
ReStructuredText documents, images, and videos in the `doc` directory are made
|
||||
available under the terms of the Creative Commons Attribution 4.0 (CC BY 4.0)
|
||||
license. You may obtain a copy of the License at
|
||||
https://creativecommons.org/licenses/by/4.0/legalcode.
|
||||
`doc` 目录下的 ReStructuredText 文档、图像和视频均依据知识共享署名 4.0 国际许可协议（Creative Commons Attribution 4.0, CC BY 4.0）提供。您可在 https://creativecommons.org/licenses/by/4.0/legalcode 获取该许可证副本。
|
||||
|
||||
Source code is licensed under the Apache License, Version 2.0. You may obtain a
|
||||
copy of the License at https://www.apache.org/licenses/LICENSE-2.0.
|
||||
源代码基于 Apache 许可证 2.0 版（Apache License, Version 2.0）授权。您可在 https://www.apache.org/licenses/LICENSE-2.0 获取许可证副本。
|
||||
|
||||
This is not an officially supported Google product.
|
||||
本项目不是 Google 官方支持的产品。
|
||||
|
||||
[build from source]: https://mujoco.readthedocs.io/en/latest/programming#building-from-source
|
||||
[Getting Started]: https://mujoco.readthedocs.io/en/latest/programming#getting-started
|
||||
|
||||
+13
-28
@@ -7,48 +7,33 @@
|
||||
[pypi-badge]: https://badge.fury.io/py/mujoco-mjx.svg
|
||||
[pypi]: https://pypi.org/project/mujoco-mjx/
|
||||
|
||||
This package is a re-implementation of the
|
||||
[MuJoCo physics engine](https://github.com/google-deepmind/mujoco) in
|
||||
[JAX](https://github.com/jax-ml/jax). This library is developed and maintained
|
||||
by Google DeepMind, and is kept up-to-date with the latest developments in
|
||||
MuJoCo itself.
|
||||
本软件包是基于 [JAX](https://github.com/jax-ml/jax) 对 [MuJoCo 物理引擎](https://github.com/google-deepmind/mujoco) 的重新实现。该库由 Google DeepMind 开发和维护，并与 MuJoCo 本身的最新进展保持同步。
|
||||
|
||||
The `mujoco-mjx` package is API-compatible with MuJoCo, but is missing some
|
||||
features found in MuJoCo. See our
|
||||
[documentation](https://mujoco.readthedocs.io/en/stable/mjx.html) for more
|
||||
details concerning feature parity.
|
||||
`mujoco-mjx` 软件包在 API 上与 MuJoCo 兼容，但缺少 MuJoCo 中的某些功能。有关功能特性的对齐情况，请参阅我们的[官方文档](https://mujoco.readthedocs.io/en/stable/mjx.html)。
|
||||
|
||||
## Installation
|
||||
## 安装
|
||||
|
||||
The recommended way to install this package is via [PyPI](https://pypi.org/project/mujoco-mjx/):
|
||||
推荐通过 [PyPI](https://pypi.org/project/mujoco-mjx/) 安装本软件包：
|
||||
|
||||
```sh
|
||||
pip install mujoco-mjx
|
||||
```
|
||||
|
||||
## Usage
|
||||
## 使用说明
|
||||
|
||||
Once installed, the package can be imported via `from mujoco import mjx`. Please
|
||||
consult our [documentation](https://mujoco.readthedocs.io/en/stable/mjx.html)
|
||||
for further detail on the package's API.
|
||||
安装完成后，可以通过 `from mujoco import mjx` 导入该包。有关该包 API 的更多详细信息，请参阅我们的[官方文档](https://mujoco.readthedocs.io/en/stable/mjx.html)。
|
||||
|
||||
We recommend going through the tutorial notebook which introduces the MJX API
|
||||
and trains a reinforcement learning policy in a few minutes: [](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/tutorial.ipynb)
|
||||
我们建议查阅教程 Notebook，它介绍了 MJX API 并在数分钟内训练一个强化学习策略：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/mjx/tutorial.ipynb)
|
||||
|
||||
## Versioning
|
||||
## 版本规范
|
||||
|
||||
The `major.minor.micro` portion of the version number matches the version of
|
||||
MuJoCo that this library provides. Optionally, if we release updates to MJX that
|
||||
target the same version of MuJoCo, a `.postN` suffix is added, for example
|
||||
`3.0.1.post2` represents the second update to MJX for MuJoCo 3.0.1.
|
||||
版本号的 `major.minor.micro` 部分与该库所基于的 MuJoCo 版本保持一致。可选地，如果我们发布了针对同一 MuJoCo 版本的 MJX 自身更新，则会添加 `.postN` 后缀，例如 `3.0.1.post2` 表示针对 MuJoCo 3.0.1 的 MJX 第二次更新。
|
||||
|
||||
## License and Disclaimer
|
||||
## 开源许可证与免责声明
|
||||
|
||||
Copyright 2023 DeepMind Technologies Limited
|
||||
|
||||
MuJoCo and its libraries are licensed under the Apache License,
|
||||
Version 2.0. You may obtain a copy of the License at
|
||||
https://www.apache.org/licenses/LICENSE-2.0.
|
||||
MuJoCo 及其相关库基于 Apache 许可证 2.0 版（Apache License, Version 2.0）授权。您可在 https://www.apache.org/licenses/LICENSE-2.0 获取许可证副本。
|
||||
|
||||
This is not an officially supported Google product.
|
||||
本项目不是 Google 官方支持的产品。
|
||||
|
||||
@@ -1,11 +1,10 @@
|
||||
# MJX Warp Codegen
|
||||
# MJX Warp 代码生成（Codegen）
|
||||
|
||||
Generates the MJX-Warp shim layer in `mujoco/mjx/warp/` by reading the vendored
|
||||
`mujoco_warp` source in `mujoco/mjx/third_party/mujoco_warp/`.
|
||||
通过读取 `mujoco/mjx/third_party/mujoco_warp/` 中内嵌的 `mujoco_warp` 源码，在 `mujoco/mjx/warp/` 下生成 MJX-Warp 垫片适配层（shim layer）。
|
||||
|
||||
## Setup
|
||||
## 环境配置
|
||||
|
||||
From the root `mjx/` directory, once you install [`uv`](https://docs.astral.sh/uv/getting-started/installation/), install the latest MuJoCo and local MJX:
|
||||
在根目录 `mjx/` 下，安装 [`uv`](https://docs.astral.sh/uv/getting-started/installation/) 之后，安装最新的 MuJoCo 和本地 MJX：
|
||||
|
||||
```bash
|
||||
uv venv .venv --default-index https://pypi.org/simple
|
||||
@@ -14,9 +13,9 @@ uv pip install --upgrade --force-reinstall mujoco --default-index https://pypi.o
|
||||
uv pip install -e ".[warp,dev]" --default-index https://pypi.org/simple
|
||||
```
|
||||
|
||||
## Run codegen
|
||||
## 运行代码生成
|
||||
|
||||
From the root `mjx/` directory:
|
||||
在根目录 `mjx/` 下执行：
|
||||
|
||||
```bash
|
||||
bash mujoco/mjx/codegen/update_for_mujoco_warp.sh
|
||||
|
||||
@@ -1,19 +1,19 @@
|
||||
# Google Barkour v0
|
||||
|
||||
## MJCF Instructions
|
||||
## MJCF 说明
|
||||
|
||||
The MuJoCo config in `assets/barkour_v0_mjx.xml` was copied from https://github.com/deepmind/mujoco_menagerie/google_barkour_v0. The following edits were made to the MJCF specifically for brax:
|
||||
`assets/barkour_v0_mjx.xml` 中的 MuJoCo 配置复制自 https://github.com/deepmind/mujoco_menagerie/google_barkour_v0 。为了适配 Brax，对该 MJCF 进行了以下专门修改：
|
||||
|
||||
* `meshdir` was changed from `assets` to `.`.
|
||||
* `frictionloss` was removed. `damping` was changed to 0.5239.
|
||||
* A custom `init_qpos` was added.
|
||||
* A sphere geom `lowerLegFoot` was added to all feet. All other contacts were turned off.
|
||||
* The compiler option was changed to `<option timestep="0.002" iterations="4" solver="CG"/>`.
|
||||
* Non-visual geoms were removed from the torso, to speed up rendering.
|
||||
* `meshdir` 从 `assets` 修改为 `.`。
|
||||
* 移除 `frictionloss`，将 `damping` 修改为 0.5239。
|
||||
* 添加了自定义 `init_qpos`。
|
||||
* 为所有足部添加了球体几何体 `lowerLegFoot`。关闭了所有其他碰撞接触。
|
||||
* 编译器选项修改为 `<option timestep="0.002" iterations="4" solver="CG"/>`。
|
||||
* 移除了躯干上的非可视化几何体，以加快渲染速度。
|
||||
|
||||
## Publications
|
||||
## 发表文献
|
||||
|
||||
If you use this work in an academic context, please cite the following publication:
|
||||
如果您在学术研究中使用了本项工作，请按如下格式引用：
|
||||
|
||||
@misc{caluwaerts2023barkour,
|
||||
title={Barkour: Benchmarking Animal-level Agility with Quadruped Robots},
|
||||
|
||||
@@ -1,26 +1,17 @@
|
||||
Humanoid
|
||||
========
|
||||
# 人形机器人（Humanoid）
|
||||
|
||||
Degrees of Freedom: 27
|
||||
Actuators: 21
|
||||
* 自由度（Degrees of Freedom）：27
|
||||
* 执行器（Actuators）：21
|
||||
|
||||
This is a clone of the [MuJoCo Humanoid](https://github.com/google-deepmind/mujoco/blob/main/model/humanoid/humanoid.xml)
|
||||
with the following changes:
|
||||
这是 [MuJoCo Humanoid](https://github.com/google-deepmind/mujoco/blob/main/model/humanoid/humanoid.xml) 的克隆版本，包含以下修改：
|
||||
|
||||
* Solver switched to CG with 8 iterations
|
||||
* Explicit contact pairs for feet and ground (compatible with
|
||||
[OpenAI Gym Humanoid](https://gymnasium.farama.org/environments/mujoco/humanoid/)
|
||||
environment)
|
||||
* 求解器切换为带有 8 次迭代的 CG（共轭梯度法）
|
||||
* 足部和地面的显式接触对（兼容 [OpenAI Gym Humanoid](https://gymnasium.farama.org/environments/mujoco/humanoid/) 环境）
|
||||
|
||||
This simplified humanoid model, introduced in [1], is designed for bipedal
|
||||
locomotion behaviours. While several variants of it exist in the wild, this
|
||||
version is based on the model in the DeepMind Control Suite [2], which has
|
||||
fairly realistic actuator gains.
|
||||
本简化人形机器人模型最初在文献 [1] 中提出，专为双足运动控制行为设计。尽管社区中存在多种变体，但此版本基于 DeepMind Control Suite [2] 中的模型构建，具备较为逼真的执行器增益。
|
||||
|
||||
[1] [Synthesis and Stabilization of Complex Behaviors through Online Trajectory Optimization]
|
||||
(https://doi.org/10.1109/IROS.2012.6386025).
|
||||
[1] [Synthesis and Stabilization of Complex Behaviors through Online Trajectory Optimization](https://doi.org/10.1109/IROS.2012.6386025).
|
||||
|
||||
[2] [DeepMind Control Suite](https://arxiv.org/abs/1801.00690).
|
||||
|
||||
|
||||
|
||||
|
||||
@@ -1,28 +1,24 @@
|
||||
# Shadow Hand E3M5 Description (MJCF)
|
||||
# Shadow Hand E3M5 模型描述（MJCF）
|
||||
|
||||
Requires MuJoCo 3.0.0 or later.
|
||||
需要 MuJoCo 3.0.0 或更高版本。
|
||||
|
||||
## Overview
|
||||
## 概述
|
||||
|
||||
This package contains assets of the "E3M5" version of the Shadow Hand robot,
|
||||
including both right-handed and left-handed versions.
|
||||
The original URDF and assets were provided directly by
|
||||
[Shadow Robot Company](https://www.shadowrobot.com/) under the
|
||||
[Apache 2.0 License](LICENSE).
|
||||
本软件包包含 Shadow Hand 机器人“E3M5”版本的资产，包括右手和左手版本。
|
||||
原始 URDF 和资产由 [Shadow Robot Company](https://www.shadowrobot.com/) 在 [Apache 2.0 许可证](LICENSE) 下直接提供。
|
||||
|
||||
The [original Menagerie Shadow Hand](https://github.com/google-deepmind/mujoco_menagerie/tree/main/shadow_hand)
|
||||
has been modified for MJX simulation in the following ways:
|
||||
来自 [Menagerie 的原始 Shadow Hand](https://github.com/google-deepmind/mujoco_menagerie/tree/main/shadow_hand) 针对 MJX 仿真进行了如下修改：
|
||||
|
||||
* Solver switched to CG with 8 iterations
|
||||
* Condim switched to 3 (MJX does not yet support condim != 3)
|
||||
* Object converted from ellipsoid to sphere (MJX does not yet support ellipsoids)
|
||||
* Explicit contact pairs for fingers and object
|
||||
* Removed some unused geoms in the arm base
|
||||
* 求解器切换为带有 8 次迭代的 CG（共轭梯度法）
|
||||
* Condim 切换为 3（MJX 暂不支持 condim != 3）
|
||||
* 物体从椭球体转换为球体（MJX 暂不支持椭球体）
|
||||
* 为手指和物体设置显式接触对（contact pairs）
|
||||
* 移除了机械臂基座中一些未使用的几何体
|
||||
|
||||
<p float="left">
|
||||
<img src="shadow_hand.png" width="400">
|
||||
</p>
|
||||
|
||||
## License
|
||||
## 开源许可证
|
||||
|
||||
These models are released under an [Apache-2.0 License](LICENSE).
|
||||
这些模型基于 [Apache-2.0 许可证](LICENSE) 发布。
|
||||
|
||||
@@ -1,9 +1,8 @@
|
||||
# Active adhesion example
|
||||
# 主动吸附示例
|
||||
|
||||
This example model shows how to use adhesion actuators.
|
||||
本示例模型演示了如何使用吸附执行器（Adhesion Actuator）。
|
||||
|
||||
The video below is a screen capture of a user interacting with the model:
|
||||
下方视频展示了用户与该模型进行交互的录屏：
|
||||
|
||||
|
||||
[](https://www.youtube.com/watch?v=BcHZ5BFeTmU)
|
||||
|
||||
[](https://www.youtube.com/watch?v=BcHZ5BFeTmU)
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Cube
|
||||
# 魔方（Cube）
|
||||
|
||||
This model was contributed by Kevin Zakka. For details regarding its creation, see the associated [repository](https://github.com/kevinzakka/mujoco_cube).
|
||||
该模型由 Kevin Zakka 贡献。关于其创建的详细信息，请参阅相关[代码仓库](https://github.com/kevinzakka/mujoco_cube)。
|
||||
|
||||
Click the video below to see a user interacting with the cube:
|
||||
点击下方视频查看用户与魔方交互的演示：
|
||||
|
||||
[](https://www.youtube.com/watch?v=ZppeDArq6AU)
|
||||
[](https://www.youtube.com/watch?v=ZppeDArq6AU)
|
||||
|
||||
+21
-23
@@ -1,35 +1,33 @@
|
||||
# Humanoid
|
||||
# 人形机器人（Humanoid）
|
||||
|
||||
This simplified humanoid model, introduced in [1], is designed for bipedal locomotion
|
||||
behaviours. While several variants of it exist in the wild, this version is based on the model
|
||||
in the DeepMind Control Suite [2], which has fairly realistic actuator gains.
|
||||
本简化人形机器人模型最初在文献 [1] 中提出，专为双足运动控制行为设计。尽管社区中存在多种变体，但此版本基于 DeepMind Control Suite [2] 中的模型构建，具备较为逼真的执行器增益。
|
||||
|
||||
* Degrees of Freedom: 27
|
||||
* Actuators: 21
|
||||
* 自由度（Degrees of Freedom）：27
|
||||
* 执行器（Actuators）：21
|
||||
|
||||
<p float="left">
|
||||
<img src="humanoid.png" width="400">
|
||||
</p>
|
||||
|
||||
## Changelog
|
||||
## 更新日志
|
||||
|
||||
* 08-10-2024: Moved tracking light from the torso to the world.
|
||||
* 20-02-2024: Sorted actuators in the same order as the joints.
|
||||
* 02-01-2024: Add more keyframes.
|
||||
* 27-11-2023: Move humanoid geoms to group 1.
|
||||
* 05-04-2023: Fix typo in texture size.
|
||||
* 20-09-2022: Use default class for left_upper_arm geom.
|
||||
* 17-09-2022: Increase offscreen render buffer resolution of the humanoid to 2560x1440.
|
||||
* 12-09-2022:
|
||||
* Increased maximum hip flexion.
|
||||
* Symmetrised shoulder and ankle joints.
|
||||
* Added hamstring tendons which couple the hip and knee at large flexion values.
|
||||
* Moved duplicated values into defaults.
|
||||
* Added two keyframes.
|
||||
* Improved lighting.
|
||||
* Changed naming convention.
|
||||
* 2024-10-08：将跟踪光源从躯干移动到全局世界（world）。
|
||||
* 2024-02-20：将执行器排序调整为与关节相同的顺序。
|
||||
* 2024-01-02：添加了更多关键帧。
|
||||
* 2023-11-27：将人形机器人的几何体移动到 group 1。
|
||||
* 2023-04-05：修复纹理尺寸中的拼写错误。
|
||||
* 2022-09-20：为 left_upper_arm geom 使用 default class。
|
||||
* 2022-09-17：将人形机器人的离屏渲染缓冲区分辨率提升至 2560x1440。
|
||||
* 2022-09-12：
|
||||
* 增大了髋关节最大屈曲角度。
|
||||
* 使肩关节和踝关节对称化。
|
||||
* 添加了腘绳肌肌腱（hamstring tendons），在大角度屈曲时耦合髋部和膝盖。
|
||||
* 将重复的属性值合并到 defaults。
|
||||
* 添加了两个关键帧。
|
||||
* 改进了光照效果。
|
||||
* 修改了命名规范。
|
||||
|
||||
## References
|
||||
## 参考文献
|
||||
|
||||
[1] [Synthesis and Stabilization of Complex Behaviors through Online Trajectory Optimization](https://doi.org/10.1109/IROS.2012.6386025).
|
||||
|
||||
|
||||
@@ -1,2 +1 @@
|
||||
The spot assets were taken from https://www.cs.cmu.edu/~kmcrane/Projects/ModelRepository/ and are
|
||||
released under the CC0 1.0 Universal (CC0 1.0) Public Domain Dedication license.
|
||||
Spot 相关的三维模型资产来源于 https://www.cs.cmu.edu/~kmcrane/Projects/ModelRepository/ ，并在 CC0 1.0 Universal (CC0 1.0) 公共领域贡献许可协议下发布。
|
||||
|
||||
@@ -1,27 +1,26 @@
|
||||
# Replicate
|
||||
# 复制元元素（Replicate）
|
||||
|
||||
Models in this directory provide usage examples of the `<replicate>` meta-element, see
|
||||
[documentation](https://mujoco.readthedocs.io/en/stable/XMLreference.html#replicate-r).
|
||||
此目录下的模型提供了 `<replicate>` 元元素的使用示例，详见[官方文档](https://mujoco.readthedocs.io/en/stable/XMLreference.html#replicate-r)。
|
||||
|
||||
The models contain several categories:
|
||||
这些模型涵盖以下几个类别：
|
||||
|
||||
1. Constructing static geometries:
|
||||
1. 构建静态几何体：
|
||||
- cylinder.xml
|
||||
- bowl.xml
|
||||
- helix.xml
|
||||
- container.xml
|
||||
|
||||
2. Replicating moving bodies:
|
||||
2. 复制运动刚体：
|
||||
- particle.xml
|
||||
- bunnies.xml
|
||||
- leaves.xml
|
||||
- stonehenge.xml
|
||||
|
||||
3. Replicas that include tendons:
|
||||
3. 包含肌腱/绳索（Tendon）的复制：
|
||||
- newton_cradle.xml
|
||||
- tendon.xml
|
||||
|
||||
4. Replicas with multiple referencing elements:
|
||||
4. 包含多个引用元素的复制：
|
||||
- references.xml
|
||||
|
||||
[](https://www.youtube.com/watch?v=5k0_wsIRAFc)
|
||||
[](https://www.youtube.com/watch?v=5k0_wsIRAFc)
|
||||
|
||||
+11
-11
@@ -1,13 +1,13 @@
|
||||
# Actuator plugins
|
||||
# 执行器插件（Actuator plugins）
|
||||
|
||||
## PID
|
||||
|
||||
The `mujoco.pid` actuator plugin implements a configurable [PID controller](https://en.wikipedia.org/wiki/Proportional%E2%80%93integral%E2%80%93derivative_controller):
|
||||
`mujoco.pid` 执行器插件实现了一个可配置的 [PID 控制器](https://en.wikipedia.org/wiki/Proportional%E2%80%93integral%E2%80%93derivative_controller)：
|
||||
|
||||
$$f(t) = K_\text{p} e(t) + K_\text{i} \int_0^t e(\tau) \mathrm{d}\tau + K_\text{d} \frac{\mathrm{d}e(t)}{\mathrm{d}t},$$
|
||||
where $e(t) = u(t) - \ell(t)$ is the difference between the control $u$ and the actuator length $\ell$.
|
||||
其中 $e(t) = u(t) - \ell(t)$ 是控制量 $u$ 与执行器长度 $\ell$ 之间的差值。
|
||||
|
||||
You can use it like:
|
||||
使用示例如下：
|
||||
|
||||
```xml
|
||||
<mujoco>
|
||||
@@ -36,12 +36,12 @@ You can use it like:
|
||||
</mujoco>
|
||||
```
|
||||
|
||||
The available options are:
|
||||
可用配置选项如下：
|
||||
|
||||
|Attribute | Default | Meaning |
|
||||
|属性 | 默认值 | 含义 |
|
||||
|----------|---------|---------|
|
||||
|`kp` | 0 | **P** gain for the controller. |
|
||||
|`ki` | 0 | **I** gain for the controller.<p/>If nonzero, one activation variable will be added to `mjData.act`, containing the current I term (in units of force). |
|
||||
|`kd` | 0 | **D** gain for the controller. |
|
||||
|`imax` | Optional | If specified, the force produced by the I term will be clipped to the range `[-imax, imax]`. |
|
||||
|`slewmax` | Optional | The maximum rate at which the setpoint for the PID controller can change.<p/>If a bigger change is requested between two timesteps, it will be clipped to the range `[ctrl - slewmax * dt, ctrl + slewmax * dt]`<p/>If specified, one activation variable will be added to `mjData.act` containing the previous value of `ctrl`. |
|
||||
|`kp` | 0 | 控制器的**比例（P）**增益。 |
|
||||
|`ki` | 0 | 控制器的**积分（I）**增益。<p/>若非零，将在 `mjData.act` 中添加一个激活变量，用于存储当前的积分项（以力为单位）。 |
|
||||
|`kd` | 0 | 控制器的**微分（D）**增益。 |
|
||||
|`imax` | 可选 | 若指定，积分项产生的力将被截断至 `[-imax, imax]` 范围内。 |
|
||||
|`slewmax` | 可选 | PID 控制器设定点允许的最大变化速率（斜率限制）。<p/>若两个时间步之间请求了更大的变化，它将被截断至 `[ctrl - slewmax * dt, ctrl + slewmax * dt]` 范围。<p/>若指定，将在 `mjData.act` 中添加一个激活变量，用于存储上一个时间步的 `ctrl` 值。 |
|
||||
|
||||
+10
-10
@@ -2,19 +2,19 @@
|
||||
<a href="#"><img alt="MuJoCo" src="../../banner.png" width="100%"/></a>
|
||||
</h1>
|
||||
|
||||
## Elasticity plugins
|
||||
## 弹性插件（Elasticity plugins）
|
||||
|
||||
These are first-party plugins that implement passive forces based on discretized continuum mechanics models. They can be applied to **flexes** and **bodies** (via the **composite** functionality). Sample models can be found in [this folder](../../model/plugin/elasticity/).
|
||||
这些是第一方插件，基于离散连续介质力学模型实现被动力。它们可以应用于 **flexes**（柔性体）和 **bodies**（刚体，通过 **composite** 复合体功能）。示例模型可在[此文件夹](../../model/plugin/elasticity/)中找到。
|
||||
|
||||
### Cable
|
||||
### 缆绳（Cable）
|
||||
|
||||
Implemented in [cable.cc](cable.cc).
|
||||
在 [cable.cc](cable.cc) 中实现。
|
||||
|
||||
The cable plugin discretizes an inextensible 1D continuum. It is intended to simulate the twist and bending of rods where the stretching in negligible compared to the other deformation modes.
|
||||
缆绳插件离散化了一个不可伸长的一维连续介质。它旨在模拟细杆的扭转和弯曲，在这些场景下拉伸形变与其他形变模式相比可以忽略不计。
|
||||
|
||||
Parameters:
|
||||
参数：
|
||||
|
||||
- `twist` [Pa]: twisting stiffness.
|
||||
- `bend` [Pa]: bending stiffness.
|
||||
- `flat` [bool]: if true, the stress-equilibrium configuration is that of a straight cable; if false or unspecified, it is the configuration defined in the XML.
|
||||
- `vmax` [N/m^2]: If greater than zero, the cable is colored using mechanical stresses; the value represent the maximum stress in the color scale.
|
||||
- `twist` [Pa]：扭转刚度。
|
||||
- `bend` [Pa]：弯曲刚度。
|
||||
- `flat` [bool]：若为 true，应力平衡构型为直缆状态；若为 false 或未指定，则为 XML 中定义的初始构型。
|
||||
- `vmax` [N/m^2]：若大于零，缆绳将根据机械应力着色；该值代表颜色标尺中的最大应力。
|
||||
|
||||
+42
-51
@@ -2,106 +2,97 @@
|
||||
<a href="#"><img alt="MuJoCo" src="../../banner.png" width="100%"/></a>
|
||||
</h1>
|
||||
|
||||
## Signed distance function (SDF) plugins
|
||||
## 符号距离函数（SDF）插件
|
||||
|
||||
These are first-party plugins that implement implicit geometries using SDFs. They can be applied to **geoms** and
|
||||
**meshes** (in the **asset** section). Sample models can be found in [this folder](../../model/plugin/sdf/).
|
||||
这些是第一方插件，使用符号距离函数（Signed Distance Functions, SDF）实现隐式几何体。它们可以应用于 **geoms**（几何体）和 **meshes**（网格，在 **asset** 资产部分）。示例模型可在[此文件夹](../../model/plugin/sdf/)中找到。
|
||||
|
||||
### Bolt
|
||||
### 螺栓（Bolt）
|
||||
|
||||
Implemented in [bolt.cc](bolt.cc). Example usage in [nutbolt.xml](../../model/plugin/sdf/nutbolt.xml).
|
||||
在 [bolt.cc](bolt.cc) 中实现。使用示例见 [nutbolt.xml](../../model/plugin/sdf/nutbolt.xml)。
|
||||
|
||||
This plugin implements a bolt with a hexagonal head, similar to https://www.shadertoy.com/view/XtffzX.
|
||||
该插件实现了一个带有六角头的螺栓，类似于 https://www.shadertoy.com/view/XtffzX。
|
||||
|
||||
Parameters:
|
||||
参数：
|
||||
|
||||
- `radius` [m]: bolt radius (default `0.26`).
|
||||
- `radius` [m]：螺栓半径（默认 `0.26`）。
|
||||
|
||||
### Bowl
|
||||
### 碗（Bowl）
|
||||
|
||||
Implemented in [bowl.cc](bowl.cc). Example usage in [bowl.xml](../../model/plugin/sdf/bowl.xml).
|
||||
在 [bowl.cc](bowl.cc) 中实现。使用示例见 [bowl.xml](../../model/plugin/sdf/bowl.xml)。
|
||||
|
||||
The plugin implements a cut hollow sphere from https://www.shadertoy.com/view/7tVXRt.
|
||||
该插件实现了来自 https://www.shadertoy.com/view/7tVXRt 的被切割中空球体。
|
||||
|
||||
Parameters:
|
||||
参数：
|
||||
|
||||
- `height` [m]: location of the cut plane (default `0.4`).
|
||||
- `radius` [m]: radius of the sphere (default `1`).
|
||||
- `thickness` [m]: thickness of the bowl (default `0.02`).
|
||||
- `height` [m]：切割平面的位置（默认 `0.4`）。
|
||||
- `radius` [m]：球体半径（默认 `1`）。
|
||||
- `thickness` [m]：碗的壁厚（默认 `0.02`）。
|
||||
|
||||
### Gear
|
||||
### 齿轮（Gear）
|
||||
|
||||
Implemented in [gear.cc](gear.cc). Example usage in [gear.xml](../../model/plugin/sdf/gear.xml).
|
||||
在 [gear.cc](gear.cc) 中实现。使用示例见 [gear.xml](../../model/plugin/sdf/gear.xml)。
|
||||
|
||||
The plugin implements a 3D extrusion of the 2D gear geometry from https://www.shadertoy.com/view/3lG3WR.
|
||||
该插件实现了来自 https://www.shadertoy.com/view/3lG3WR 的 2D 齿轮几何体的 3D 拉伸挤出。
|
||||
|
||||
Parameters:
|
||||
参数：
|
||||
|
||||
- `alpha` [m]: initial angle of rotation of the gear (default `0`).
|
||||
- `diameter` [m]: gear diameter (default `2.8`).
|
||||
- `teeth` []: number of teeth (default `25`).
|
||||
- `alpha` [m]：齿轮的初始旋转角度（默认 `0`）。
|
||||
- `diameter` [m]：齿轮直径（默认 `2.8`）。
|
||||
- `teeth` []：齿数（默认 `25`）。
|
||||
|
||||
### Nut
|
||||
### 螺母（Nut）
|
||||
|
||||
Implemented in [nut.cc](nut.cc). Example usage in [nutbolt.xml](../../model/plugin/sdf/nutbolt.xml).
|
||||
在 [nut.cc](nut.cc) 中实现。使用示例见 [nutbolt.xml](../../model/plugin/sdf/nutbolt.xml)。
|
||||
|
||||
This plugin implements a hexagonal nut identical to the bolt head from https://www.shadertoy.com/view/XtffzX.
|
||||
该插件实现了一个六角螺母，与来自 https://www.shadertoy.com/view/XtffzX 的螺栓头部相同。
|
||||
|
||||
Parameters:
|
||||
参数：
|
||||
|
||||
- `radius` [m]: nut radius (default `0.26`).
|
||||
- `radius` [m]：螺母半径（默认 `0.26`）。
|
||||
|
||||
### Torus
|
||||
### 圆环体（Torus）
|
||||
|
||||
Implemented in [torus.cc](torus.cc). Example usage in [torus.xml](../../model/plugin/sdf/torus.xml).
|
||||
在 [torus.cc](torus.cc) 中实现。使用示例见 [torus.xml](../../model/plugin/sdf/torus.xml)。
|
||||
|
||||
This plugin implements a torus.
|
||||
该插件实现了一个圆环体。
|
||||
|
||||
Parameters:
|
||||
参数：
|
||||
|
||||
- `radius1` [m]: major radius (default `0.35`).
|
||||
- `radius1` [m]: minor radius (default `0.15`).
|
||||
- `radius1` [m]：主半径/大半径（默认 `0.35`）。
|
||||
- `radius1` [m]：次半径/小半径（默认 `0.15`）。
|
||||
|
||||
### How to make your own SDF
|
||||
### 如何创建自定义 SDF
|
||||
|
||||
Create your `MySDF.h` and `MySDF.cc` files in the SDF folder, where this README is located. Implement your SDF using the
|
||||
following interface:
|
||||
在当前 README 所在的 SDF 文件夹中创建您的 `MySDF.h` 和 `MySDF.cc` 文件。使用以下接口实现您的 SDF：
|
||||
|
||||
```
|
||||
```cpp
|
||||
struct MySDFAttribute {
|
||||
static constexpr int nattribute =
|
||||
/* insert the number of attributes */;
|
||||
/* 填入属性数量 */;
|
||||
static constexpr char const* names[nattribute] =
|
||||
/* an array of attributes with the same order as the attribute array in your SDF class */;
|
||||
/* 与 SDF 类中属性数组顺序相同的属性名称数组 */;
|
||||
static constexpr mjtNum defaults[nattribute] =
|
||||
/* an array of default values for your attributes */;
|
||||
/* 属性的默认值数组 */;
|
||||
};
|
||||
|
||||
class MySDF {
|
||||
public:
|
||||
// creates a new MySDF instance or returns null on failure.
|
||||
// 创建新的 MySDF 实例，失败时返回 null。
|
||||
static std::optional<MySDF> Create(const mjModel* m, mjData* d, int instance);
|
||||
MySDF(MySDF&&) = default;
|
||||
~MySDF() = default;
|
||||
|
||||
// functions that return the SDF and its gradient at a query point
|
||||
// 在查询点返回 SDF 距离及其梯度的函数
|
||||
mjtNum Distance(const mjtNum point[3]) const;
|
||||
void Gradient(mjtNum grad[3], const mjtNum point[3]) const;
|
||||
|
||||
// a call to this needs to be added to register.cc
|
||||
// 需要在 register.cc 中添加对此函数的调用
|
||||
static void RegisterPlugin();
|
||||
|
||||
// an array of attributes with the same order as in the struct above
|
||||
// 与上述结构体中顺序相同的属性数组
|
||||
mjtNum attribute[MySDFAttribute::nattribute];
|
||||
|
||||
private:
|
||||
MySDF(const mjModel* m, mjData* d, int instance);
|
||||
};
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
+38
-63
@@ -1,45 +1,34 @@
|
||||
# Sensor Plugins
|
||||
# 传感器插件（Sensor Plugins）
|
||||
|
||||
Custom sensors implemented as [engine
|
||||
plugins](https://mujoco.readthedocs.io/en/latest/programming/extension.html#engine-plugins).
|
||||
通过[引擎插件](https://mujoco.readthedocs.io/en/latest/programming/extension.html#engine-plugins)实现的自定义传感器。
|
||||
|
||||
- [Touch Grid](#touch-grid)
|
||||
- [Example model](#example-model)
|
||||
- [Illustration of fields-of-view in spherical coordinates](#illustration-of-fields-of-view-in-spherical-coordinates)
|
||||
- [Illustration of foveal deformation](#illustration-of-foveal-deformation)
|
||||
- [Illustration combining resolution, fields-of-view and foveal deformation](#illustration-combining-resolution-fields-of-view-and-foveal-deformation)
|
||||
- [触觉网格（Touch Grid）](#touch-grid)
|
||||
- [示例模型](#example-model)
|
||||
- [球坐标系下的视场角图示](#illustration-of-fields-of-view-in-spherical-coordinates)
|
||||
- [中央凹形变图示](#illustration-of-foveal-deformation)
|
||||
- [结合分辨率、视场角和中央凹形变的综合图示](#illustration-combining-resolution-fields-of-view-and-foveal-deformation)
|
||||
|
||||
- [Touch Stress](#touch-stress)
|
||||
- [Example model with analytical SDF](#example-model-with-analytical-sdf)
|
||||
- [触觉应力（Touch Stress）](#touch-stress)
|
||||
- [解析 SDF 示例模型](#example-model-with-analytical-sdf)
|
||||
|
||||
## [Touch Grid](touch_grid.h)
|
||||
|
||||
This sensor aggregates contact forces into "taxels": a rectangular array of pixel-like elements.
|
||||
该传感器将接触力聚合到“触觉像素（taxels）”中：即类似像素的矩形阵列单元。
|
||||
|
||||
A `touch_grid` sensor is associated with a site and senses contact forces and
|
||||
torques between the site's parent body and all other bodies. The site's frame
|
||||
determines the orientation of the sensor with the same convention used for
|
||||
cameras and lights: the sensor points in the frame's **negative-z** direction,
|
||||
so the x and y axes correspond to horizontal and vertical, respectively.
|
||||
`touch_grid` 传感器与一个 site（位姿点）关联，用于感知该 site 所属的父刚体与所有其他刚体之间的接触力和力矩。site 的坐标系决定了传感器的朝向，采用与相机和光源相同的约定：传感器指向坐标系的 **-z（负 z 轴）**方向，因此 x 轴和 y 轴分别对应水平方向和垂直方向。
|
||||
|
||||
The output of the sensor is a stack of 1 to 6 "touch images" corresponding to forces
|
||||
and torques in the frame of the sensor. Forces and torques are in the in [z, x,
|
||||
y] order, corresponding to the ordering in contact frames: [normal, tangent,
|
||||
tangent] and [torsional, rolling, rolling]. Each "taxel" corresponds to an angular bin
|
||||
in spherical coordinates, and aggregates all the forces occurring inside this bin, which occur
|
||||
between the body in which the sensor's site is defined and any other body.
|
||||
该传感器的输出是 1 到 6 个“触觉图像（touch images）”的堆叠，对应于传感器坐标系中的力和力矩。力和力矩按照 [z, x, y] 顺序排列，对应于接触坐标系中的顺序：[法向, 切向, 切向] 和 [扭转, 滚动, 滚动]。每个“触觉像素（taxel）”对应于球坐标系中的一个角度分桶（angular bin），并聚合该分桶内发生的所有接触力（发生在传感器 site 所属刚体与任何其他刚体之间）。
|
||||
|
||||
The sensor is parametrized by 6 numbers:
|
||||
该传感器由 6 个参数进行参数化：
|
||||
|
||||
1. Number of channels, in the order given above. _positive integer in [1 6]_
|
||||
2. Horizontal resolution. _positive integer_
|
||||
3. Vertical resolution. _positive integer_
|
||||
4. Horizontal field-of-view. _positive float in (0, 180] degrees_
|
||||
5. Vertical field-of-view. _positive float in (0, 90] degrees_
|
||||
6. Foveal deformation. _positive float in [0, 1]_
|
||||
1. 通道数（按照上述顺序）：_取值范围为 [1, 6] 的正整数_
|
||||
2. 水平分辨率：_正整数_
|
||||
3. 垂直分辨率：_正整数_
|
||||
4. 水平视场角（FOV）：_角度范围在 (0, 180] 度的正浮点数_
|
||||
5. 垂直视场角（FOV）：_角度范围在 (0, 90] 度的正浮点数_
|
||||
6. 中央凹形变（Foveal deformation）：_取值范围在 [0, 1] 的正浮点数_
|
||||
|
||||
See illustrations below for a visual explanation of the field-of-view and foveal
|
||||
deformation parameters. These parameters are passed as plugin config attributes:
|
||||
有关视场角和中央凹形变参数的可视化解释，请参见下方的图示。这些参数作为插件的配置属性进行传递：
|
||||
|
||||
```xml
|
||||
<mujoco>
|
||||
@@ -58,57 +47,43 @@ deformation parameters. These parameters are passed as plugin config attributes:
|
||||
</mujoco>
|
||||
```
|
||||
|
||||
Note the following:
|
||||
请注意以下事项：
|
||||
|
||||
- The dimensionality of the sensor output is `nchannel * size_x *size_y`.
|
||||
- `objtype="site" objname="touch"` specify that the sensor is associated with a
|
||||
site, and the name of the specific site.
|
||||
- Field-of-view angles are always in degrees, disregarding the `<compiler>`
|
||||
"angle" directive.
|
||||
- 传感器输出的维度为 `nchannel * size_x * size_y`。
|
||||
- `objtype="site" objname="touch"` 指定传感器与 site 关联，以及关联的特定 site 名称。
|
||||
- 视场角始终以“度”为单位，不受 `<compiler>` 中的 "angle" 指令影响。
|
||||
|
||||
### Example model
|
||||
### 示例模型
|
||||
|
||||
<a href="https://youtu.be/0LOJ3WMnqeA" target="_blank">
|
||||
<img src="http://img.youtube.com/vi/0LOJ3WMnqeA/hqdefault.jpg" alt="Watch the video" width="560" height="315"/>
|
||||
<img src="http://img.youtube.com/vi/0LOJ3WMnqeA/hqdefault.jpg" alt="观看视频" width="560" height="315"/>
|
||||
</a>
|
||||
|
||||
See [touch_grid.xml](../../model/plugin/sensor/touch_grid.xml) to play with the model above.
|
||||
请查阅 [touch_grid.xml](../../model/plugin/sensor/touch_grid.xml) 来体验上述模型。
|
||||
|
||||
### Illustration of fields-of-view in spherical coordinates
|
||||
### 球坐标系下的视场角图示
|
||||
|
||||
<img src="images/30-30.png" style="width: 300px;"/>
|
||||
<img src="images/180-30.png" style="width: 300px;"/>
|
||||
<img src="images/180-90.png" style="width: 300px;"/>
|
||||
|
||||
### Illustration of foveal deformation
|
||||
### 中央凹形变图示
|
||||
|
||||
|
||||
|
||||
|
||||
### Illustration combining resolution, fields-of-view and foveal deformation
|
||||
### 结合分辨率、视场角和中央凹形变的综合图示
|
||||
|
||||
[](https://www.youtube.com/watch?v=YScjmR8LwQI)
|
||||
[](https://www.youtube.com/watch?v=YScjmR8LwQI)
|
||||
|
||||
## [Touch Stress](touch_stress.h)
|
||||
|
||||
This sensor is based on similar concepts and parametrization as the `touch_grid`,
|
||||
while overcoming some of its limitations. In particular, the `touch_grid` can
|
||||
only provide sparse information, depending on the number of contact points
|
||||
generated. The `touch_stress` sensor can instead generate a high-resolution
|
||||
touch image. In order to do this, it requires a signed distance function (SDF)
|
||||
of the object that is in contact with the sensor. This is handled internally for
|
||||
primitives or it must be declared explicitly in the model using SDF plugins.
|
||||
该传感器基于与 `touch_grid` 相似的概念和参数化设计，同时克服了它的一些局限性。具体而言，`touch_grid` 只能提供稀疏信息（取决于生成的接触点数量）。而 `touch_stress` 传感器可以生成高分辨率的触觉图像。为了实现这一点，它需要与传感器接触的物体的符号距离函数（Signed Distance Function, SDF）。对于基本几何图元（primitives），这会在内部自动处理；或者必须使用 SDF 插件在模型中显式声明。
|
||||
|
||||
There is one important difference with respect to the `touch_grid`: in this case,
|
||||
the force is computed in the local taxel frame and not in the frame of the sensor.
|
||||
This allows for a more intuitive interpretation of normal and tangential stresses,
|
||||
as shown in the images below.
|
||||
与 `touch_grid` 相比有一个重要区别：在此传感器中，力是在局部 taxel 坐标系下计算的，而不是在传感器坐标系下计算的。这使得法向应力和切向应力的物理意义更加直观，如下图所示。
|
||||
|
||||
Note that in this case, the absolute values of the stresses reported by the
|
||||
sensor are unrelated to the contact forces. They are purely based on geometric
|
||||
and kinematic considerations, i.e. the SDF for the normal stress and the sliding
|
||||
velocity for the tangential contributions.
|
||||
请注意，在这种情况下，传感器报告的应力绝对值与接触力无关。它们纯粹基于几何和运动学考量，即法向应力基于 SDF，切向分量基于滑动速度。
|
||||
|
||||
### Example model with analytical SDF
|
||||
### 解析 SDF 示例模型
|
||||
|
||||
```xml
|
||||
<extension>
|
||||
@@ -142,8 +117,8 @@ velocity for the tangential contributions.
|
||||
</sensor>
|
||||
</extension>
|
||||
```
|
||||
The images below show a static sphere over a gear described by an analytic SDF
|
||||
and the same sphere dragged along the x and y axes.
|
||||
|
||||
下图展示了由解析 SDF 描述的齿轮上方的一个静止球体，以及沿 x 轴和 y 轴拖动同一球体时的应力分布：
|
||||
|
||||
<img src="images/normal.png" style="width: 300px;"/>
|
||||
<img src="images/tangential1.png" style="width: 300px;"/>
|
||||
|
||||
+18
-42
@@ -1,4 +1,4 @@
|
||||
# MuJoCo Python Bindings
|
||||
# MuJoCo Python 绑定
|
||||
|
||||
[![PyPI Python Version][pypi-versions-badge]][pypi]
|
||||
[![PyPI version][pypi-badge]][pypi]
|
||||
@@ -7,67 +7,43 @@
|
||||
[pypi-badge]: https://badge.fury.io/py/mujoco.svg
|
||||
[pypi]: https://pypi.org/project/mujoco/
|
||||
|
||||
This package is the canonical Python bindings for the
|
||||
[MuJoCo physics engine](https://github.com/google-deepmind/mujoco).
|
||||
These bindings are developed and maintained by Google DeepMind, and is kept
|
||||
up-to-date with the latest developments in MuJoCo itself.
|
||||
本软件包是 [MuJoCo 物理引擎](https://github.com/google-deepmind/mujoco) 的官方规范 Python 绑定。这些绑定由 Google DeepMind 开发和维护，并与 MuJoCo 本身的最新进展保持同步。
|
||||
|
||||
The `mujoco` package provides direct access to raw MuJoCo C API functions,
|
||||
structs, constants, and enumerations. Structs are provided as Python classes,
|
||||
with Pythonic initialization and deletion semantics.
|
||||
`mujoco` 软件包提供了对底层 MuJoCo C API 函数、结构体、常量和枚举的直接访问。结构体以 Python 类的形式提供，具有符合 Python 习惯的对象初始化和销毁语义。
|
||||
|
||||
It is not the aim of this package to provide fully fledged
|
||||
scene/environment/game authoring API, as there are already a number of existing
|
||||
packages that do this well. However, this package does provide a number of
|
||||
lower-level components outside of MuJoCo itself that are likely to be useful to
|
||||
most users who access MuJoCo through Python. For example, the `egl`, `glfw`, and
|
||||
`osmesa` subpackages contain utilities for setting up OpenGL rendering contexts.
|
||||
本软件包的目的并不是提供功能完备的场景/环境/游戏创作 API，因为已有许多优秀的现有软件包做到了这一点。不过，本软件包确实提供了 MuJoCo 本身之外的一些底层组件，这些组件对大多数通过 Python 访问 MuJoCo 的用户很有用。例如，`egl`、`glfw` 和 `osmesa` 子包包含了用于设置 OpenGL 渲染上下文的实用工具。
|
||||
|
||||
## Installation
|
||||
## 安装
|
||||
|
||||
The recommended way to install this package is via [PyPI](https://pypi.org/project/mujoco/):
|
||||
推荐通过 [PyPI](https://pypi.org/project/mujoco/) 安装本软件包：
|
||||
|
||||
```sh
|
||||
pip install mujoco
|
||||
```
|
||||
|
||||
A copy of the MuJoCo library is provided as part of the package and does **not**
|
||||
need to be downloaded or installed separately.
|
||||
MuJoCo 库的副本已作为软件包的一部分提供，**无需**单独下载或安装。
|
||||
|
||||
### Source
|
||||
### 源码编译
|
||||
|
||||
**IMPORTANT:** Building from source is only necessary if you are modifying the
|
||||
Python bindings (or are trying to run on exceptionally old Linux systems).
|
||||
If that's not the case, then we recommend installing the prebuilt binaries from
|
||||
PyPI.
|
||||
**重要提示：** 仅当您需要修改 Python 绑定（或尝试在特别老旧的 Linux 系统上运行）时，才需要从源码构建。若非此类情况，我们建议直接安装来自 PyPI 的预编译二进制包。
|
||||
|
||||
If you need to build the Python bindings from source, please consult
|
||||
[the documentation](https://mujoco.readthedocs.io/en/latest/python.html#building-from-source).
|
||||
如果您需要从源码构建 Python 绑定，请查阅[官方文档](https://mujoco.readthedocs.io/en/latest/python.html#building-from-source)。
|
||||
|
||||
## Usage
|
||||
## 使用说明
|
||||
|
||||
Once installed, the package can be imported via `import mujoco`. Please consult
|
||||
our [documentation](https://mujoco.readthedocs.io/en/stable/python.html) for
|
||||
further detail on the package's API.
|
||||
安装完成后，可以通过 `import mujoco` 导入该包。有关该包 API 的更多详细信息，请参阅我们的[官方文档](https://mujoco.readthedocs.io/en/stable/python.html)。
|
||||
|
||||
We recommend going through the tutorial notebook which covers the basics of
|
||||
MuJoCo using Python:
|
||||
我们建议阅读教程 Notebook，其中介绍了使用 Python 操作 MuJoCo 的基础知识：
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/tutorial.ipynb)
|
||||
|
||||
## Versioning
|
||||
## 版本规范
|
||||
|
||||
The `major.minor.micro` portion of the version number matches the version of
|
||||
MuJoCo that the bindings provide. Optionally, if we release updates to the
|
||||
Python bindings themselves that target the same version of MuJoCo, a `.postN`
|
||||
suffix is added, for example `2.1.2.post2` represents the second update to the
|
||||
bindings for MuJoCo 2.1.2.
|
||||
版本号的 `major.minor.micro` 部分与绑定所对应的 MuJoCo 版本完全一致。可选地，如果我们针对同一版本的 MuJoCo 发布了 Python 绑定自身的更新，则会添加 `.postN` 后缀，例如 `2.1.2.post2` 表示针对 MuJoCo 2.1.2 的绑定的第二次更新。
|
||||
|
||||
## License and Disclaimer
|
||||
## 开源许可证与免责声明
|
||||
|
||||
Copyright 2022 DeepMind Technologies Limited
|
||||
|
||||
MuJoCo and its Python bindings are licensed under the Apache License,
|
||||
Version 2.0. You may obtain a copy of the License at
|
||||
https://www.apache.org/licenses/LICENSE-2.0.
|
||||
MuJoCo 及其 Python 绑定基于 Apache 许可证 2.0 版（Apache License, Version 2.0）授权。您可在 https://www.apache.org/licenses/LICENSE-2.0 获取许可证副本。
|
||||
|
||||
This is not an officially supported Google product.
|
||||
本项目不是 Google 官方支持的产品。
|
||||
|
||||
@@ -1,73 +1,55 @@
|
||||
# System Identification Toolbox
|
||||
# 系统辨识工具箱（System Identification Toolbox）
|
||||
|
||||
[](https://colab.research.google.com/github/google-deepmind/mujoco/blob/main/python/mujoco/sysid/sysid.ipynb)
|
||||
|
||||
Given a MuJoCo model and recorded sensor data, find parameters
|
||||
that make simulation match reality. By default, the library uses
|
||||
nonlinear least-squares with box constraints to minimize the difference
|
||||
between measured and simulated (predicted) outputs. Residuals
|
||||
can be modified by static or optimized parameters, such as
|
||||
weights and time-delays.
|
||||
给定 MuJoCo 模型和采集到的传感器数据，寻找能够使仿真结果与真实物理系统相吻合的模型参数。默认情况下，该库使用带有边界约束（box constraints）的非线性最小二乘法来最小化测量输出与仿真（预测）输出之间的差异。残差可以通过静态或待优化的参数（例如权重和时间延迟）进行调整。
|
||||
|
||||
The optimizer uses Gauss-Newton with finite-difference Jacobians. Each
|
||||
parameter perturbation requires an independent simulation rollout. All
|
||||
of them execute in a single batched call to `mujoco.rollout`, parallelized
|
||||
across threads.
|
||||
优化器采用基于有限差分雅可比矩阵的高斯-牛顿法（Gauss-Newton）。每次参数摄动都需要一次独立的仿真 rollout（推演）。所有 rollout 均在对 `mujoco.rollout` 的单次批处理调用中跨多线程并行执行。
|
||||
|
||||
## Pipeline
|
||||
## 工作流程（Pipeline）
|
||||
|
||||
**You provide:**
|
||||
- One or more `ModelSequences` each bundling a single `MjSpec` with one or
|
||||
more sequences of measured data. All will be optimized jointly.
|
||||
- A `ParameterDict` defining differentiable `Parameter`s with bounds.
|
||||
- Callbacks to apply `Parameter`s to an `MjSpec` (individually or jointly)
|
||||
- (optional) Functions (`build_model`, `custom_rollout`, `modify_residual`)
|
||||
that override the default residual function behavior.
|
||||
**用户提供：**
|
||||
- 一个或多个 `ModelSequences`，每个序列将单个 `MjSpec` 与一个或多个测量数据序列打包在一起。所有序列将被联合优化。
|
||||
- 一个 `ParameterDict`，用于定义带有上下界的可微参数 `Parameter`。
|
||||
- 用于将 `Parameter` 应用到 `MjSpec` 上的回调函数（可单独或联合应用）。
|
||||
- （可选）用于覆盖默认残差函数行为的自定义函数（`build_model`、`custom_rollout`、`modify_residual`）。
|
||||
|
||||
**The framework:**
|
||||
- Composes user code into a residual function (`build_residual_fn`).
|
||||
- Optimizes parameters via batched parallel rollouts (`optimize`).
|
||||
- Saves results and generates an HTML report (`save_results`, `default_report`).
|
||||
**框架执行：**
|
||||
- 将用户代码组合为残差函数（`build_residual_fn`）。
|
||||
- 通过批量并行 rollout 优化参数（`optimize`）。
|
||||
- 保存结果并生成交互式 HTML 报告（`save_results`、`default_report`）。
|
||||
|
||||
## What Can You Identify?
|
||||
## 可以辨识哪些参数？
|
||||
|
||||
You can optimize any parameter that differentiably modifies the final
|
||||
residuals. Common use cases include:
|
||||
您可以优化任何能够以可微方式修改最终残差的参数。常见用例包括：
|
||||
|
||||
**Physics parameters** settable on `MjSpec`. Most parameters in MjSpec
|
||||
can be easily set directly by user-provided callbacks:
|
||||
在 `MjSpec` 上可设置的**物理参数**。MjSpec 中的大多数参数可以通过用户提供的回调函数直接轻松设置：
|
||||
|
||||
| Target | Approach |
|
||||
| 辨识目标 | 对应方法 |
|
||||
|---|---|
|
||||
| Contact sliding friction | `spec.pair("cp").friction[0] = p.value[0]` |
|
||||
| Joint damping | `spec.joint("j1").damping = p.value[0]` |
|
||||
| 接触滑动摩擦力 | `spec.pair("cp").friction[0] = p.value[0]` |
|
||||
| 关节阻尼 | `spec.joint("j1").damping = p.value[0]` |
|
||||
|
||||
Convenience functions are provided for common system identification
|
||||
parameterizations that cannot be trivially applied to an MjSpec:
|
||||
对于无法直接简单应用到 MjSpec 的常见系统辨识参数化方式，该库提供了便捷函数：
|
||||
|
||||
| Target | Approach |
|
||||
| 辨识目标 | 对应方法 |
|
||||
|---|---|
|
||||
| Body mass | `body_inertia_param(..., InertiaType.Mass)` |
|
||||
| Body mass + center of mass | `body_inertia_param(..., InertiaType.MassIpos)` |
|
||||
| Full inertia (10-D) | `body_inertia_param(..., InertiaType.Pseudo)` |
|
||||
| Actuator P/D gains | `apply_pdgain(spec, "act1", p.value)` |
|
||||
| 刚体质量 | `body_inertia_param(..., InertiaType.Mass)` |
|
||||
| 刚体质量 + 质心位置 | `body_inertia_param(..., InertiaType.MassIpos)` |
|
||||
| 完整惯量（10 维） | `body_inertia_param(..., InertiaType.Pseudo)` |
|
||||
| 执行器 P/D 增益 | `apply_pdgain(spec, "act1", p.value)` |
|
||||
|
||||
Full inertia uses the pseudo-inertia Cholesky parameterization
|
||||
([Rucker & Wensing 2022](https://ieeexplore.ieee.org/document/9690029)),
|
||||
guaranteeing physical consistency without singularities.
|
||||
完整惯量采用伪惯量 Cholesky 参数化（Pseudo-inertia Cholesky Parameterization，[Rucker & Wensing 2022](https://ieeexplore.ieee.org/document/9690029)），保证物理一致性且不存在奇异点。
|
||||
|
||||
**Measurement parameters** such as sensor delays, gains, and biases are
|
||||
properties of the measurement system, not the physics model. The library
|
||||
provides utilities for applying these corrections to the residual after
|
||||
rollout. They are functionally complete but their API is not yet final.
|
||||
诸如传感器延迟、增益和偏差等**测量参数**属于测量系统的属性，而非物理模型本身的属性。该库提供了在 rollout 之后将这些校正应用于残差的实用工具。这些功能已完备，但其 API 尚未最终定型。
|
||||
|
||||
## Example
|
||||
## 示例
|
||||
|
||||
```python
|
||||
import mujoco
|
||||
from mujoco import sysid
|
||||
|
||||
# 1. Load model and define parameters.
|
||||
# 1. 加载模型并定义待辨识参数。
|
||||
spec = mujoco.MjSpec.from_file("robot.xml")
|
||||
model = spec.compile()
|
||||
|
||||
@@ -79,18 +61,17 @@ params.add(sysid.Parameter(
|
||||
"link1_mass", nominal=2.0, min_value=0.5, max_value=5.0,
|
||||
modifier=set_link1_mass))
|
||||
|
||||
# 2. Load and package measured data.
|
||||
# arrays assumed to be in MuJoCo order, otherwise pass names argument
|
||||
# 2. 加载并封装实测数据。
|
||||
# 数组默认采用 MuJoCo 顺序，否则请传入 names 参数
|
||||
control = sysid.TimeSeries.from_control_names(times, ctrl_array, model)
|
||||
measureddata = sysid.TimeSeries.from_names(times, measurement_array, model)
|
||||
initial_state = sysid.create_initial_state(model, qpos_0, qvel_0)
|
||||
ms = sysid.ModelSequences("robot", spec, "traj_1", initial_state, control, measureddata)
|
||||
|
||||
# 3. Build residual, optimize, save.
|
||||
# 3. 构建残差函数、执行优化并保存结果。
|
||||
residual_fn = sysid.build_residual_fn(models_sequences=[ms])
|
||||
opt_params, opt_result = sysid.optimize(initial_params=params, residual_fn=residual_fn)
|
||||
sysid.save_results("results/", [ms], params, opt_params, opt_result, residual_fn)
|
||||
```
|
||||
|
||||
`default_report` generates an interactive HTML report with videos, measurement comparisons,
|
||||
parameter tables, and confidence intervals.
|
||||
`default_report` 可生成包含视频、测量对比图、参数表格以及置信区间的交互式 HTML 报告。
|
||||
|
||||
@@ -1,3 +1,3 @@
|
||||
# USD exporter module
|
||||
# USD 导出器模块
|
||||
|
||||
Please see [documentation](https://mujoco.readthedocs.io/en/stable/python.html) for details.
|
||||
详情请参阅[官方文档](https://mujoco.readthedocs.io/en/stable/python.html)。
|
||||
|
||||
+3
-8
@@ -1,12 +1,7 @@
|
||||
# Simulate App
|
||||
# Simulate 应用程序
|
||||
|
||||
`simulate` is a fully-featured interactive application for MuJoCo. It opens an
|
||||
OpenGL window using the platform-independent GLFW library, and renders the
|
||||
simulation state in it. There is built-in help, simulation statistics, profiler,
|
||||
sensor data plots. The model file can be specified as a command-line argument,
|
||||
or loaded at runtime using drag-and-drop functionality. Below is a
|
||||
screen-capture of simulate in action:
|
||||
`simulate` 是 MuJoCo 的全功能交互式应用程序。它使用跨平台的 GLFW 库打开 OpenGL 窗口，并在其中渲染仿真状态。内置了帮助菜单、仿真统计数据、性能剖析器（profiler）以及传感器数据曲线图。模型文件可以通过命令行参数指定，也可以在运行时通过拖拽文件直接加载。下面是 simulate 运行时的屏幕录像：
|
||||
|
||||
<a href="https://youtu.be/0ORsj_E17B0" target="_blank">
|
||||
<img src="http://img.youtube.com/vi/0ORsj_E17B0/hqdefault.jpg" alt="Watch the video" width="560" height="315"/>
|
||||
<img src="http://img.youtube.com/vi/0ORsj_E17B0/hqdefault.jpg" alt="观看视频" width="560" height="315"/>
|
||||
</a>
|
||||
|
||||
@@ -1,26 +1,21 @@
|
||||
# MuJoCo Studio
|
||||
|
||||
MuJoCo Studio is the next iteration of the [simulate](../../../simulate)
|
||||
application. The UI has been reimplemented using [Dear ImGui](https://github.com/ocornut/imgui)
|
||||
and the default renderer has been switched to Filament. The application is
|
||||
still WIP, see the [Future Work](#future-work) section for details.
|
||||
MuJoCo Studio 是 [simulate](../../../simulate) 应用程序的下一代演进版本。UI 界面已使用 [Dear ImGui](https://github.com/ocornut/imgui) 重新实现，默认渲染器已切换为 Filament。该应用程序目前仍处于开发中（WIP），详情请参阅[未来工作](#未来工作)部分。
|
||||
|
||||
## Usage
|
||||
## 使用说明
|
||||
|
||||
Configure and build MuJoCo Studio by running this command from the top-level
|
||||
directory. Then follow the printed instructions to run the executable.
|
||||
在项目顶级根目录下运行以下命令来配置并构建 MuJoCo Studio，然后按照打印的提示运行可执行文件：
|
||||
|
||||
```
|
||||
```bash
|
||||
bash build.sh
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> For now [`build.sh`](build.sh) script works on windows in a git bash shell.
|
||||
> 目前 [`build.sh`](build.sh) 脚本在 Windows 系统的 Git Bash 环境下可用。
|
||||
|
||||
To keep Studio build artifacts separate from other MuJoCo builds, you can also
|
||||
configure an isolated build directory manually:
|
||||
为了将 Studio 构建产物与其他 MuJoCo 构建分开，您也可以手动配置一个隔离的构建目录：
|
||||
|
||||
```
|
||||
```bash
|
||||
cmake -B build-studio \
|
||||
-DCMAKE_BUILD_TYPE=Release \
|
||||
-DUSE_STATIC_LIBCXX=OFF \
|
||||
@@ -38,52 +33,37 @@ cmake -B build-studio \
|
||||
cmake --build build-studio --config Release --target mujoco_studio --parallel
|
||||
```
|
||||
|
||||
Run `mujoco_studio` from the build output directory so it can find the copied
|
||||
font and Filament assets:
|
||||
从构建输出目录运行 `mujoco_studio`，以便它能够找到复制的字体和 Filament 资产：
|
||||
|
||||
```
|
||||
```bash
|
||||
cd build-studio/bin
|
||||
./mujoco_studio --gfx=opengl
|
||||
```
|
||||
|
||||
On macOS, Studio defaults to Filament OpenGL. The OpenGL implementation may be
|
||||
provided by Apple's Metal-backed OpenGL layer, so runtime logs can mention both
|
||||
OpenGL and Metal/Apple GPU details.
|
||||
在 macOS 上，Studio 默认使用 Filament OpenGL。OpenGL 实现可能由 Apple 基于 Metal 的 OpenGL 层提供，因此运行时日志可能会同时提及 OpenGL 和 Metal/Apple GPU 详细信息。
|
||||
|
||||
### Troubleshooting
|
||||
### 故障排除（Troubleshooting）
|
||||
|
||||
If configure fails while resolving Filament dependencies, check whether CMake is
|
||||
finding package-manager CMake configs from environments such as Anaconda. In
|
||||
particular, an unrelated `abslConfig.cmake` can conflict with MuJoCo's fetched
|
||||
Abseil targets. Remove that prefix from `CMAKE_PREFIX_PATH`, or configure with
|
||||
`CMAKE_IGNORE_PREFIX_PATH` pointing at the conflicting environment prefix.
|
||||
如果配置在解析 Filament 依赖项时失败，请检查 CMake 是否找到了来自 Anaconda 等环境的包管理器 CMake 配置文件。特别是，无关的 `abslConfig.cmake` 可能会与 MuJoCo 拉取的 Abseil 目标发生冲突。请从 `CMAKE_PREFIX_PATH` 中移除该前缀，或在配置时将 `CMAKE_IGNORE_PREFIX_PATH` 指向冲突的环境前缀。
|
||||
|
||||
## Development
|
||||
## 开发指南
|
||||
|
||||
The [`build.sh`](build.sh) script is intended to get you up and running quickly.
|
||||
If you intend to develop the application you may prefer to work from an IDE:
|
||||
[`build.sh`](build.sh) 脚本旨在让您快速上手运行。如果您打算开发该应用程序，可能更倾向于在 IDE 中工作：
|
||||
|
||||
* [Clion](https://www.jetbrains.com/clion/). You should be able to set this up
|
||||
to work with the cmake files we provide.
|
||||
* [CLion](https://www.jetbrains.com/clion/)：您可以将其配置为与我们提供的 CMake 文件配合工作。
|
||||
|
||||
* [VSCode](https://code.visualstudio.com/). We have found that Microsoft's
|
||||
[CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools)
|
||||
extension works well.
|
||||
* [VSCode](https://code.visualstudio.com/)：我们发现微软的 [CMake Tools](https://marketplace.visualstudio.com/items?itemName=ms-vscode.cmake-tools) 扩展效果很好。
|
||||
|
||||
* [Visual Studio](https://visualstudio.microsoft.com/). Follow these
|
||||
[instructions](https://learn.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-170).
|
||||
* [Visual Studio](https://visualstudio.microsoft.com/)：请遵循这些[操作说明](https://learn.microsoft.com/en-us/cpp/build/cmake-projects-in-visual-studio?view=msvc-170)。
|
||||
|
||||
## Known Bugs
|
||||
## 已知问题
|
||||
|
||||
* MuJoCo Studio does not yet work using Wayland on Linux, use X11 instead.
|
||||
* MuJoCo Studio 目前在 Linux 的 Wayland 下尚无法正常工作，请改用 X11。
|
||||
|
||||
## Future Work
|
||||
## 未来工作
|
||||
|
||||
1. **Stability and Robustness**. We need user feedback to find and fix bugs.
|
||||
1. **稳定性与健壮性**：我们需要用户反馈来发现和修复 Bug。
|
||||
|
||||
1. **UI/UX improvements**. We have ported the simulate UI to make it easier to
|
||||
users to switch. We will be making further changes to make use of the
|
||||
flexibility offered by Dear ImGui ([examples](https://github.com/ocornut/imgui/issues/8942)).
|
||||
2. **UI/UX 改进**：我们移植了 simulate UI 以方便用户过渡切换。我们将进一步修改以充分利用 Dear ImGui 提供的灵活性（[示例参考](https://github.com/ocornut/imgui/issues/8942)）。
|
||||
|
||||
1. **Python integration**. As with simulate, we would like to make Studio usable
|
||||
via Python.
|
||||
3. **Python 集成**：与 simulate 一样，我们希望让 Studio 可以通过 Python 调用和使用。
|
||||
|
||||
@@ -1,15 +1,7 @@
|
||||
# mjcPhysics -- MuJoCo Physics Schemas for OpenUSD
|
||||
# mjcPhysics -- OpenUSD 的 MuJoCo 物理模式定义（Schemas）
|
||||
|
||||
This directory contains the USD schema definition and accompanying code for
|
||||
`mjcPhysics`. These schemas allow for detailed specification of a MuJoCo
|
||||
simulation environment directly within USD. The aim is not to replace
|
||||
UsdPhysics, but to extend existing concepts and create new types only where is
|
||||
necessary.
|
||||
本目录包含 `mjcPhysics` 的 USD Schema（模式定义）及其附带代码。这些 Schema 允许直接在 USD 内部详细指定 MuJoCo 仿真环境。其目标不是取代 UsdPhysics，而是在现有概念的基础上进行扩展，仅在必要时创建新类型。
|
||||
|
||||
The schemas can be used codeless, or can be built with its C++ bindings. We've
|
||||
pre-generated the code here via usdGenSchema for internal MuJoCo usage, but it
|
||||
should also work outside of MuJoCo in apps that support USD natively such as
|
||||
Omniverse, Houdini, and Maya.
|
||||
这些 Schema 可以无代码使用（codeless），也可以与其 C++ 绑定一起构建。我们已经在此处通过 usdGenSchema 预生成了代码供 MuJoCo 内部使用，但它也应该能在原生支持 USD 的外部应用程序（如 Omniverse、Houdini 和 Maya）中正常工作。
|
||||
|
||||
For more detailed information please refer to
|
||||
[our OpenUSD documentation](https://mujoco.readthedocs.io/en/latest/OpenUSD/index.html)
|
||||
有关更详细的信息，请参阅[我们的 OpenUSD 文档](https://mujoco.readthedocs.io/en/latest/OpenUSD/index.html)。
|
||||
|
||||
+2
-7
@@ -1,8 +1,3 @@
|
||||
# Unity Plug-in
|
||||
# Unity 插件
|
||||
|
||||
The MuJoCo Unity plug-in allows the Unity Editor and runtime to use the MuJoCo
|
||||
physics engine. Users can import MJCF files and edit the models in the Editor.
|
||||
The plug-in relies on Unity for most aspects -- assets, game logic, simulation
|
||||
time -- but uses MuJoCo to determine how objects move, giving the designer
|
||||
access to MuJoCo's full API. See documentation and installation instructions
|
||||
[here](https://mujoco.readthedocs.io/en/latest/unity.html).
|
||||
MuJoCo Unity 插件允许 Unity 编辑器和运行时使用 MuJoCo 物理引擎。用户可以导入 MJCF 文件并在编辑器中编辑模型。该插件在大部分方面依赖 Unity（资产、游戏逻辑、仿真时间），但使用 MuJoCo 来计算物体的运动规律，使设计者能够访问 MuJoCo 的全部 API。文档和安装说明请参阅[此处](https://mujoco.readthedocs.io/en/latest/unity.html)。
|
||||
|
||||
+139
-275
@@ -1,80 +1,55 @@
|
||||
# MuJoCo JavaScript Bindings
|
||||
# MuJoCo JavaScript 绑定
|
||||
|
||||
These are the canonical JavaScript and TypeScript bindings for the MuJoCo
|
||||
physics engine.
|
||||
这是 [MuJoCo 物理引擎](https://github.com/google-deepmind/mujoco) 的官方规范 JavaScript 和 TypeScript 绑定。
|
||||
|
||||
This package provides a high-level API that allows you to interact with the core
|
||||
MuJoCo engine compiled into a high-performance WebAssembly (WASM) module. These
|
||||
bindings are developed and maintained by Google DeepMind and are always up to
|
||||
date with the latest developments in MuJoCo. For brevity, the documentation
|
||||
below will often refer to “JavaScript” but the concepts apply equally to
|
||||
TypeScript.
|
||||
本软件包提供了一个高级 API，使您能够与编译为高性能 WebAssembly (WASM) 模块的 MuJoCo 核心引擎进行交互。这些绑定由 Google DeepMind 开发和维护，并始终与 MuJoCo 的最新进展保持同步。为简明起见，下文中的文档通常称为“JavaScript”，但相关概念同样完全适用于 TypeScript。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> _These bindings are still a WIP. For details, see the [Future Work](#future-work)
|
||||
> section. Also note that development has primarily taken place on Linux using
|
||||
> Google Chrome. If you're working on a different OS or browser, you may
|
||||
> encounter some rough edges. We have successfully tested the bindings on MacOS
|
||||
> in CI but as of November 13th 2025, Windows support remains experimental
|
||||
> (installation succeeded on one Windows 11 machine but failed on others)._
|
||||
> _这些绑定仍处于开发阶段（WIP）。详情请参阅[未来工作](#未来工作)部分。另请注意，开发主要是在 Linux 上使用 Google Chrome 进行的。如果您在其他操作系统或浏览器上开发，可能会遇到一些粗糙边缘。我们已在 CI 中成功在 macOS 上测试了绑定，但截至 2025 年 11 月 13 日，Windows 支持仍处于实验性阶段（在某台 Windows 11 设备上安装成功，但在其他设备上失败）。_
|
||||
|
||||
## Installation
|
||||
## 安装
|
||||
|
||||
The easiest way to use the MuJoCo JavaScript bindings is to install the
|
||||
`@mujoco/mujoco` package from npm:
|
||||
使用 MuJoCo JavaScript 绑定最简单的方法是从 npm 安装 `@mujoco/mujoco` 软件包：
|
||||
|
||||
```sh
|
||||
npm install @mujoco/mujoco
|
||||
```
|
||||
|
||||
This package is ESM (`type: module`) and includes the pre-compiled WebAssembly
|
||||
module, JavaScript bindings, and TypeScript declarations. Ensure your bundler or
|
||||
dev server serves the `.wasm` asset at runtime.
|
||||
该软件包采用 ESM 模块规范（`type: module`），包含预编译的 WebAssembly 模块、JavaScript 绑定和 TypeScript 类型声明。请确保您的打包工具（bundler）或开发服务器在运行时能够正确提供 `.wasm` 静态资源服务。
|
||||
|
||||
### Threading Models
|
||||
### 线程模型（Threading Models）
|
||||
|
||||
The `@mujoco/mujoco` package includes two distinct builds of the engine to
|
||||
support different browser environments and performance needs.
|
||||
`@mujoco/mujoco` 软件包包含两个不同的引擎构建版本，以支持不同的浏览器环境和性能需求。
|
||||
|
||||
#### 1. Single-Threaded (Default)
|
||||
#### 1. 单线程（默认）
|
||||
|
||||
The standard single-threaded version is located at the root of the package. It
|
||||
is compatible with all modern browsers and does not require special security
|
||||
headers.
|
||||
标准的单线程版本位于软件包的根目录。它兼容所有现代浏览器，无需特殊的安全响应头配置。
|
||||
```typescript
|
||||
import loadMujoco from '@mujoco/mujoco';
|
||||
```
|
||||
|
||||
#### 2. Multi-Threaded (MT)
|
||||
#### 2. 多线程（MT）
|
||||
|
||||
The multi-threaded version is located in the `/mt` subfolder. It utilizes Web
|
||||
Workers and `SharedArrayBuffer` to parallelize physics computations.
|
||||
```typeScript
|
||||
多线程版本位于 `/mt` 子目录中。它利用 Web Workers 和 `SharedArrayBuffer` 来并行化物理计算。
|
||||
```typescript
|
||||
import loadMujoco from '@mujoco/mujoco/mt';
|
||||
```
|
||||
|
||||
> [!NOTE]
|
||||
> Due to the use of `SharedArrayBuffer`, browsers require Cross-Origin Isolation
|
||||
> to enable multi-threading. Your web server must send the following HTTP
|
||||
> headers:
|
||||
> 由于使用了 `SharedArrayBuffer`，浏览器需要配置跨域隔离（Cross-Origin Isolation）才能启用多线程。您的 Web 服务器必须发送以下 HTTP 响应头：
|
||||
> - `Cross-Origin-Opener-Policy: same-origin`
|
||||
> - `Cross-Origin-Embedder-Policy: require-corp`
|
||||
>
|
||||
> If these headers are missing, the module will fail to initialize.
|
||||
> 如果缺少这些响应头，模块将无法完成初始化。
|
||||
|
||||
## Build from source
|
||||
## 从源码构建
|
||||
|
||||
### Prerequisites
|
||||
### 前置依赖
|
||||
|
||||
> [!NOTE]
|
||||
> Run all the commands in this README from the top-level directory.
|
||||
> 请在项目顶级根目录下运行本 README 中的所有命令。
|
||||
|
||||
- To compile the [`bindings.cc`](codegen/generated/bindings.cc) file, which
|
||||
generates the `.wasm` WebAssembly file, `.js` JavaScript import, and `.d.ts`
|
||||
TypeScript declaration file, you will need Emscripten SDK version `4.0.10`.
|
||||
Later versions may work but are untested. To set up the SDK, do the
|
||||
following, you can run this anywhere but the rest of the commands in this
|
||||
README only work in the shell where you source the `emsdk_env.sh` script.
|
||||
- 要编译 [`bindings.cc`](codegen/generated/bindings.cc) 文件（用于生成 `.wasm` WebAssembly 文件、`.js` JavaScript 导入文件和 `.d.ts` TypeScript 声明文件），您需要安装 Emscripten SDK `4.0.10` 版本。更新的版本可能可用但未经充分测试。要配置 SDK，请执行以下命令（您可以在任何位置运行安装，但本 README 中的后续命令仅在执行了 `source ./emsdk/emsdk_env.sh` 的 Shell 中生效）：
|
||||
|
||||
```sh
|
||||
git clone https://github.com/emscripten-core/emsdk.git
|
||||
@@ -83,22 +58,14 @@ import loadMujoco from '@mujoco/mujoco/mt';
|
||||
source ./emsdk/emsdk_env.sh
|
||||
```
|
||||
|
||||
- To easily run the JavaScript tests and the demo application, `node` and `npm`
|
||||
are required. We recommend managing these using
|
||||
[nvm](https://github.com/nvm-sh/nvm). There are also various JavaScript
|
||||
dependencies needed for the tests, demo, and bindings build process. These
|
||||
dependencies are expected to be located in the `wasm` folder. To install
|
||||
them and ensure they can be found by later commands, run the following:
|
||||
- 要轻松运行 JavaScript 测试和演示应用，需要安装 `node` 和 `npm`。我们建议使用 [nvm](https://github.com/nvm-sh/nvm) 进行版本管理。此外，测试、演示和绑定构建过程还需要一些 JavaScript 依赖项。这些依赖位于 `wasm` 文件夹中。要安装它们并确保后续命令可以找到相关工具，请运行：
|
||||
|
||||
```sh
|
||||
npm install --prefix ./wasm
|
||||
export PATH="$(pwd)/wasm/node_modules/.bin:$PATH"
|
||||
```
|
||||
|
||||
- To modify the bindings `python3` is required because the [`bindings.cc`](codegen/generated/bindings.cc)
|
||||
file is generated by a Python script. To run the bindings generator tests,
|
||||
`absl` is required and `pytest` will be helpful. Set up a Python environment
|
||||
with these dependencies as follows:
|
||||
- 要修改绑定，需要安装 `python3`，因为 [`bindings.cc`](codegen/generated/bindings.cc) 文件是由 Python 脚本生成的。要运行绑定生成器测试，需要 `absl`，同时 `pytest` 也很有帮助。配置包含这些依赖的 Python 虚拟环境：
|
||||
|
||||
```sh
|
||||
python3 -m venv .venv
|
||||
@@ -107,254 +74,199 @@ import loadMujoco from '@mujoco/mujoco/mt';
|
||||
```
|
||||
|
||||
> [!TIP]
|
||||
> _Emscripten is well-documented. We recommend reading the sections covering the
|
||||
> [Emscripten Compiler Settings](https://emscripten.org/docs/tools_reference/settings_reference.html),
|
||||
> the [Emscripten SDK](https://emscripten.org/docs/tools_reference/emsdk.html),
|
||||
> and the [Embind](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html)
|
||||
> library. To understand the limitations and caveats related to using the
|
||||
> browser as a platform, see the
|
||||
> [Porting](https://emscripten.org/docs/porting/index.html#porting) section._
|
||||
> _Emscripten 文档非常详尽。建议阅读涵盖 [Emscripten 编译器设置](https://emscripten.org/docs/tools_reference/settings_reference.html)、[Emscripten SDK](https://emscripten.org/docs/tools_reference/emsdk.html) 以及 [Embind](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html) 库的章节。若要了解将浏览器作为运行平台的相关限制和注意事项，请参阅 [Porting（移植）](https://emscripten.org/docs/porting/index.html#porting) 章节。_
|
||||
|
||||
The [`bindings.cc`](codegen/generated/bindings.cc) file is compiled to generate
|
||||
the `.wasm` WebAssembly file, `.js` JavaScript import, and `.d.ts` TypeScript
|
||||
declaration file. These are the files you'll use to call MuJoCo from JavaScript.
|
||||
To generate them ensure the npm and Emscripten SDK prerequisites are set up and
|
||||
then run the following:
|
||||
编译 [`bindings.cc`](codegen/generated/bindings.cc) 文件将生成 `.wasm` WebAssembly 文件、`.js` JavaScript 导入文件以及 `.d.ts` TypeScript 声明文件。这些文件将用于在 JavaScript 中调用 MuJoCo。要生成它们，请确保已配置好 npm 和 Emscripten SDK 前置环境，然后运行以下命令：
|
||||
|
||||
```sh
|
||||
emcmake cmake -B build && cmake --build build
|
||||
```
|
||||
|
||||
This command will generate the following folders under the project root:
|
||||
该命令将在项目根目录下生成以下文件夹：
|
||||
|
||||
- `build`: contains MuJoCo compiled using Emscripten.
|
||||
- `wasm/dist`: contains the WebAssembly module, `.js` and `.d.ts` files.
|
||||
- `build`：包含使用 Emscripten 编译的 MuJoCo。
|
||||
- `wasm/dist`：包含 WebAssembly 模块、`.js` 和 `.d.ts` 文件。
|
||||
|
||||
The assets inside those folders are compiled and prepared to run as
|
||||
single-threaded. If you need to operate with a multi-threaded version of the
|
||||
module make sure to pass the `-DMUJOCO_WASM_THREADS=ON` flag like:
|
||||
这些文件夹内的资源默认编译并配置为单线程运行。如果需要使用多线程版本的模块，请传递 `-DMUJOCO_WASM_THREADS=ON` 标志：
|
||||
|
||||
```sh
|
||||
emcmake cmake -B build -DMUJOCO_WASM_THREADS=ON && cmake --build build
|
||||
```
|
||||
|
||||
### Example Application
|
||||
### 示例应用程序
|
||||
|
||||
After generating the bindings you will be ready to write web applications using
|
||||
MuJoCo. We have provided a basic web application that uses Three.js to render a
|
||||
simple simulation, to try it run this command:
|
||||
生成绑定后，您就可以开始编写使用 MuJoCo 的 Web 应用程序了。我们提供了一个使用 Three.js 渲染简单仿真的基础 Web 应用，运行以下命令体验：
|
||||
|
||||
```sh
|
||||
npm run dev:demo --prefix ./wasm
|
||||
```
|
||||
|
||||
You may prefer to write your entire app in C++ and compile it using Emscripten.
|
||||
If you do this, you won’t need to use these bindings, since you’ll be writing
|
||||
minimal JavaScript, and the granularity of these bindings may be inappropriate
|
||||
(e.g., you might want to call multiple MuJoCo functions in the C++ callback
|
||||
invoked by `requestAnimationFrame`).
|
||||
您也可以选择完全用 C++ 编写整个应用并使用 Emscripten 编译。如果采用这种方式，您将不需要使用这些绑定，因为您只需编写极少量的 JavaScript，而且这些绑定的粒度可能不太合适（例如，您可能希望在 `requestAnimationFrame` 触发的 C++ 回调中调用多个 MuJoCo 函数）。
|
||||
|
||||
We have also found that a hybrid approach can be helpful, as it is often more
|
||||
convenient to work with browser APIs directly in JavaScript. If you choose to
|
||||
write your application in C++ and compile it using Emscripten, you may want to
|
||||
copy a subset of the `EMSCRIPTEN_BINDINGS` from `bindings.cc` into your
|
||||
application’s source file.
|
||||
我们还发现混合架构非常实用，因为直接在 JavaScript 中操作浏览器 API 通常更方便。如果您选择用 C++ 编写应用程序并使用 Emscripten 编译，您可以将 `bindings.cc` 中 `EMSCRIPTEN_BINDINGS` 的子集复制到您的应用程序源文件中。
|
||||
|
||||
## User Guide
|
||||
### Named Access
|
||||
## 用户指南
|
||||
|
||||
The bindings support named access methods, similar to the Python bindings,
|
||||
allowing convenient access to model and data elements by name or index. For
|
||||
example, you can access a geometry by name using `model.geom('mygeom')` or a
|
||||
joint using `data.jnt('myjoint')`.
|
||||
### 按名称访问（Named Access）
|
||||
|
||||
For more details and examples of how to use named access, please refer to the [named access tests](tests/bindings_test.ts#L1876-L2378) and [documentation](https://mujoco.readthedocs.io/en/stable/python.html#named-access).
|
||||
绑定支持按名称访问方法（与 Python 绑定类似），允许通过名称或索引便捷地访问模型和数据元素。例如，可以通过 `model.geom('mygeom')` 按名称访问几何体，或通过 `data.jnt('myjoint')` 访问关节。
|
||||
|
||||
### Memory Management
|
||||
Embind-wrapped C++ object handles created or returned into JavaScript live on
|
||||
the WebAssembly heap and are **not** garbage-collected by the JS runtime.
|
||||
有关如何使用按名称访问的更多详细信息和示例，请参阅[按名称访问测试](tests/bindings_test.ts#L1876-L2378)以及[官方文档](https://mujoco.readthedocs.io/en/stable/python.html#named-access)。
|
||||
|
||||
Any heap-allocated C++ object exposed to JS (e.g. via `new Module.MyClass(...)`
|
||||
or returned as a pointer/reference from a binding) must be explicitly freed
|
||||
when no longer needed to avoid memory leaks.
|
||||
### 内存管理
|
||||
|
||||
Use the generated `.delete()` method on wrapped instances to destroy the
|
||||
underlying C++ object:
|
||||
通过 Embind 封装创建或返回到 JavaScript 中的 C++ 对象句柄保存在 WebAssembly 堆内存中，**不会**被 JS 运行时的垃圾回收器自动回收。
|
||||
|
||||
任何暴露给 JS 的堆分配 C++ 对象（例如通过 `new Module.MyClass(...)` 创建，或作为绑定的指针/引用返回），在不再需要时必须显式释放，以避免内存泄漏。
|
||||
|
||||
在封装实例上调用生成的 `.delete()` 方法来销毁底层 C++ 对象：
|
||||
|
||||
```typescript
|
||||
const obj = new Module.MyClass(...);
|
||||
// ... use obj ...
|
||||
obj.delete(); // free the C++ memory
|
||||
// ... 使用 obj ...
|
||||
obj.delete(); // 释放 C++ 内存
|
||||
```
|
||||
|
||||
Be careful to call `.delete()` exactly once per created object (double-delete
|
||||
is an error). In JS code paths that may throw or return early, ensure
|
||||
deletion happens in finally blocks or wrap lifetime management to avoid leaks.
|
||||
请注意，每个创建的对象只能调用 `.delete()` **一次**（重复释放属于错误）。在可能抛出异常或提前返回的 JS 代码路径中，请确保在 `finally` 块中执行删除操作，或对生命周期管理进行封装以避免内存泄漏。
|
||||
|
||||
> [!IMPORTANT]
|
||||
> _Embind's documentation strongly recommends that JavaScript code explicitly
|
||||
> deletes any C++ object handles it has received._
|
||||
> _Embind 文档强烈建议 JavaScript 代码显式释放其接收到的所有 C++ 对象句柄。_
|
||||
|
||||
### Copy vs. Reference
|
||||
### 拷贝 vs. 引用（Copy vs. Reference）
|
||||
|
||||
When interacting with MuJoCo objects through the WASM bindings, it's important
|
||||
to understand how data is accessed. Properties on objects like `MjModel` and
|
||||
`MjData` can expose data in two ways: by copy or by reference.
|
||||
通过 WASM 绑定与 MuJoCo 对象交互时，理解数据的访问方式非常重要。`MjModel` 和 `MjData` 等对象上的属性可以通过两种方式暴露数据：按值拷贝（Copy）或按引用（Reference）。
|
||||
|
||||
#### 1. By Copy (Value-based access)
|
||||
#### 1. 按值拷贝（基于值的访问）
|
||||
|
||||
Some properties return a copy of the data at the time of access. This is common
|
||||
for complex data structures that need to be marshalled from C++ to JavaScript.
|
||||
某些属性在访问时会返回数据的副本。对于需要从 C++ 封送到 JavaScript 的复杂数据结构，这是常见做法。
|
||||
|
||||
A key example is `MjData.contact`. When you access `data.contact`, you get an
|
||||
object containing a copy of the contacts at that specific moment in the
|
||||
simulation.
|
||||
一个典型的例子是 `MjData.contact`。当访问 `data.contact` 时，您会获得一个包含该仿真时刻接触信息副本的对象。
|
||||
|
||||
If you step the simulation forward, they will not be updated. You must access
|
||||
`data.contact` again to get the new contact information.
|
||||
如果推进仿真步进，这些副本将不会自动更新。您必须重新访问 `data.contact` 才能获取最新的接触信息。
|
||||
|
||||
The object you get is a JavaScript proxy interface generated by [Emscripten’s Embind library](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html#built-in-type-conversions) when you expose a `std::vector` using `register_vector<T>`. It is essentially a "bridge" object.
|
||||
您获得的对象是由 [Emscripten Embind 库](https://emscripten.org/docs/porting/connecting_cpp_and_javascript/embind.html#built-in-type-conversions)在使用 `register_vector<T>` 暴露 `std::vector` 时生成的 JavaScript 代理接口。它本质上是一个“桥接”对象。
|
||||
|
||||
```typescript
|
||||
export interface MjContactVec extends ClassHandle {
|
||||
/** Appends a new element to the end of the vector, increasing its length by one. */
|
||||
/** 向向量末尾追加一个新元素，长度加 1。 */
|
||||
push_back(_0: MjContact): void;
|
||||
/** Resizes the vector to contain the specified number of elements, filling new slots with the provided value. */
|
||||
/** 调整向量大小以包含指定数量的元素，新位置填充提供的值。 */
|
||||
resize(_0: number, _1: MjContact): void;
|
||||
/** Returns the total number of elements currently stored in the vector. */
|
||||
/** 返回向量中当前存储的元素总数。 */
|
||||
size(): number;
|
||||
/** Retrieves the element at the specified index, or returns undefined if the index is out of bounds. */
|
||||
/** 检索指定索引处的元素；如果索引越界则返回 undefined。 */
|
||||
get(_0: number): MjContact | undefined;
|
||||
/** Overwrites the element at the specified index; returns true if successful or false if the index is invalid. */
|
||||
/** 覆盖指定索引处的元素；成功返回 true，索引无效返回 false。 */
|
||||
set(_0: number, _1: MjContact): boolean;
|
||||
}
|
||||
```
|
||||
|
||||
Example:
|
||||
示例：
|
||||
```typescript
|
||||
// Gets contacts at the current time.
|
||||
// 获取当前时刻的接触信息
|
||||
const contacts = data.contact;
|
||||
|
||||
// Step the simulation
|
||||
// 推进仿真单步
|
||||
mujoco.mj_step(model, data);
|
||||
|
||||
// `contacts` is now stale. To get the new contacts, you must access the property again:
|
||||
// `contacts` 现在已过时。要获取新的接触信息，必须重新访问该属性：
|
||||
const newContacts = data.contact;
|
||||
|
||||
// Remember to delete all created objects when they are no longer needed.
|
||||
// 记得在不再需要时删除所有创建的对象
|
||||
contacts.delete();
|
||||
newContacts.delete();
|
||||
```
|
||||
|
||||
#### 2. By Reference (View-based access)
|
||||
#### 2. 按引用（基于视图的访问）
|
||||
|
||||
Many properties, especially large numerical arrays, return a live view directly
|
||||
into the WebAssembly memory. This is highly efficient as it avoids copying large
|
||||
amounts of data.
|
||||
许多属性（特别是大型数值数组）会直接返回指向 WebAssembly 内存的实时视图（Live View）。这种方式效率极高，避免了大量数据的拷贝。
|
||||
|
||||
A key example is `MjData.qpos` (joint positions). When you get a reference to
|
||||
this array, it points directly to the simulation's state data. Any changes in
|
||||
the simulation (e.g., after a call to `mj_step`) will be immediately reflected
|
||||
in this array.
|
||||
一个典型的例子是 `MjData.qpos`（关节位置）。当您获取对该数组的引用时，它直接指向仿真的状态数据。仿真中的任何更改（例如调用 `mj_step` 之后）都将立即反映在该数组中。
|
||||
|
||||
```typescript
|
||||
// `qpos` is a live view into the simulation state.
|
||||
// `qpos` 是指向仿真状态的实时视图
|
||||
const qpos = data.qpos;
|
||||
|
||||
console.log(qpos[0]); // Print initial position
|
||||
console.log(qpos[0]); // 输出初始位置
|
||||
|
||||
// Step the simulation
|
||||
// 推进仿真单步
|
||||
mujoco.mj_step(model, data);
|
||||
|
||||
// `qpos` is automatically updated.
|
||||
console.log(qpos[0]); // Print new position
|
||||
// `qpos` 自动更新
|
||||
console.log(qpos[0]); // 输出新位置
|
||||
|
||||
// Remember to delete all created objects when they are no longer needed.
|
||||
// 记得在不再需要时释放对象
|
||||
data.delete();
|
||||
```
|
||||
|
||||
### Data Layout: Row-Major Matrices
|
||||
### 数据排布：行主序矩阵（Row-Major Matrices）
|
||||
|
||||
When a function from the MuJoCo C API returns a matrix (or needs a matrix as
|
||||
input), these are represented in the JavaScript bindings as flat,
|
||||
one-dimensional `TypedArray`'s. The elements are stored in row-major order.
|
||||
当 MuJoCo C API 函数返回矩阵（或需要矩阵作为输入）时，在 JavaScript 绑定中表示为扁平的一维 `TypedArray`。元素按行主序（Row-Major）存储。
|
||||
|
||||
For example, a 3x10 matrix will be returned as a flat array with 30 elements.
|
||||
The first 10 elements represent the first row, the next 10 represent the second
|
||||
row, and so on.
|
||||
例如，一个 3x10 的矩阵将作为包含 30 个元素的扁平数组返回。前 10 个元素表示第一行，接下来的 10 个元素表示第二行，依此类推。
|
||||
|
||||
Example: Accessing an element at `(row, col)`
|
||||
示例：访问 `(row, col)` 位置的元素
|
||||
```typescript
|
||||
// A 3x10 matrix stored as a flat array.
|
||||
// 存储为扁平数组的 3x10 矩阵
|
||||
const matrix: Float64Array = ...;
|
||||
const nRows = 3;
|
||||
const nCols = 10;
|
||||
|
||||
// To access the element at row `i` and column `j`:
|
||||
// 要访问第 `i` 行、第 `j` 列的元素：
|
||||
const element = matrix[i * nCols + j];
|
||||
```
|
||||
|
||||
### Working with Out Parameters
|
||||
### 处理输出参数（Out Parameters）
|
||||
|
||||
Many functions in the MuJoCo C API use "out parameters" to return data. This
|
||||
means instead of returning a value, they write the result into one of the
|
||||
arguments passed to them by reference (using pointers). In our JavaScript
|
||||
bindings, you'll need to handle these cases specifically.
|
||||
MuJoCo C API 中的许多函数使用“输出参数”（Out Parameters）来返回数据。这意味着它们不是直接返回值，而是将结果写入通过引用（指针）传递给它们的参数中。在 JavaScript 绑定中，您需要针对这些情况做特别处理。
|
||||
|
||||
There are two main scenarios you'll encounter:
|
||||
通常会遇到两种主要场景：
|
||||
|
||||
#### 1. Array-like Out Parameters
|
||||
#### 1. 类数组输出参数
|
||||
|
||||
When a function expects a pointer to a primitive type (like `mjtNum*` or `int*`)
|
||||
to write an array of values, you need to pre-allocate memory for the result on
|
||||
the JavaScript side. We provide helper classes for this: `mujoco.Uint8Buffer`,
|
||||
`mujoco.DoubleBuffer`, `mujoco.FloatBuffer`, and `mujoco.IntBuffer`.
|
||||
当函数期望接收指向基本类型（如 `mjtNum*` 或 `int*`）的指针来写入值数组时，您需要在 JavaScript 端预先分配结果内存。我们为此提供了辅助类：`mujoco.Uint8Buffer`、`mujoco.DoubleBuffer`、`mujoco.FloatBuffer` 和 `mujoco.IntBuffer`。
|
||||
|
||||
Here's how to use them:
|
||||
使用步骤如下：
|
||||
|
||||
1. Create a buffer: Instantiate the appropriate buffer class with an initial array of the correct size (e.g., an array of zeros).
|
||||
2. Call the function: Pass the buffer instance to the function as the out parameter.
|
||||
3. Access the result: Use the `.getView()` method on the buffer to get a `TypedArray` view of the data written by the C++ function.
|
||||
4. Free the memory: When you are done with the buffer, you must call the `.delete()` method to free the underlying memory and prevent memory leaks.
|
||||
1. **创建缓冲区**：使用正确大小的初始数组（例如全零数组）实例化相应的缓冲区类。
|
||||
2. **调用函数**：将缓冲区实例作为输出参数传递给函数。
|
||||
3. **获取结果**：在缓冲区上调用 `.getView()` 方法，获取由 C++ 函数写入的数据的 `TypedArray` 视图。
|
||||
4. **释放内存**：使用完缓冲区后，必须调用 `.delete()` 方法释放底层内存，以防止内存泄漏。
|
||||
|
||||
Example: Rotating a vector
|
||||
示例：旋转向量
|
||||
|
||||
The function `mju_rotVecQuat` rotates a vector `vec` by a quaternion `quat` and
|
||||
stores the result in the `res` out parameter.
|
||||
函数 `mju_rotVecQuat` 使用四元数 `quat` 旋转向量 `vec`，并将结果存储在 `res` 输出参数中。
|
||||
|
||||
```typescript
|
||||
// Create a buffer to hold the 3D vector result.
|
||||
// 创建缓冲区以容纳 3D 向量结果
|
||||
const res = new mujoco.DoubleBuffer([0, 0, 0]);
|
||||
|
||||
const vec = [1, 0, 0];
|
||||
const quat = [0.707, 0, 0, 0.707]; // 90-degree rotation around z-axis
|
||||
const quat = [0.707, 0, 0, 0.707]; // 绕 z 轴旋转 90 度
|
||||
|
||||
try {
|
||||
// Call the function with the buffer as the out parameter.
|
||||
// 调用函数，将缓冲区作为输出参数
|
||||
mujoco.mju_rotVecQuat(res, vec, quat);
|
||||
|
||||
// Get the result as a Float64Array.
|
||||
// 获取 Float64Array 格式的结果视图
|
||||
const resultView = res.getView();
|
||||
console.log(resultView); // Expected: approximately [0, 1, 0]
|
||||
console.log(resultView); // 期望输出：约 [0, 1, 0]
|
||||
|
||||
} finally {
|
||||
// IMPORTANT: Free the memory allocated for the buffer.
|
||||
// 重要：释放为缓冲区分配的内存
|
||||
res.delete();
|
||||
}
|
||||
```
|
||||
|
||||
#### 2. Struct Out Parameters (e.g., mjvCamera*, mjvScene*)
|
||||
#### 2. 结构体输出参数（例如 mjvCamera*、mjvScene*）
|
||||
|
||||
When a function modifies a struct passed by pointer, you should pass an instance
|
||||
of the corresponding JavaScript wrapper class. The underlying C++ struct will be
|
||||
modified in place.
|
||||
当函数修改通过指针传递的结构体时，应传递相应 JavaScript 包装类的实例。底层 C++ 结构体将被就地（in-place）修改。
|
||||
|
||||
Example: Updating a scene
|
||||
示例：更新场景
|
||||
|
||||
The function `mjv_updateScene` populates an `mjvScene` object with information
|
||||
from `mjModel` and `mjData`.
|
||||
函数 `mjv_updateScene` 使用来自 `mjModel` 和 `mjData` 的信息填充 `mjvScene` 对象。
|
||||
```typescript
|
||||
// Create instances of the necessary structs.
|
||||
// 创建必要结构体的实例
|
||||
const model = mujoco.MjModel.from_xml_string(xmlContent);
|
||||
const data = new mujoco.MjData(model);
|
||||
const scene = new mujoco.MjvScene(model, 1000);
|
||||
@@ -362,9 +274,9 @@ const option = new mujoco.MjvOption();
|
||||
const perturb = new mujoco.MjvPerturb();
|
||||
const camera = new mujoco.MjvCamera();
|
||||
|
||||
// ... (step simulation, etc.)
|
||||
// ... (单步仿真等)
|
||||
|
||||
// Update the scene. The 'scene' object is modified by the function.
|
||||
// 更新场景。'scene' 对象被函数就地修改。
|
||||
mujoco.mjv_updateScene(
|
||||
model,
|
||||
data,
|
||||
@@ -375,9 +287,9 @@ mujoco.mjv_updateScene(
|
||||
scene
|
||||
);
|
||||
|
||||
console.log('Number of geoms in scene:', scene.ngeom);
|
||||
console.log('场景中的 geom 数量:', scene.ngeom);
|
||||
|
||||
// Remember to delete all created objects when they are no longer needed.
|
||||
// 记得在不再需要时删除所有创建的对象
|
||||
scene.delete();
|
||||
camera.delete();
|
||||
perturb.delete();
|
||||
@@ -386,141 +298,93 @@ data.delete();
|
||||
model.delete();
|
||||
```
|
||||
|
||||
As with buffers, you are responsible for managing the memory of these struct
|
||||
instances and must call `.delete()` on them when you are finished.
|
||||
与缓冲区一样，您负责管理这些结构体实例的内存，并在使用完毕后调用 `.delete()`。
|
||||
|
||||
### Enums
|
||||
Access via `.value`:
|
||||
### 枚举类型（Enums）
|
||||
通过 `.value` 访问枚举值：
|
||||
```javascript
|
||||
mujoco.mjtDisableBit.mjDSBL_CLAMPCTRL.value
|
||||
```
|
||||
|
||||
### Constants
|
||||
Scalar constants can be accessed as properties:
|
||||
### 常量（Constants）
|
||||
标量常量可以直接作为属性访问：
|
||||
|
||||
```javascript
|
||||
mujoco.mjNEQDATA
|
||||
```
|
||||
|
||||
Non-scalar constants like `mjFRAMESTRING` are also accessed as properties, and
|
||||
return JavaScript arrays:
|
||||
非标量常量（如 `mjFRAMESTRING`）也可以作为属性访问，并返回 JavaScript 数组：
|
||||
|
||||
```javascript
|
||||
mujoco.mjFRAMESTRING
|
||||
```
|
||||
|
||||
This will return a javascript array representation of the values in MuJoCo
|
||||
`mjFRAMESTRING`.
|
||||
这将返回 MuJoCo 中 `mjFRAMESTRING` 包含的值对应的 JavaScript 数组。
|
||||
|
||||
> [!NOTE]
|
||||
> You will notice constants like `mjFRAMESTRING` are typed as `any`. This is
|
||||
> because they are bound using `emscripten::val::array()` in C++, and Embind
|
||||
> maps `emscripten::val` to `any` in TypeScript definition files. While
|
||||
> `EMSCRIPTEN_DECLARE_VAL_TYPE(StringArray)` could be used to define
|
||||
> `StringArray` as an alias for `emscripten::val` and hint to Embind how to
|
||||
> handle conversions in function signatures or when using `.as()` it does not
|
||||
> change how `emscripten::constant` infers types for properties.
|
||||
> 您会发现像 `mjFRAMESTRING` 这样的常量被类型化为 `any`。这是因为它们在 C++ 中使用 `emscripten::val::array()` 进行绑定，而 Embind 在 TypeScript 定义文件中将 `emscripten::val` 映射为 `any`。虽然可以使用 `EMSCRIPTEN_DECLARE_VAL_TYPE(StringArray)` 将 `StringArray` 定义为 `emscripten::val` 的别名，并提示 Embind 如何在函数签名或使用 `.as()` 时处理类型转换，但这不会改变 `emscripten::constant` 推断属性类型的方式。
|
||||
|
||||
## Development
|
||||
## 开发指南
|
||||
|
||||
In order to change the bindings you will need to change the [`bindings.cc`](codegen/generated/bindings.cc)
|
||||
file but this should not be done manually. The file is generated using the
|
||||
Python scripts and template files in the [`codegen`](codegen) folder, to edit
|
||||
the bindings you will need to change those files and re-generate [`bindings.cc`](codegen/generated/bindings.cc)
|
||||
using this command:
|
||||
若要修改绑定，需要修改 [`bindings.cc`](codegen/generated/bindings.cc) 文件，但不应手动编辑。该文件是使用 [`codegen`](codegen) 文件夹中的 Python 脚本和模板文件生成的。要编辑绑定，需要修改这些文件，并使用以下命令重新生成 [`bindings.cc`](codegen/generated/bindings.cc)：
|
||||
|
||||
```sh
|
||||
PYTHONPATH=python/mujoco python3 -m wasm.codegen.update
|
||||
```
|
||||
|
||||
The codegen scripts use MuJoCo’s Python introspect library to generate the
|
||||
Embind `EMSCRIPTEN_BINDINGS` block that binds C++ functions and classes to
|
||||
JavaScript. The functions and classes that are bound are wrappers around
|
||||
MuJoCo's C API. These wrappers provide a convenient place to add features like
|
||||
bounds checking and nice error reporting.
|
||||
代码生成脚本使用 MuJoCo 的 Python 内省（introspect）库来生成将 C++ 函数和类绑定到 JavaScript 的 Embind `EMSCRIPTEN_BINDINGS` 代码块。被绑定的函数和类是 MuJoCo C API 的封装层。这些封装层便于添加边界检查和完善的错误报告等功能。
|
||||
|
||||
### Testing
|
||||
### 测试
|
||||
|
||||
1. **JavaScript API tests.**
|
||||
These verify that a wide variety of MuJoCo functions and classes work
|
||||
correctly when called from JavaScript. Run the tests as follows:
|
||||
1. **JavaScript API 测试。**
|
||||
验证从 JavaScript 调用各种 MuJoCo 函数和类时能否正确工作。运行测试命令：
|
||||
|
||||
```sh
|
||||
npm run test --prefix ./wasm
|
||||
```
|
||||
|
||||
2. **JavaScript API benchmark tests.**
|
||||
The current benchmark tests check JavaScript/C++ shared memory buffers
|
||||
performance. We will increase the coverage of the benchmarks overtime. Run
|
||||
the benchmarks using this command:
|
||||
2. **JavaScript API 基准性能测试。**
|
||||
目前的基准测试检查 JavaScript/C++ 共享内存缓冲区的性能。随着时间推移，我们将提高基准测试的覆盖率。运行基准测试：
|
||||
|
||||
```sh
|
||||
npm run benchmark --prefix ./wasm
|
||||
```
|
||||
|
||||
3. **Bindings generator tests.**
|
||||
These are relevant when developing or extending the bindings. The following
|
||||
command finds and runs all `test_*.py` or `*_test.py` files in the `wasm`
|
||||
folder:
|
||||
3. **绑定生成器测试。**
|
||||
在开发或扩展绑定时相关。以下命令会查找并运行 `wasm` 文件夹中的所有 `test_*.py` 或 `*_test.py` 文件：
|
||||
|
||||
```sh
|
||||
PYTHONPATH=python/mujoco python3 -m pytest ./wasm
|
||||
```
|
||||
|
||||
### Debugging
|
||||
### 调试
|
||||
|
||||
We provide a “sandbox” app where you can quickly write code to run in your
|
||||
browser. Write your code in the [`main.ts`](tests/sandbox/main.ts) file and use
|
||||
the following command to execute it in your browser:
|
||||
我们提供了一个“沙盒（sandbox）”应用，您可以在其中快速编写要在浏览器中运行的代码。在 [`main.ts`](tests/sandbox/main.ts) 文件中编写代码，并使用以下命令在浏览器中执行：
|
||||
|
||||
```sh
|
||||
npm run dev:sandbox --prefix ./wasm
|
||||
```
|
||||
|
||||
The page will be blank since the script only logs to the console output. You
|
||||
can add your code at the indicated placeholder and use Chrome DevTools for
|
||||
debugging. It is possible to set up a debug workflow where stack traces and
|
||||
stepping through code across language boundaries work correctly. Our current
|
||||
method to do this only works internally at Google, but it should be possible to
|
||||
replicate the experience with open-source tooling — community suggestions are
|
||||
welcome!
|
||||
页面将是空白的，因为脚本仅在控制台（console）输出日志。您可以在指定的占位符处添加代码，并使用 Chrome 开发者工具进行调试。可以设置支持跨语言边界正确调用栈追踪和单步调试的工作流。我们目前实现这一点的方法仅在 Google 内部有效，但应该可以使用开源工具链复制相同的体验——欢迎社区提出建议！
|
||||
|
||||
## Versioning
|
||||
Package versions follow the official MuJoCo release versions.
|
||||
For example:
|
||||
## 版本规范
|
||||
软件包版本遵循 MuJoCo 官方发布版本。
|
||||
例如：
|
||||
|
||||
| npm version | MuJoCo version |
|
||||
| npm 版本 | MuJoCo 版本 |
|
||||
|-------------|----------------|
|
||||
| 3.5.0 | 3.5.0 |
|
||||
|
||||
## Future Work
|
||||
## 未来工作
|
||||
|
||||
1. **Bind all useful APIs.**
|
||||
These bindings are not yet complete. While the main MuJoCo APIs (`mj_step`,
|
||||
`mj_loadXML`, etc.) are well tested, other APIs (e.g., functions from
|
||||
`mjspec.h`) remain untested in real web applications (though test code for
|
||||
the `mjspec` bindings does exist).
|
||||
1. **绑定所有实用 API。**
|
||||
这些绑定尚未完全覆盖所有接口。虽然核心 MuJoCo API（`mj_step`、`mj_loadXML` 等）已经过良好测试，但其他 API（例如来自 `mjspec.h` 的函数）在真实的 Web 应用程序中仍未经充分测试（尽管 `mjspec` 绑定的测试代码已存在）。
|
||||
|
||||
2. **Improve the developer experience.**
|
||||
There is still work to be done to improve the developer experience when
|
||||
developing the WASM bindings. The most obvious issue is that bindings
|
||||
generation is not yet fully automated. As a result, it is currently less
|
||||
convenient than we'd like to identify and apply the changes needed to update
|
||||
the bindings. The goal is to eventually automate all binding code generation
|
||||
and clearly communicate what changes are required in the WASM bindings as a
|
||||
result of C++ updates. This problem should only affect developers working on
|
||||
the MuJoCo engine in C++, not end users writing JavaScript.
|
||||
2. **改善开发者体验。**
|
||||
在开发 WASM 绑定本身的开发者体验方面仍有改进空间。最明显的问题是绑定生成尚未完全自动化。因此，当前识别和应用更新绑定所需的更改还不够便捷。目标是最终将所有绑定代码生成自动化，并清晰提示由于 C++ 更新而在 WASM 绑定中需要进行的更改。此问题仅影响从事 MuJoCo C++ 引擎开发的开发者，不影响编写 JavaScript 的最终用户。
|
||||
|
||||
3. **Improve the documentation.**
|
||||
The documentation in this README will eventually be merged into the main
|
||||
MuJoCo documentation once the bindings are complete and named access is
|
||||
implemented. We also intend to review the bindings APIs and make adjustments
|
||||
to minimize differences with the Python bindings (while respecting language
|
||||
idioms) to reduce the amount of additional documentation required.
|
||||
3. **完善文档。**
|
||||
一旦绑定完成且按名称访问完全实现，本 README 中的文档最终将合并到 MuJoCo 主文档中。我们还计划审查绑定 API 并进行调整，以在遵循语言惯用法的同时最大程度减少与 Python 绑定的差异，从而减少所需的额外文档量。
|
||||
|
||||
4. **Improve the [example](#example-application).**
|
||||
We aim to provide an example application that can be easily modified and
|
||||
embedded into a paper project page (see [this example](https://kzakka.com/robopianist/)).
|
||||
This could be achieved by extending the Three.js example or by compiling the
|
||||
MuJoCo platform C++ code using the Emscripten toolchain. Community
|
||||
suggestions and contributions are welcome!
|
||||
4. **完善[示例应用](#示例应用程序)。**
|
||||
我们的目标是提供一个可以轻松修改并嵌入到学术论文项目主页中的示例应用程序（参见[此示例](https://kzakka.com/robopianist/)）。这可以通过扩展 Three.js 示例或使用 Emscripten 工具链编译 MuJoCo 平台 C++ 代码来实现。欢迎社区提出建议并参与贡献！
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -0,0 +1,41 @@
|
||||
<!--
|
||||
Copyright 2025 DeepMind Technologies Limited
|
||||
|
||||
Licensed under the Apache License, Version 2.0 (the "License");
|
||||
you may not use this file except in compliance with the License.
|
||||
You may obtain a copy of the License at
|
||||
|
||||
http://www.apache.org/licenses/LICENSE-2.0
|
||||
|
||||
Unless required by applicable law or agreed to in writing, software
|
||||
distributed under the License is distributed on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
||||
See the License for the specific language governing permissions and
|
||||
limitations under the License.
|
||||
-->
|
||||
|
||||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<title>MuJoCo WebAssembly</title>
|
||||
<style>
|
||||
#button-container {
|
||||
position: fixed;
|
||||
bottom: 20px;
|
||||
left: 50%;
|
||||
transform: translateX(-50%);
|
||||
display: flex;
|
||||
gap: 10px;
|
||||
}
|
||||
</style>
|
||||
<script type="module" crossorigin src="./assets/index-DpY1_NiW.js"></script>
|
||||
</head>
|
||||
<body>
|
||||
<div id="button-container">
|
||||
<button id="pause-button">Pause</button>
|
||||
<button id="reset-button">Reset</button>
|
||||
<button id="contact-button">Show Contacts</button>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user