orisys-sensor-design/docs/design-parameters.md

# `design.yaml` 参数说明

本文是 `sensors/<sensor>/r01/design.yaml` 的详细说明，主要面向传感器研发工程师。


本文重点解释两个命令：

- `texture_patch`：在普通 UV 展开图上生成一整张标记图案；
- `texture_patch_views`：把同一套图案拆成多个相机投影视图，并决定每个视图负责印刷哪一部分。

例子：`orisys-design texture-views .\sensors\finger\r01 --grayscale`

## 1. 总览

传感器设计工具依赖开源3维绘图软件blender以及自带的Python API 开发，需要传感器3维CAD模型、镜头FOV参数、cmos的尺寸。目前主要用于摄像头位置和标记点的设计，后续会加入光源优化。

摄像头位置的设计主要是确保在镜头FOV限制下，可以完全覆盖传感的表面，分为感知面积最大化和死区清除两部分。

标记点设计目的是：
* 算法上要导出unwarp conformal的平面图，把3维变形映射到2维计算同时降低畸变。
* 生产上要在不可展曲面上印刷/雕刻标记点，程序需要导出曲面在加工平面上投影的平面图，格式包括 PNG、SVG 或 PDF。

导出的图片类型一览：
```text
Blender 三维传感表面 (sensing surface)
         ├─ `export` conformal UV 展开                           → 计算用
         │
         ├─ `texture` 单相机投影（projected from view） UV 展开   → 生产用，一张图覆盖整个表面
         │
         └─ `texture-views` 多个相机投影视图 + 分割               → 生产用，每张图只印自己负责的区域
```
设计参数放置在`sensors/<sensor>/r01/design.yaml`里面，具体设计资源参考现有传感器的文件树。

### 1.1 基础原理

叠动视触觉传感器基于单色光技术，标记图案要具备高密度纹理信息，用于光流追踪，目前采用随机彩色方格矩阵纹理设计和UV打印生产，对于平面传感器可以简单密铺，对于Finger曲面传感器需要考虑曲面畸变、镜头透视误差、可视区域、可生产性等等，要在3维层面进行设计，与三维绘图的呈现方式类似。考虑到代码兼容性、价格、功能等因素，采用开源的三维绘图软件Blender和配套的python进行程序开发，可以从相机、模型、图案、光源4个部分独立和耦合设计。

设计流程是：1. 结构传感器曲面设计；2.模型导入Blender摄像头位置摆放；3.曲面不可视区域去除；4.结构曲面修改；5.模型导入Blender和标记图案设计;6.生产摄像头位置摆放和图案生产文件导出。

曲面结构除了标品外，要根据客户灵巧手可释放的空间来设计，但一般有一个非触觉版本的模型，可以作为基准来修改，考虑塑料壳、硅胶层的厚度，得出一个初步的感知曲面形状和位置。然后导入Blender进入详细设计，在结构和摄像头FOV的约束下，选择合适的摄像头摆放位置来达到可视区域的最大化，再根据摄像头FOV去除曲面的不可视区域，然后反馈结构进行修改。最后根据修改后的摄像头位置、曲面结构，生成计算用和生产用标记点图案。

计算用标记点图案作用是把在三维空间的曲面投影到二维的平面上，方便通过过去用于平面的算法计算，投影方法目前采用conformal投影，未来可以尝试其他方法。三维到二维的投影通过Blender里面在实际摄像头位置的透视投影相机，和感知曲面的模型获取，并通过`export`指令导出图案和投影矩阵。生产用图案是通过Blender的正交投影相机模拟在传感器治具正上方，由加工设备（UV打印机或激光雕刻机）看到的形状/投影，从而把我们在曲面上的目标图案，从三维空间投影到生产的二维平面上，支持多角度生产和重复部分去除功能。

通过Bleder Python API，在具备视触觉传感器结构和材料特性下可以进行物理准确的仿真，是本设计和模拟工具的核心支撑。


