386 lines
11 KiB
Plaintext
386 lines
11 KiB
Plaintext
# MainShell/Process/DieTransfer/Planning 说明与代码审阅
|
||
|
||
## 1. 范围
|
||
本次说明覆盖 `MainShell/Process/DieTransfer/Planning` 目录下的规划相关实现，包含以下文件：
|
||
|
||
- `DieTransferPathGenerator.cs`
|
||
- `DieTransferPlanningContext.cs`
|
||
- `DieTransferPathRequest.cs`
|
||
- `DieTransferPathPlan.cs`
|
||
- `DieTransferPathRegionPlan.cs`
|
||
- `DieTransferPathStep.cs`
|
||
- `DieTransferRegion.cs`
|
||
- `DieTransferRow.cs`
|
||
- `PadTransferRow.cs`
|
||
- `DieTransferRowDirection.cs`
|
||
- `SubstrateRowDirectionStrategy.cs`
|
||
- `IDieTransferPathGenerator.cs`
|
||
|
||
## 2. 模块定位
|
||
该模块是 Die Transfer 的“规划层”，职责不是执行运动，而是把候选 Die 集合和候选 Pad 集合转换成一份可执行的路径计划。
|
||
|
||
输入侧负责提供：
|
||
|
||
- 候选 Die 集合
|
||
- 候选 Pad 集合
|
||
- Die 区域
|
||
- Substrate 区域
|
||
- 路径生成策略
|
||
- 是否跳过 NG Die
|
||
- 基板行方向策略
|
||
|
||
输出侧负责提供：
|
||
|
||
- 已生成的配对步骤 `Steps`
|
||
- 过滤后的可用 Die / Pad 数量
|
||
- 剩余未配对的 Die / Pad
|
||
- 剩余区域的行结构和区域边界
|
||
|
||
整体设计是合理的：规划逻辑与运动执行解耦，后续无论手动模式还是自动流程，都可以复用同一套路径生成器。
|
||
|
||
## 3. 核心对象职责
|
||
|
||
### 3.1 `DieTransferPathRequest`
|
||
路径规划输入对象。
|
||
|
||
关键字段：
|
||
|
||
- `DieCandidates`：候选 Die 集合
|
||
- `PadCandidates`：候选 Pad 集合
|
||
- `DieRegion`：Die 过滤区域
|
||
- `SubstrateRegion`：Pad 过滤区域
|
||
- `TransPathType`：路径生成模式
|
||
- `SubstrateRowDirectionStrategy`：Pad 行遍历方向
|
||
- `SkipNgDie`：是否跳过 NG Die
|
||
|
||
默认值设置比较合理：
|
||
|
||
- 默认模式是 `Sequence`
|
||
- 默认 Pad 行方向是 `AllPositive`
|
||
- 默认跳过 NG Die
|
||
|
||
### 3.2 `DieTransferPlanningContext`
|
||
这是当前模块最核心的中间对象。它的作用不是对外暴露，而是把 request 预处理成“可直接生成路径”的内部上下文。
|
||
|
||
它主要做三件事：
|
||
|
||
1. 把 `RegionModel` 转成内部使用的 `DieTransferRegion`
|
||
2. 把原始候选点整理成按行分组的 `DieTransferRow` / `PadTransferRow`
|
||
3. 根据行方向规则，把每一行的点组织成确定顺序
|
||
|
||
换句话说，真正的“排序、过滤、按行组织”都不在 generator 本体里，而是在 context 创建阶段完成。
|
||
|
||
### 3.3 `DieTransferPathGenerator`
|
||
路径生成入口。
|
||
|
||
对外现有四个方法：
|
||
|
||
- `Generate()`：返回 `DieTransferPathPlan`
|
||
- `GenerateByRegion()`：返回 `DieTransferPathRegionPlan`
|
||
- `GenerateByCandidates()`：根据传入的 Pad 集合和 Die 集合生成 `DieTransferPathRegionPlan`
|
||
- `GenerateByRows()`：根据传入的 `PadTransferRow` / `DieTransferRow` 直接生成 `DieTransferPathRegionPlan`
|
||
|
||
其中 `Generate()` 实际只是转调 `GenerateByRegion()`，只是把返回类型收窄成基类。因此：
|
||
|
||
- 如果调用方只关心步骤列表和统计信息，用 `Generate()` 即可
|
||
- 如果调用方还关心剩余 Die / Pad 和剩余区域，应该使用 `GenerateByRegion()`
|
||
|
||
两个新增入口的定位如下：
|
||
|
||
- `GenerateByCandidates()`：适合调用方手里只有原始候选点集合，但不想自己组装 `DieTransferPathRequest` 的场景。该方法内部仍会走现有的 request/context 预处理逻辑，生成的路径统一从返回结果的 `Steps` 中获取。
|
||
- `GenerateByRows()`：适合调用方已经完成按行分组、方向整理、NG 过滤策略配置的场景。该方法不会重新构建 planning context，而是直接把传入行展开为有序 Die / Pad，再生成步骤和剩余区域。
|
||
|
||
### 3.4 `DieTransferPathPlan` / `DieTransferPathRegionPlan`
|
||
`DieTransferPathPlan` 表示基础规划结果，包含：
|
||
|
||
- `TransPathType`
|
||
- `Steps`
|
||
- `AvailableDieCount`
|
||
- `AvailablePadCount`
|
||
- `GeneratedStepCount`
|
||
|
||
`DieTransferPathRegionPlan` 在此基础上扩展了剩余信息：
|
||
|
||
- `RemainingDies`
|
||
- `RemainingPads`
|
||
- `RemainingDieRows`
|
||
- `RemainingPadRows`
|
||
- `RemainingDieRegion`
|
||
- `RemainingSubstrateRegion`
|
||
|
||
这意味着该模块不仅能生成一次路径，还能给下一轮继续规划留下上下文。
|
||
|
||
### 3.5 `DieTransferPathStep`
|
||
单步配对结果对象，记录：
|
||
|
||
- 步序号 `StepIndex`
|
||
- Die 行列和坐标
|
||
- Pad 行列和坐标
|
||
- 当前路径类型
|
||
|
||
这个对象设计得比较直接，后续 UI 或执行层都容易消费。
|
||
|
||
## 4. 生成方法总流程
|
||
路径生成的主流程如下：
|
||
|
||
1. 调用方构造 `DieTransferPathRequest`
|
||
2. `DieTransferPathGenerator.GenerateByRegion()` 校验 request 非空
|
||
3. `DieTransferPlanningContext.Create(request)` 生成规划上下文
|
||
4. 从 context 中取出有序的 Die 列表和 Pad 列表
|
||
5. 按 `TransPathType` 选择生成策略
|
||
6. 生成 `DieTransferPathStep` 列表
|
||
7. 计算未参与配对的剩余 Die / Pad
|
||
8. 计算剩余行结构和剩余区域
|
||
9. 组装 `DieTransferPathRegionPlan` 返回
|
||
|
||
可以把它理解为两段式流程：
|
||
|
||
- 第一段：预处理输入，得到稳定顺序
|
||
- 第二段：按策略做 Die 与 Pad 的一一配对
|
||
|
||
新增的两个入口，本质上只是改变“输入落点”，不改变“路径生成算法”：
|
||
|
||
- `GenerateByCandidates()`：从候选集合进入，再复用 `GenerateByRegion()` 的完整流程
|
||
- `GenerateByRows()`：跳过 request/context 构建，直接从行对象展开为有序点集合后进入配对阶段
|
||
|
||
## 5. 预处理阶段讲解
|
||
|
||
### 5.1 区域过滤
|
||
`DieTransferPlanningContext.Create()` 首先把 `request.DieRegion` 和 `request.SubstrateRegion` 转成 `DieTransferRegion`。
|
||
|
||
`DieTransferRegion.Contains(row, column)` 负责判断点是否落在区域内。
|
||
|
||
当前语义如下：
|
||
|
||
- 区域不为空：按区域过滤
|
||
- 区域为空：视为不过滤，所有候选点均可参与规划
|
||
|
||
这一点在实现上是清晰的，但最好在文档或接口注释中明确说明，因为这是一个业务约定。
|
||
|
||
### 5.2 按行分组
|
||
Pad 和 Die 都不是直接整体排序，而是先按 `Row` 分组，再在每一行内部决定遍历方向。
|
||
|
||
Pad 通过 `CreatePadRows()` 生成 `PadTransferRow`：
|
||
|
||
- 先过滤空对象和区域外点
|
||
- 按 `Row` 分组
|
||
- 每组按 `Column` 升序保存原始集合
|
||
- 再根据策略决定当前行最终读取方向
|
||
|
||
Die 通过 `CreateDieRows()` 生成 `DieTransferRow`：
|
||
|
||
- 先过滤空对象和区域外点
|
||
- 按 `Row` 分组
|
||
- 每组按 `Column` 升序保存
|
||
- 行方向固定按蛇形方式决定
|
||
- `SkipNgDie` 在行对象中生效
|
||
|
||
### 5.3 行方向规则
|
||
Pad 的行方向由 `SubstrateRowDirectionStrategy` 决定：
|
||
|
||
- `AllPositive`：所有行都从小列到大列
|
||
- `AllNegative`：所有行都从大列到小列
|
||
- `Serpentine`：奇数行正向，偶数行反向
|
||
|
||
Die 的行方向当前固定采用蛇形规则，因为 `CreateDieRows()` 被调用时 `useSerpentineDirection` 固定传入 `true`：
|
||
|
||
- 奇数行正向
|
||
- 偶数行反向
|
||
|
||
这意味着当前设计里，Die 的遍历顺序比 Pad 更“强约束”，调用方无法在 request 中单独配置 Die 行方向。
|
||
|
||
### 5.4 可用点提取
|
||
在分组完成后，context 通过以下方法展平成最终有序列表：
|
||
|
||
- `GetOrderedPads()`
|
||
- `GetOrderedDies()`
|
||
|
||
这两个方法都会按 `RowIndex` 升序遍历各行，再拼接每行的可用点序列。
|
||
|
||
其中 Die 侧的“可用”还额外受 `SkipNgDie` 影响：
|
||
|
||
- `SkipNgDie = true` 时，`DieStatus.Ng` 会被排除
|
||
- `SkipNgDie = false` 时，所有 Die 都会参与规划
|
||
|
||
因此，后续真正参与生成的并不是 request 里的原始候选集合，而是“经过区域过滤、方向排序、NG 过滤后的线性序列”。
|
||
|
||
## 6. 两种生成方法讲解
|
||
|
||
### 6.1 顺序生成 `BuildSequenceSteps`
|
||
这是最直接的策略。
|
||
|
||
处理方式：
|
||
|
||
1. 先得到 `orderedDies` 和 `orderedPads`
|
||
2. 取 `Math.Min(dies.Count, pads.Count)` 作为可生成步数
|
||
3. 第 `i` 个 Die 与第 `i` 个 Pad 直接配对
|
||
4. 调用 `CreateStep()` 生成步骤对象
|
||
|
||
伪代码如下：
|
||
|
||
```text
|
||
stepCount = min(orderedDies.Count, orderedPads.Count)
|
||
for i in [0 .. stepCount - 1]
|
||
step = CreateStep(i + 1, orderedDies[i], orderedPads[i])
|
||
steps.Add(step)
|
||
```
|
||
|
||
该策略的特点是：
|
||
|
||
- 完全依赖预处理后的顺序
|
||
- 算法简单，复杂度低
|
||
- 结果稳定，便于追溯
|
||
- 不考虑实际几何距离，只考虑排好序后的对应关系
|
||
|
||
适用场景：
|
||
|
||
- 生产节拍更看重顺序一致性
|
||
- 上游已经保证 Die / Pad 序列一一对应
|
||
- 希望路径可预测、容易校验和复现
|
||
|
||
### 6.2 最近生成 `BuildNearestSteps`
|
||
这是更偏几何优化的策略。
|
||
|
||
处理方式：
|
||
|
||
1. 先复制一份 `remainingDies`
|
||
2. 按 Pad 的既定顺序逐个处理每个 Pad
|
||
3. 在当前剩余 Die 中，找出距离该 Pad 最近的 Die
|
||
4. 生成一步配对后，把该 Die 从 `remainingDies` 中移除
|
||
5. 继续处理下一个 Pad，直到 Die 用完或 Pad 遍历完毕
|
||
|
||
伪代码如下：
|
||
|
||
```text
|
||
remainingDies = orderedDies
|
||
for each pad in orderedPads
|
||
if remainingDies is empty
|
||
break
|
||
|
||
die = SelectNearestDie(pad, remainingDies)
|
||
steps.Add(CreateStep(stepIndex, die, pad))
|
||
remainingDies.Remove(die)
|
||
stepIndex++
|
||
```
|
||
|
||
这个策略不是全局最优匹配，而是“按 Pad 顺序逐个贪心选择最近 Die”。
|
||
|
||
它的优点是：
|
||
|
||
- 实现简单
|
||
- 对局部移动距离有优化作用
|
||
- 比完全顺序配对更贴近空间位置
|
||
|
||
它的限制也很明确：
|
||
|
||
- 它不是匈牙利算法一类的全局最优解
|
||
- 前面 Pad 的选择会影响后面 Pad 的可选 Die
|
||
- 最终总路程不一定最短
|
||
|
||
因此，这个“最近策略”更准确的表述应该是：
|
||
|
||
- 按 Pad 顺序执行的局部贪心最近匹配
|
||
|
||
### 6.3 最近 Die 的选取规则 `SelectNearestDie`
|
||
`SelectNearestDie()` 遍历当前所有剩余 Die，并选择距离最小的那个。
|
||
|
||
当前距离计算公式为：
|
||
|
||
```text
|
||
(die.X - pad.X)^2 + (die.Y - pad.Y)^2
|
||
```
|
||
|
||
这里返回的是平方距离，而不是开方后的欧氏距离。对于“比较谁更近”这个问题，平方距离是等价的，且计算更省。
|
||
|
||
需要注意两点：
|
||
|
||
1. `CalculateDistance()` 这个命名不够精确，实际更像 `CalculateSquaredDistance()`
|
||
2. 当距离相等时，当前代码按“先遍历到谁就保留谁”处理
|
||
|
||
第二点尤其需要讲清楚：
|
||
|
||
- 当前 tie-break 不是直接按 `Row`、`Column` 比较
|
||
- 它依赖 `remainingDies` 的当前顺序
|
||
- 而 `remainingDies` 的顺序，又来自 Die 行的蛇形组织结果
|
||
|
||
也就是说，当两个 Die 与同一个 Pad 等距时，最终胜出者本质上由“Die 预处理后的线性顺序”决定。
|
||
|
||
## 7. 剩余结果的生成方式
|
||
路径步骤生成完成后，`GenerateByRegion()` 还会继续做一层“剩余状态提取”。
|
||
|
||
对新增入口来说，剩余结果生成规则分别是：
|
||
|
||
- `GenerateByCandidates()`：与 `GenerateByRegion()` 完全一致，因为内部就是组装 request 后复用区域入口
|
||
- `GenerateByRows()`：保留调用方传入行对象中的 `RowIndex`、`Direction`、`SkipNgDie` 等行级配置，只过滤掉本轮已使用点位，再构造 `RemainingPadRows` / `RemainingDieRows`
|
||
|
||
### 7.1 剩余 Die / Pad 计算
|
||
通过 `CreateRemainingPads()` 和 `CreateRemainingDies()`：
|
||
|
||
- 从步骤列表中提取已经使用过的 `(row, column)` 键
|
||
- 对原有有序集合做差集
|
||
- 得到未参与本轮规划的点
|
||
|
||
这里使用 `(row, column)` 作为唯一键，说明当前模块默认一个点位由行列唯一标识。
|
||
|
||
### 7.2 剩余行结构重建
|
||
剩余 Pad / Die 并不只是简单返回列表，还会重新生成：
|
||
|
||
- `RemainingPadRows`
|
||
- `RemainingDieRows`
|
||
|
||
这非常有价值，因为后续如果要做二次规划，不需要重新整理全部数据结构。
|
||
|
||
### 7.3 剩余区域重建
|
||
`CreateRegionFromPads()` 和 `CreateRegionFromDies()` 会根据剩余点重新计算最小包围区域：
|
||
|
||
- 最小行
|
||
- 最小列
|
||
- 最大行
|
||
- 最大列
|
||
|
||
如果没有剩余点，则返回 `null`。
|
||
|
||
这个设计能让调用方快速判断：
|
||
|
||
- 当前是否已全部规划完成
|
||
- 还剩下哪一片区域未处理
|
||
|
||
## 8. 代码审阅结论
|
||
|
||
### 8.1 优点
|
||
该模块的优点比较明确：
|
||
|
||
- 职责单一，专注于规划而非执行
|
||
- request / context / result 三层结构清楚
|
||
- 顺序策略和最近策略边界明确
|
||
- 剩余区域输出增强了复用性
|
||
- 代码整体可读性较好，扩展入口也比较清晰
|
||
|
||
### 8.2 需要注意的点
|
||
当前实现没有明显功能性缺陷，但有几个维护层面的注意点：
|
||
|
||
1. `CalculateDistance()` 实际是平方距离，建议改名或补注释
|
||
2. 最近策略是局部贪心，不是全局最优匹配，建议在文档中明确
|
||
3. 等距时的选择规则依赖 Die 预处理顺序，建议明确写入说明
|
||
4. `AvailableDieCount` / `AvailablePadCount` 表示过滤后的可用数量，不是原始候选数
|
||
5. 区域为 `null` 时表示不过滤，这属于隐式约定，建议补充说明
|
||
6. `Generate()` 返回基类，但实际内部生成的是区域计划对象，调用方需明确自己是否需要剩余区域信息
|
||
|
||
### 8.3 可改进但不必立即重构的点
|
||
以下问题存在，但不建议为此做大改：
|
||
|
||
- 结果对象是可写模型，存在被外部修改的可能
|
||
- `DieTransferPathGenerator` 中保留了未被使用的 `OrderDies()` / `OrderPads()` 私有方法，可在后续清理
|
||
- 命名空间仍统一使用 `MainShell.Process`，与目录层次不是完全一一对应，但符合当前仓库惯例
|
||
|
||
## 9. 总结
|
||
Planning 模块的核心思路可以概括为一句话：
|
||
|
||
先把候选 Die / Pad 依据区域、行方向、NG 过滤整理成稳定顺序，再按“顺序配对”或“局部贪心最近配对”生成 `DieTransferPathStep` 列表，最后补充剩余点和剩余区域信息。
|
||
|
||
如果从可维护性看，这套实现已经具备较好的基础。当前更需要的是把策略语义讲清楚，而不是立即做结构性重构。尤其是以下三点，建议作为后续文档或注释的固定说明：
|
||
|
||
- 最近模式是局部贪心，不是全局最优
|
||
- 距离比较使用平方距离
|
||
- 等距时遵循 Die 预处理后的先后顺序
|