# 托盘位姿远程标注工具：宽度坐标对齐方案

**状态：已按用户确认执行并上线。** 使用入口、实际界面和验收限制见[远程标注工具使用说明](pallet_pose_review_web.md)。本页保留当时确认的方案及静态实例。

## 1. 本轮更新：两幅图共用叉取面宽度 W

正视图和俯视图均以 **W（托盘叉取面左右长边方向）** 为横轴，沿选定叉取面建立工作视图：

| 视图 | 横轴 | 纵轴 | 主要用途 |
|---|---|---|---|
| 上方正视图 | 宽度 W | 高度 H | 看两侧边缘、托盘腿、叉孔与中心的关系 |
| 下方俯视图 | 同一宽度 W | 深度 D | 平移、旋转刻度标尺，标注中心与叉入方向 |

W随选定叉取面的长边方向建立。托盘相对传感器倾斜时，不能直接把固定的传感器横轴当作W。

对当前x/y/theta任务，W取叉取面长边在工作水平面内的方向；D为与W垂直、指向叉入方向的水平深度轴；H使用该传感器配置登记的高度轴。面存在俯仰或非平面误差时，保留对应点云厚度，不能为了显示成直线而移动实测点。高度轴和单位未确认的来源需明确记录其配置状态。

上下视图共用W的正方向、原点、范围和像素比例；横向缩放、平移及中心/左右端点参考线联动。初始W正方向对应图像左到右，同一目标编辑期间固定符号，避免平面法向翻转导致镜像。

## 2. 实例一：真实图像和点云的工作台布局

![真实样本工作台布局](assets/pallet_pose_annotation_design/workstation_real_sample.png)

[查看原尺寸图片](assets/pallet_pose_annotation_design/workstation_real_sample.png)

- 左侧上方：原始强度图，白色虚线为原人工框；初始编辑多边形取该框四角。
- 左侧下方：多边形编辑后的区域放大示例，支持增加/删除/拖动顶点及撤销重做。
- 右侧上方：正视W—H，显示托盘三腿、两叉孔与左右外轮廓。
- 右侧下方：俯视W—D，标尺中心及左右端点与上图同列。
- 灰色为原始点云上下文，蓝色为多边形内点云，橙色为拟合叉取面候选，绿色为标尺。

本图使用原train样本 `2024_10_30/30-10-2024_10-03-05#245mm/1600mm/0mm`。多边形、中心和标尺是静态演示，不是新确认的人工标签。使用该样本登记的点云单位比例；叉取面法向由点云几何拟合取得，未使用位姿GT值生成几何结果。

## 3. 实例二：倾斜托盘的坐标建立与标尺操作

![宽度坐标与标尺操作](assets/pallet_pose_annotation_design/width_coordinates_and_ruler.png)

[查看原尺寸图片](assets/pallet_pose_annotation_design/width_coordinates_and_ruler.png)

### A. 原始传感器坐标

同一叉取面在原坐标中倾斜，示例拟合的水平法向角约为-31.6°。

### B. 叉取面宽度坐标

旋转的是查看点云所用的坐标基，实测点仍保留原始坐标。叉取面长边沿W展开，正视图与俯视图都采用这个W。

**视图内标尺水平，不表示托盘在原坐标系中的theta为0。** 原坐标中的位置、方向通过显示变换逆算并保存。

### C. 标尺拖动和旋转

粉色虚线是人为构造的偏移/旋转示例，绿色线是本图的示意对齐位置。

1. 拖圆形中心手柄，同时改变W和D位置。
2. 拖菱形旋转手柄，绕标尺中心改变方向。
3. 利用正视图中的外轮廓、腿和叉孔辅助判断宽度中心。
4. 可调整标尺左右参考端点，并提供数字输入、小步平移和角度微调。
5. 标尺的中心为零刻度；单位登记后显示mm/cm，可切换；单位未确认时显示原始单位。

**拖动期间锁定视图坐标基。** 否则标尺旋转会同时驱动相机旋转，鼠标/手指与控制点的关系随之漂移。操作完成后可点击“按标尺重对齐”，让当前确认的长边方向重新成为水平W；两个视图同步更新，原坐标位姿保持相同。