### 1.2 Blender 使用
以下文档基于Blender 5.0 版本 （5.0.1）编写，如非必要不进行版本更新。

![blender_layout](.\img\design_parameters\blender_layout.png)

Blender的资源树在右上方，不同集合（Collection）分别代表不同的资源：

| 集合 | 种类 | 作用 | 导出 |
| --- | --- | --- |--- |
| ASSEMBLY| mesh、摄像头 | 外壳模型、生产视角摄像头 |所有网格物体，cam_uv_**x** |
| EXCLUDE | 非导出物体 | 文件暂存 |无|
| EXPORT_COMPUTE| mesh | 感知曲面 |sensing_surface|
| FRAMES| empty | 原点定义 |origin_sensor |
| DESIGN_SIM| 摄像头、光源 | 视场设计仿真 |cam_sensor |




---
# 下方文档是AI生成，待整理
---

### 1.1 初学者需要知道的几个词

|术语|简单解释|
|---|---|
|UV|把三维表面的点映射到二维平面的坐标。`U`、`V` 类似图像中的 `x`、`y`|
|UV 展开（unwrap）|像展开纸盒一样，把弯曲表面摊到二维平面；允许人为安排接缝和布局|
|Project from View (Bounds)|从指定相机看向物体，把画面投影到 UV，并缩放到 `[0,1]²`|
|pattern camera|定义标记图案从哪个方向投到表面，即“图案来源”|
|region camera|判断一个区域由哪个印刷视图负责，即“区域分工”|
|ownership|某个三角形最终归哪一个视图打印|
|hole|没有任何视图负责的表面区域，会形成漏印或“秃斑”|
|seam|Blender 中标记的接缝，用于把表面分区|
|page|输出 SVG/PDF 对应的实际物理尺寸，单位为毫米|
|raster|PNG 的像素尺寸，例如 `3700 × 3280 px`|

### 1.2 阅读参数时遵守三条规则

1. **每一个测量值都必须说明失效条件。** 例如相机移动后，以旧相机位置测出的覆盖率就不能
   继续使用。
2. **测量条件是结果的一部分。** 涉及区域相机时，必须同时记录相机位姿，因为位姿就是算法
   输入。
3. **文件哈希只代表测量当时的文件。** `geometry.blend` 会持续修改。引用旧哈希前必须重新
   计算，不能把历史哈希当成当前状态。

本文最重要的目的，是防止一个过期数值继续显得“很合理”。只把说明写在 YAML 注释里，没有
自动失败路径；参数失效后程序仍可能正常运行，却生成错误结果。因此本文会明确写出每个关键
数值的来源、失效条件和重测方法。

## 2. 两种纹理命令的区别

|项目|`texture`|`texture-views`|
|---|---|---|
|YAML 配置块|`texture_patch`|`texture_patch_views`|
|输出定义|`uv_outputs`：名称到文件名的映射|`pairs[]`：视图 ID、相机、UV map|
|二维布局|普通 UV 展开，不是相机投影|由相机拟合到边界的投影视图|
|物理页面|`fixed`：读取 `texture_patch.vector` 中声明的毫米尺寸|`auto`：从相机图像平面推导，并验证它确实是投影视图|
|区域归属|不需要，一张图覆盖整个表面|必须，每个 pair 都包含完整表面，但只打印归自己负责的部分|
|任务格式|`texture-job-v3`|`texture-job-multiview-v1`|
|Blender 驱动|`blender/scripts/random_patch_dd02c.py`|`blender/scripts/random_patch_multiview.py`|

`texture_patch_views` 会从 `texture_patch` 继承以下“图案本身”的设置：

- 栅格尺寸 `width`、`height`；
- 网格数量 `nx`、`ny`；
- 随机种子 `seed`；
- 固定页面备用值 `vector`；
- 颜色配置；
- `edge_sample_grid`。

代码入口是 `texture_views.resolve_views_settings(...)`，内部调用
`resolve_texture_settings(...)`。它不会继承 `uv_outputs`、`merge`、`seam` 或 `print`，
因为这些字段分别属于单图输出或多视图分区。

