add chinese

2026-08-19 17:14:37 +08:00
parent ac4f431ff5
commit b45b15d153
26 changed files with 4388 additions and 805 deletions
@@ -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` 值。 |
@@ -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]：若大于零，缆绳将根据机械应力着色；该值代表颜色标尺中的最大应力。
@@ -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);
 };
 ```
-
-
-
-
-
-
-
@@ -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
+### 中央凹形变图示

-![foveal deformation](images/fovea.png)
+![中央凹形变](images/fovea.png)

-### Illustration combining resolution, fields-of-view and foveal deformation
+### 结合分辨率、视场角和中央凹形变的综合图示

-[![touch grid illustration](https://img.youtube.com/vi/YScjmR8LwQI/0.jpg)](https://www.youtube.com/watch?v=YScjmR8LwQI)
+[![touch grid 图示](https://img.youtube.com/vi/YScjmR8LwQI/0.jpg)](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;"/>