表面距离#
gs.sensors.SurfaceDistanceProbe 报告一个或多个探针点到一组被跟踪刚体连杆网格表面的最近距离。每个探针安装在某个连杆的局部坐标系中并随之运动，因此随着场景演化，该传感器能回答：”我机器人上的这个点离那些物体有多近？”
完整脚本见 examples/sensors/surface_distance_shadowhand.py，该示例将探针安装在 Shadow Hand 的手掌和指尖上，在键盘遥操作下测量到鸭子网格和盒子的距离。
最小示例#
import genesis as gs
gs.init(backend=gs.cpu)
scene = gs.Scene()
robot = scene.add_entity(gs.morphs.URDF(file="urdf/shadow_hand/shadow_hand.urdf"))
duck = scene.add_entity(
gs.morphs.Mesh(file="meshes/duck.obj", scale=0.06, pos=(-0.2, 0.4, 0.6)),
)
sensor = scene.add_sensor(
gs.sensors.SurfaceDistanceProbe(
entity_idx=robot.idx,
link_idx_local=robot.get_link("palm").idx_local,
probe_local_pos=((0.0, 0.0, 0.0),), # one probe at the palm-link origin
probe_radius=0.5, # max sensing range, meters
track_link_idx=(duck.base_link_idx,), # global link idx to measure against
)
)
scene.build()
scene.step()
distances = sensor.read() # shape ([n_envs,] n_probes), meters
points = sensor.nearest_points # shape ([n_envs,] n_probes, 3), world frame
探针与被跟踪连杆#
探针是固定在连杆局部坐标系中的一个点。probe_local_pos 是一组 (x, y, z) 偏移（单位米），每个探针一个，全部安装在实体 entity_idx 上由 link_idx_local 指定的连杆。像示例那样在指尖和手掌上安装多个探针，就能以较低开销勾勒出手部接近物体时的空间态势。
track_link_idx 列出要测量的连杆，使用求解器连杆空间中的全局连杆索引，而不是连杆局部索引。可以从你想跟踪的实体上读取这些索引：单连杆网格用 duck.base_link_idx，关节体的特定连杆用 entity.get_link(name).idx。传感器查询这些连杆上每个网格几何体的三角面，因此距离是到真实表面的距离，而不是到包围盒或中心的距离。
读取传感器#
read() 返回每个探针的最近表面距离：
distances = sensor.read() # shape ([n_envs,] n_probes), meters
nearest_points 属性保存每个被跟踪表面上对应的点：
points = sensor.nearest_points # shape ([n_envs,] n_probes, 3), world frame
只有当场景在构建时包含多个环境，二者才会带 [n_envs,] 轴。Genesis World 在每一步写入 nearest_points，因此请至少执行一次 scene.step() 后再读取；首次步进之前它保持为零。