继承方向只有一个：`texture_patch` 是页面、颜色和图案随机性的基础配置；
`texture_patch_views` 在此基础上增加投影视图和区域分工。

> 为什么不合并两个配置块？在 `texture_patch` 中，页面是人工声明的输入，例如
> `18.5 × 16.4 mm`；在 `texture_patch_views` 中，页面是经过验证后从相机投影推导出的
> 结果。合并后，`page.mode` 的含义会依赖旁边是否出现某个键，还会削弱当前严格的未知键
> 检查，使拼错的配置可能被静默忽略。如果未来出现第三个消费者，或者 `uv_1`、`uv_2`
> 不再是边界投影，再重新评估公共配置结构。

## 3. `texture_patch`：在普通 UV 展开图上生成图案

命令会为 `uv_outputs` 中的每个 UV map 各生成一套 PNG、SVG 和 PDF。所有输出共用相同的
随机颜色和页面设置，仅 UV 布局不同。

UV 展开必须预先在 Blender GUI 中完成并保存在 `source_blend`。无界面运行只读取已有 UV
map，不会自动创建或重新展开 UV。

### 3.1 `uv_outputs` 的顺序不能随意调整

程序通过下面的方式构造输出列表：

```python
block["uv_outputs"].items()
```

因此 YAML mapping 的顺序会进入 `texture-job-v3` 的 `outputs[]`。目前四个测试固定要求顺序
为：

```text
["produce", "compute"]
```

仅从生成像素来看，调换顺序不会改变颜色，因为 `patch_colors` 在遍历各 UV 前只计算一次。
但任务文件数组顺序会改变并导致测试失败，所以不要为了“整理”而重排。

### 3.2 为什么有的配置是 `nx == ny`，有的是 `80 × 45`

`nx`、`ny` 表示相机空间中的图案网格数量。`finger-xynova/r01` 的 `cam_sensor` 是正方形
画幅，所以 `nx == ny` 可以让相机空间中的单元接近正方形。

`finger/r01` 使用 `80 × 45`，来自 16:9 相机。这个比例对它自己的相机是合理的，不能因为
另一个型号采用方形网格就统一修改。

### 3.3 `width`、`height` 与 `vector` 的关系

- `width`、`height`：PNG 栅格尺寸，单位是像素；
- `vector.width_mm`、`vector.height_mm`：SVG/PDF 对应的物理页面尺寸，单位是毫米。

当前两个 revision 都使用 200 px/mm：

```text
3280 / 16.4 = 200
3200 / 16.0 = 200
3700 / 18.5 = 200
```

维护时应满足：

```text
raster pixels = px_per_mm × physical millimetres
```

`_warn_if_page_aspect_differs` 会比较栅格长宽比与物理页面长宽比。如果不一致，SVG/PDF
填满页面时会沿某一方向被拉伸。保持上述关系，警告就不会出现。

### 3.4 `seed` 是整个物理图案的随机种子

固定 `seed` 是为了让同一配置反复运行得到相同的图案。同一次生成中的 PNG、SVG、PDF 和
所有 UV map 共用一套颜色。

`texture-views` 里的每个 pair 也必须使用相同 seed，因为它们打印的是同一个物理表面的
不同部分。如果每个视图使用 `seed + i`，两个印刷文件会在同一个表面上产生不同图案。

> 已知文档缺陷：`orisys-design texture-views --seed` 的帮助文字声称“第 i 个 pair 使用
> `seed + i`”，但实际代码让所有 pair 使用 `settings.seed`。实际代码行为是正确的，CLI
> 帮助文字需要另行修正。

## 4. `texture_patch_views`：多个投影视图和区域分工

本节说明**每个键的语义**。为什么这样设计——为什么所有权在生成之前决定、为什么单位是三角形、
以及两种 seam 模式各自的适用条件——见
`D:\orisys_ws\docs\workflow\multiview-ownership-decision.md`。测量数据（拓扑、相机、入射角、
cell pitch）见 [`geometry-measurements.md`](geometry-measurements.md)。