## 4. 视图变换与位姿定义

令显示原点为O，宽度、深度、高度单位向量分别为eW、eD、eH。原始点p仅在绘图时变换：

```text
W = dot(p - O, eW)
D = dot(p - O, eD)
H = dot(p - O, eH)

正视图 = (W, H)
俯视图 = (W, D)
```

平面标尺中心为(wc, dc)时，保存位置取下式的原始x/y分量；不将显示原点或中心零刻度冒充传感器原点：

```text
center_xy = (O + wc * eW + dc * eD).xy
```

标尺在局部W—D内的旋转角为delta，叉入方向向量为：

```text
direction = -sin(delta) * eW + cos(delta) * eD
theta_source = atan2(direction.y, direction.x)
```

保存叉入方向箭头，明确180°朝向。记录坐标基、显示原点、单位比例和标尺参数，保证刷新、重新对齐及导出后可重现。

参考点仍建议采用 **叉取面宽度中心**，最终人工确认x/y/theta。如果用户所说的中心指托盘整体几何中心，应先明确托盘深度和换算依据，再变更参考点定义。前视图在本任务中用于帮助定位宽度中心，不由俯视标尺虚构z/roll/pitch。

## 5. 完整工作流

1. 按原分组和目标队列读取图像、原框、已注册PCD及已有机器预标注。
2. 四角初始化多边形；用户增点、拖点、删点，形成原图坐标下的粗区域掩膜。
3. 根据精确像素映射取区域点云，使用距离/法向约束聚类与多平面RANSAC/SVD生成叉取面候选。
4. 支持候选簇/面切换、共面片合并和误选区域剔除，选定用于配准的叉取面。
5. 建立W—H及W—D双视图，拖动和旋转标尺；保存前可重新对齐视图复查。
6. 分别确认区域掩膜和位姿；草稿自动保存，支持历史回看、版本冲突提示和待处理状态。
7. 独立保存原图多边形/掩膜、区域与叉取面原始点索引、人工位姿、参考点定义、单位/轴配置及审核历史。

多边形变更后重新计算区域点云，已有位姿标记为需复核；旧异步任务的结果不可覆盖新的编辑版本。显示降采样不影响完整分辨率掩膜和原始点索引导出。

桌面采用左图像、右侧上正视/下俯视；手机采用图像编辑与点云配准工作页，点云页同时显示上下双视图并固定主要操作。队列进度按目标身份统计。

## 6. 公网服务与验收

确认方案后采用Python后端、Canvas/WebGL前端和独立SQLite标注库，建立独立本机服务和Cloudflare Tunnel，交付HTTPS地址、访问码、运行状态及启动/停止命令。按此前方案使用Quick Tunnel，隧道重建后最新地址写入状态文件。

导出包括LabelMe多边形JSON、PNG/COCO RLE掩膜、位姿JSONL/CSV、点索引NPZ与来源清单。

验收以真实点云和已知几何样例检查：

- 原图像素到原始点索引的对应关系，包括原生旋转配置。
- 两视图同一W位置的屏幕横坐标一致；缩放、平移、窗口变化后仍一致。
- 俯视图等比例，标尺长度和角度不受窗口拉伸影响。
- 旋转/平移标尺、按标尺重新对齐前后，原坐标位姿一致。
- 模型建议、自动平面及人工最终确认记录的来源可追溯。
- 公网登录、鼠标/触摸拖动、保存、刷新恢复和历史修改流程。

当前实例图已验证上下视图W轴同列误差为0像素；这只是静态图生成的几何检查，不是浏览器交互验收。

## 7. 本轮产物

- [工作台实例PNG](assets/pallet_pose_annotation_design/workstation_real_sample.png)
- [宽度坐标与操作PNG](assets/pallet_pose_annotation_design/width_coordinates_and_ruler.png)
- [实例来源与静态几何检查](assets/pallet_pose_annotation_design/example_provenance.json)
- 图像生成脚本：`scripts/render_pose_annotation_design.py`

上述图片为需求确认阶段的静态示意，不是实际人工标注。执行后的工具支持多边形编辑、同宽度轴双视图、标尺配准、保存恢复和公网服务，实际截图及验收记录见使用说明。
