GripperSlot 抓取区域契约
GripperSlot 是什么
GripperSlot 用于描述物体上允许抓取的位置、方向和变化范围。
例如，料箱的一条边可以被夹爪从多个位置抓取，无需逐个标定抓取点，只需用一个 GripperSlot 描述这段区域。一个物体可以配置多个 Slot，例如分别标定料箱左右两侧的抓取区域。
GripperSlot 描述的是物体的抓取条件。机器人能否到达、选择哪个姿态以及如何运动，由后续 IK 和轨迹规划处理。
源码定义
定义文件：src/lambdasim/robotics/gripper_slot.py
以下为字段初始化源码，序列化和坐标求值方法见源文件：
@dataclass
class GripperSlot:
def __init__(self) -> None:
self.center: ek.vec3 = ek.vec3(0.0, 0.0, 0.0)
self.forward: ek.vec3 = ek.vec3(0.0, 0.0, 1.0)
self.span_axis: ek.vec3 = ek.vec3(1.0, 0.0, 0.0)
self.up_range: float = 2.0
self.slot_input_angle: float = 0.0
self.LR: int = 0
self.GroupName: str = ""
self.parent_object: SceneObject | None = None
空间定义
每个 GripperSlot 都有自己的局部坐标系：
| 字段 | 含义 |
|---|---|
center | 抓取区域的中心位置。 |
forward | 夹爪的插入方向，对应局部 Z 轴。 |
span_axis | 夹爪闭合时划过的方向，对应局部 X 轴。 |
up_range | 沿 Up 方向的纵向抓取总长度，正有限标量，单位米。 |
slot_input_angle | 允许的插入角度总范围，单位为度。 |
GroupName | 关联多个 Slot 的分组名称；空字符串表示独立采样。 |
LR | 左右手标记：0 为左，1 为右。采样时的末端分配由 ee_ids 明确指定。 |
三个轴相互垂直，满足：
Up = normalize(Forward × SpanAxis)
Up 是只读派生属性 slot.up_axis，无需单独赋值；它是 Slot 的局部 Y 方向，不一定朝向世界坐标的上方。
例如，slot.up_range = 0.30，表示抓取位置可以沿 Up 在中心两侧各移动 0.15 米。范围端点为 center ± up_axis * up_range / 2。
slot_input_angle = 30 表示围绕 SpanAxis，允许相对标定方向偏转 -15°～+15°。
多个 Slot 如何配合
双臂搬运料箱时，左右两侧的抓取位置通常需要保持对应。
将两个 Slot 标定为相同的非空 GroupName 后，采样 API 会在内部为它们生成相同的局部移动距离和偏转角度，再分别映射到各自的空间。同组范围不同时，使用共同允许的范围。
未分组的 Slot 各自独立采样。
采样还会考虑 SpanAxis 正反两种朝向；同组 Slot 同步翻转，不会一部分取正向、另一部分取反向。
分组由采样 API 内部处理，使用端无需重新分组或修改组名。
读取并采样
假设 box 是已加载且完成抓取标定的 SceneObject：
from lambdasim import robotics
slots = robotics.read_gripper_slots(box)
samples = robotics.sample_gripper_groups(
slots,
ee_ids=(0, 1),
count=50,
seed=7,
)
此例假设物体包含两个 Slot，分别对应机器人登记的 EE 0 和 EE 1。
count=50：生成 50 组候选，包含 SpanAxis 正反朝向的候选。seed=7：固定随机种子，便于重复测试。samples.candidates：每项是一组需要联合求解的末端目标，可直接传给 Batch IK。
读取 API 已处理节点坐标转换和所属物体绑定，不需要逐个设置 parent_object，也不需要额外传入物体世界矩阵。
物体移动后，应重新采样；采样结果是生成时的世界位姿快照。
标定与保存
在 LambdaEngine 中，可通过 MakeGripperSlot 组件编辑抓取区域，使用 Visual Guide 和 Gizmo 调整位置、方向、纵向抓取范围（Up Range）及角度范围。
数据保存在节点的自定义 metadata 中：
metadata["lambdasim"]["gripper_slots"]
该字段是 GripperSlot 记录的列表，属于 LambdaSim 的业务数据约定，不是 USD 官方机器人 Schema。
保存场景为 USD 后可保留标定数据；再次加载时，通过 read_gripper_slots() 读取即可使用。历史资产中的 up 向量在读取边界转换为标量 up_range = 2 * length(up)；新保存的数据只写入 up_range，组件记录版本为 2。