这个流程较容易混淆，因为它同时使用三类信息。

### 4.1 三种角色

1. **图案相机 `pattern_camera`**：决定标记图案从哪个方向投到传感表面。所有视图共用一个
   图案来源，默认是 `cam_sensor`。
2. **区域相机 `pairs[].camera`**：决定该视图适合负责哪些三角形。它只参与区域分工，不是
   图案来源。
3. **`pairs[].uv_map`**：决定该视图最终写入哪个二维布局。

可以把它们理解成：pattern camera 决定“印什么”，region camera 决定“谁来印”，UV map
决定“印刷文件中的坐标”。区分这三者，也能解释为什么片段数量和三角形数量不是同一个概念。

### 4.2 `merge.incidence_limit_deg`

区域归属以 loop triangle 为单位。一个三角形只有同时满足以下条件，才可能归某个视图负责：

- 区域相机能看到它；
- 相机视线与表面法向的夹角不超过 `incidence_limit_deg`；
- 投影面积达到要求。

没有任何视图能够负责的三角形就是 hole，会造成漏印。

在 `finger-xynova/r01` 上，使用真正的 `assign_ownership` 和本次运行生成的 ground truth，
测得：

|`incidence_limit_deg`|hole fraction|相对 `max_hole_fraction: 0.02`|
|---|---|---|
|62°|**0.0480**|**失败**|
|65°|0.0130|通过|
|**70°**|**0.0001**|通过|

这里 `min_triangle_coverage` 不是限制因素：把它从 0.60 放宽到 0，在 62° 和 70° 下都不改变
结果。

这组测量对应以下区域相机位姿：

|相机|方位角|仰角|距离|
|---|---:|---:|---:|
|`cam_uv_1`|308.26°|−24.46°|32.62 mm|
|`cam_uv_2`|231.74°|−24.46°|32.62 mm|

**只要移动区域相机，这张表就立即失效。** `incidence_limit_deg` 描述的是“特定相机位姿与
特定表面”的组合，不是传感器型号自身永远不变的属性。重新调整相机后必须重跑扫描。

> 已撤回的旧结论：早期 `design.yaml` 曾写过“默认 62° 时 hole 面积为 0.100 mm²、比例
> 0.0002”，以及“4960/5007 个三角形有归属，输出 20454 + 21483 个片段”。这些数据在
> 相机移动前成立，现在已经失效。保留这段记录，是为了说明为什么相机相关数据必须写明
> 重测触发条件。

不要删除 YAML 中显式设置的 `incidence_limit_deg: 70.0`。代码中
`texture_views.MERGE_DEFAULTS` 和 `blender/scripts/texture_merge.py` 的默认值都是 62.0，
并有测试要求两处一致。但对当前 Xynova 表面，62° 会产生 4.8% hole；删除覆盖值会静默恢复
错误默认值。

### 4.3 `max_hole_fraction` 是阻断门槛

当 hole fraction 超过 `max_hole_fraction` 时，命令会失败并报告：

- 实际 hole fraction；
- 未覆盖的三角形数量；
- 可能原因。

它不是普通警告。这项检查是在一次 4.8% 漏印被静默输出之后增加的，目的是让“表面有秃斑”
从肉眼发现的问题变成自动失败。

### 4.4 `page.mode: auto` 与 `fixed`

`auto` 只适合使用 Blender **Project from View (Bounds)** 生成的布局。这种布局把相机图像
平面映射到 `[0,1]²`，程序可通过最小二乘仿射拟合反推出页面的实际尺寸。

程序不会因为写了 `auto` 就盲目信任 UV。它会验证：

- 最大拟合残差不超过 `1e-5`；
- UV 边界位于 `[0,1]²`。

真实投影视图的拟合误差大约为 `1.2e-7`；普通 UV 展开的误差约为 0.17–0.70，因此会被拒绝。
`auto` 不会在失败时悄悄退回固定页面。

