# 传感器插件（Sensor Plugins）

通过[引擎插件](https://mujoco.readthedocs.io/en/latest/programming/extension.html#engine-plugins)实现的自定义传感器。

- [触觉网格（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)
  - [解析 SDF 示例模型](#example-model-with-analytical-sdf)

## [Touch Grid](touch_grid.h)

该传感器将接触力聚合到“触觉像素（taxels）”中：即类似像素的矩形阵列单元。

`touch_grid` 传感器与一个 site（位姿点）关联，用于感知该 site 所属的父刚体与所有其他刚体之间的接触力和力矩。site 的坐标系决定了传感器的朝向，采用与相机和光源相同的约定：传感器指向坐标系的 **-z（负 z 轴）**方向，因此 x 轴和 y 轴分别对应水平方向和垂直方向。

该传感器的输出是 1 到 6 个“触觉图像（touch images）”的堆叠，对应于传感器坐标系中的力和力矩。力和力矩按照 [z, x, y] 顺序排列，对应于接触坐标系中的顺序：[法向, 切向, 切向] 和 [扭转, 滚动, 滚动]。每个“触觉像素（taxel）”对应于球坐标系中的一个角度分桶（angular bin），并聚合该分桶内发生的所有接触力（发生在传感器 site 所属刚体与任何其他刚体之间）。

该传感器由 6 个参数进行参数化：

1. 通道数（按照上述顺序）：_取值范围为 [1, 6] 的正整数_
2. 水平分辨率：_正整数_
3. 垂直分辨率：_正整数_
4. 水平视场角（FOV）：_角度范围在 (0, 180] 度的正浮点数_
5. 垂直视场角（FOV）：_角度范围在 (0, 90] 度的正浮点数_
6. 中央凹形变（Foveal deformation）：_取值范围在 [0, 1] 的正浮点数_

有关视场角和中央凹形变参数的可视化解释，请参见下方的图示。这些参数作为插件的配置属性进行传递：

```xml
<mujoco>
  <extension>
    <plugin plugin="mujoco.sensor.touch_grid"/>
  </extension>
  ...
  <sensor>
    <plugin name="touch" plugin="mujoco.sensor.touch_grid" objtype="site" objname="touch">
      <config key="nchannel" value="3"/>
      <config key="size" value="7 7"/>
      <config key="fov" value="45 45"/>
      <config key="gamma" value="0"/>
    </plugin>
  </sensor>
</mujoco>
```

请注意以下事项：

- 传感器输出的维度为 `nchannel * size_x * size_y`。
- `objtype="site" objname="touch"` 指定传感器与 site 关联，以及关联的特定 site 名称。
- 视场角始终以“度”为单位，不受 `<compiler>` 中的 "angle" 指令影响。

### 示例模型

<a href="https://youtu.be/0LOJ3WMnqeA" target="_blank">
 <img src="http://img.youtube.com/vi/0LOJ3WMnqeA/hqdefault.jpg" alt="观看视频" width="560" height="315"/>
</a>

请查阅 [touch_grid.xml](../../model/plugin/sensor/touch_grid.xml) 来体验上述模型。

### 球坐标系下的视场角图示

<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;"/>

### 中央凹形变图示

![中央凹形变](images/fovea.png)

### 结合分辨率、视场角和中央凹形变的综合图示

[![touch grid 图示](https://img.youtube.com/vi/YScjmR8LwQI/0.jpg)](https://www.youtube.com/watch?v=YScjmR8LwQI)

## [Touch Stress](touch_stress.h)

该传感器基于与 `touch_grid` 相似的概念和参数化设计，同时克服了它的一些局限性。具体而言，`touch_grid` 只能提供稀疏信息（取决于生成的接触点数量）。而 `touch_stress` 传感器可以生成高分辨率的触觉图像。为了实现这一点，它需要与传感器接触的物体的符号距离函数（Signed Distance Function, SDF）。对于基本几何图元（primitives），这会在内部自动处理；或者必须使用 SDF 插件在模型中显式声明。

与 `touch_grid` 相比有一个重要区别：在此传感器中，力是在局部 taxel 坐标系下计算的，而不是在传感器坐标系下计算的。这使得法向应力和切向应力的物理意义更加直观，如下图所示。

请注意，在这种情况下，传感器报告的应力绝对值与接触力无关。它们纯粹基于几何和运动学考量，即法向应力基于 SDF，切向分量基于滑动速度。

### 解析 SDF 示例模型

```xml
<extension>
  <plugin plugin="mujoco.sdf.gear">
    <instance name="gear">
      <config key="alpha" value="0"/>
    </instance>
  </plugin>
  <plugin plugin="mujoco.sensor.touch_stress">
    <instance name="touch_stress">
      <config key="size" value="37 37"/>
      <config key="fov" value="45 45"/>
      <config key="gamma" value="0"/>
      <config key="nchannel" value="3"/>
    </instance>
  </plugin>
  ...
  <asset>
    <mesh name="gear">
      <plugin instance="gear"/>
    </mesh>
  </asset>
  ...
  <worldbody>
    <geom type="sdf" name="gear" mesh="gear">
      <plugin instance="gear"/>
    </geom>
  ...
  <sensor>
    <plugin instance="touch_stress" objtype="site" objname="touch_site"/>
  </sensor>
</extension>
```

下图展示了由解析 SDF 描述的齿轮上方的一个静止球体，以及沿 x 轴和 y 轴拖动同一球体时的应力分布：

<img src="images/normal.png" style="width: 300px;"/>
<img src="images/tangential1.png" style="width: 300px;"/>
<img src="images/tangential2.png" style="width: 300px;"/>