`fixed` 使用 `texture_patch.vector` 中的页面尺寸。`produce` 和 `compute` 是真正的普通 UV
展开，必须使用 `fixed`；从相机反推它们的页面没有物理意义。

自动页面最终按整数像素确定：

```text
page size = rounded raster pixels / px_per_mm
```

这样页面和栅格的长宽比天然一致。200 px/mm 下，舍入导致的尺寸误差最多为 0.0025 mm，
远低于当前 0.1 mm 对位公差。

已经测得的页面尺寸：

|revision|view|对应测量位姿下的页面|
|---|---|---|
|`finger/r01`|`uv_1`|17.510 × 15.975 mm|
|`finger/r01`|`uv_2`|17.510 × 15.980 mm|
|`finger-xynova/r01`|`uv_1` / `uv_2`|17.670 × 23.565 mm|

这些数值会随相机位置改变，正是使用 `auto` 的原因。Xynova 相机重新定位后，页面从
21.200 × 23.200 mm 自动更新为 17.670 × 23.565 mm。引入自动推导前，固定共享页面在
`finger/r01` 上误差为 6.9%，在 `finger-xynova/r01` 上误差达到 23%，而且横竖方向相反。

### 4.5 `seam.boundary`、`pins` 与 `gap`

`boundary: use_seam` 表示使用 Blender 中人工标记的 seam 作为区域边界。图案生成阶段不会
读取 seam；`patch_projection.py` 只读取 `loop_triangles` 和 `uv_layers`。seam 由后续
ownership 步骤使用。

`pins` 用于在自动分配不符合设计意图时，强制某个连通区域归指定视图。默认留空，让覆盖率
指标决定归属。每次增加 pin 都应写清原因，避免把几何或相机错误隐藏成“人工设置”。

如果启用 gap，总间隙宽度是 `alignment_tolerance_mm` 的两倍。原因是两次独立印刷都可能
产生最大对位误差；每一侧退让一个公差，最坏情况下仍不会重叠。

- `apply: post_process`：将 UV 多边形裁剪到 seam 偏移后的半平面，生成物理宽度准确的直边；
- `apply: geometry_trim`：丢弃整个片段，会产生锯齿边，仅保留作比较。

> 当前仍可看到的阶梯形状来自按三角形分配的 ownership 边界，而不是 gap 自身。gap 只是
> 从这条阶梯边界向内退让。要得到平滑边界，需要支持三角形内部的更细粒度分区。

### 4.6 `print.base_fill`

`base_fill: owned` 会把本视图负责的三角形填成白色，其余区域填黑。这样白色底层也已经沿
seam 分开，两张印刷文件不会在同一位置重复打印白底。

## 5. 常用参数速查

|参数|当前值|来源/测量条件|什么时候失效|怎样重测|
|---|---:|---|---|---|
|Xynova `incidence_limit_deg`|70.0|第 4.2 节记录的相机位姿|移动区域相机或修改表面|对新 ground truth 运行 `assign_ownership`，扫描 62/65/70/75°|
|自动页面|见第 4.4 节|对应区域相机位姿|移动相机或修改网格|重跑 `texture-views`，读取 `_print_views.json`|
|`px_per_mm`|200|设计选择|修改栅格或页面尺寸|计算 `width / vector.width_mm` 和 `height / vector.height_mm`|
|`alignment_tolerance_mm`|0.1 mm|当前印刷与对位能力假设|更换打印、夹具或对位工艺|通过实际计量重新评估，不由本仓库推断|

### 内置默认值不适合当前表面的键

|键|内置默认值|为什么必须保留在 YAML 中|
|---|---:|---|
|Xynova `incidence_limit_deg`|62.0|当前表面会产生 4.8% hole；显式 70.0 是必要配置|

## 6. 已知几何漂移

仓库中的历史资料对 Xynova sensing surface 的描述互不一致：

|来源|记录值|
|---|---|
|`probe-pipeline.md`|2508 vertices / 4834 polygons|
|`xynova-texture-investigation.md`|4818 triangles + 16 quads|
|当前实际测量|2584 vertices / 5007 triangles|

`build/probe/finger-xynova/r01/probe_frames.npz` 来自 2508 顶点的
`sensing_surface_918_s`，而当前带 seam、`uv_1` 和 `uv_2` 的表面有 2584 顶点。因此
`tests/test_render.py::test_end_to_end_render_manifest` 会在顶点数量检查处失败。

这是过期 fixture，不是纹理生成错误。修复方式需要先决定哪个表面才是该 revision 的唯一权威
表面，然后选择其中一种方案：

1. 为当前权威表面重新生成 probe frames；或
2. 把 seam 和 UV 布局制作到已经生成 probe frames 的那个表面上。

当前 revision 包含六个 sensing-surface 变体：

```text
sensing_surface
sensing_surface_0
sensing_surface_0918
sensing_surface_0928
sensing_surface_45
sensing_surface_918_s
```

其中 `_0928` 与 `sensing_surface` 位于相同位置，是重合副本。`EXCLUDE` collection 的
`exclude=False` 表明它只是名称叫 EXCLUDE，并没有在 view layer 中真正排除。射线检测会先
击中这个副本，随后把所有片段判为不可用。

目前 `_0928` 已隐藏；`texture-views` 现在也会在发生遮挡时失败，并指出拦截射线的对象，
不会继续生成空白纹理。

## 7. 两个 revision 的差异

|项目|`finger/r01`|`finger-xynova/r01`|
|---|---|---|
|栅格尺寸|3280 × 3200|3700 × 3280|
|固定页面|16.4 × 16.0 mm|18.5 × 16.4 mm|
|`nx`, `ny`|80, 45（16:9 相机）|80, 80（方形相机）|
|seam 边数|32|45|
|自身 hole|0.049 mm²（0.0001）|0.092 mm²（0.00015）|
|`incidence_limit_deg`|62.0；对应旧相机位姿，移动后必须重测|70.0|
|`optics` 配置|无|有|

不能为了让两个 revision 的 YAML 看起来一致，就统一这些值。分辨率、页面、网格比例、相机
位姿和入射角门槛都是各自设计与测量条件的一部分。

## 8. 新同事修改参数时的建议步骤

1. 先确认正在修改哪个 sensor 和 revision，不要把 `finger` 的参数复制到
   `finger-xynova` 后直接使用。
2. 判断改动属于“图案”“UV 布局”“相机位姿”“印刷工艺”还是“几何”。
3. 根据第 5 节查找被改动失效的测量值。
4. 如果移动区域相机，重测 ownership、hole fraction 和自动页面。
5. 如果修改网格，核对拓扑、UV、seam、probe fixture 和 field-domain 相关输出。
6. 如果修改栅格或物理页面，重新计算两个方向的 `px_per_mm`，不能只检查宽度。
7. 运行对应测试并查看生成任务中的 manifest，不要只凭最终图片看起来正常。
8. 将新数值、测量条件、结果和下次失效条件一起更新到本文。

遇到结果异常时，可以按以下顺序排查：

```text
输出为空
  → 是否有重合/遮挡对象
  → region camera 是否能看到表面
  → UV map 名称和对象是否正确

表面有漏印
  → 查看 hole fraction
  → 检查 incidence_limit_deg
  → 检查相机位姿和 footprint 条件

页面比例不对
  → 确认 UV 是 unwrap 还是 Project from View (Bounds)
  → unwrap 使用 fixed；投影视图才使用 auto
  → 检查 raster / px_per_mm / page 的关系

接缝呈阶梯形
  → 先区分 ownership 边界与 gap
  → gap 使用 post_process 只能让退让边变直
  → 平滑 ownership 需要更细的分区算法
```

最后，不要删除“已知缺陷”“撤回结论”和失效条件。这些内容不是历史包袱，而是防止同类问题
再次以合理外观进入生产输出的工程约束。