docs: document nonuniform stamp matching

docs/12-stamp-template-matching.md

@@ -26,7 +26,9 @@ Best match:
 score: 0.9231
 stamp: D:\...\TY037.png
 location: x=412, y=286
-scale: 0.38
+scale_x: 0.38
+scale_y: 0.30
+aspect_y: 0.80
 size: 128x96
 
 Top 5:
@@ -64,6 +66,7 @@ Top 5:
 缺点：
 
 - 对缩放敏感，需要多尺度搜索。
+- 对宽高不等比例变形敏感，例如印花原图 `1000x1000` 合成时被改成 `1000x800`，只做等比例缩放时分数会下降。
 - 对旋转、透视、明显变色不够稳。
 - 背景透明 PNG 需要使用 alpha mask，否则透明区域会干扰分数。
 
@@ -112,7 +115,7 @@ Top 5:
 第一版采用：
 
 ```text
-多尺度模板匹配 + alpha mask + 边缘辅助分数
+多尺度模板匹配 + 有限宽高比变形 + alpha mask + 边缘辅助分数
 ```
 
 处理流程：
@@ -121,21 +124,72 @@ Top 5:
 2. 遍历 `STAMP_DIR` 下所有支持图片。
 3. 对每张印花保留 alpha 通道；如果没有 alpha，则按整张图参与匹配。
 4. 对印花做多尺度缩放，例如 `0.10 ~ 2.00`。
-5. 每个尺度执行一次 `cv2.matchTemplate`：
-   - 原图灰度分数：主分数。
+5. 在每个基础缩放比例上，再尝试有限的宽高比变形，例如：
+
+```text
+aspect_y: 0.60 / 0.70 / 0.80 / 0.90 / 1.00 / 1.10 / 1.20
+scale_x = scale
+scale_y = scale * aspect_y
+```
+
+示例：原印花 `1000x1000`，合成后变为 `1000x800`，可由 `scale_x=1.00`、`scale_y=0.80`、`aspect_y=0.80` 覆盖。
+
+6. 每个 `scale_x / scale_y` 组合执行一次 `cv2.matchTemplate`：
+   - RGB 彩色分数：主分数，比灰度分数更能区分颜色相近但内容不同的印花。
    - alpha mask：忽略透明区域。
    - 边缘图分数：辅助分数。
-6. 计算综合分：
+7. 计算综合分：
 
 ```text
 综合分 = 0.75 * 模板匹配分 + 0.25 * 边缘匹配分
 ```
 
-7. 保存每张印花的最佳结果：分数、位置、缩放比例、匹配尺寸。
-8. 按综合分排序并 `print` Top N。
+8. 保存每张印花的最佳结果：分数、位置、`scale_x`、`scale_y`、`aspect_y`、匹配尺寸。
+9. 按综合分排序并 `print` Top N。
+
+不建议直接暴力搜索完整的 `scale_x × scale_y` 网格，因为运行量会明显放大。优先采用“基础 scale + 少量 aspect_y 候选”的方式，覆盖常见压扁 / 拉伸场景，同时控制耗时。
 
 先不做旋转搜索。若实际发现印花经常旋转，再增加角度搜索，例如 `-30° ~ 30°`，但运行会明显变慢。
 
+### 4.1 宽高不等比例变形说明
+
+合并衣服和印花时，如果用户或模板把印花宽高分别设置为不同数值，原始印花可能发生非等比例变形。例如：
+
+```text
+原始印花：1000x1000
+合成尺寸：1000x800
+```
+
+这种情况下，只搜索单个 `scale` 的版本不够稳。因为等比例搜索只能生成：
+
+```text
+800x800
+1000x1000
+1200x1200
+```
+
+无法直接生成 `1000x800`。因此后续代码应支持独立的 `scale_x` 和 `scale_y`，但搜索范围应保持克制：
+
+- 继续保留基础 `scale`，控制整体尺寸。
+- 增加少量 `aspect_y` 候选，控制高度相对宽度的压缩 / 拉伸。
+- 默认不做所有 `scale_x × scale_y` 组合，避免每张印花匹配次数过多。
+
+输出也应从单一：
+
+```text
+scale: 0.38
+```
+
+改为：
+
+```text
+scale_x: 0.38
+scale_y: 0.30
+aspect_y: 0.80
+```
+
+这样可以直接看出匹配结果是否依赖宽高不等比例变形。
+
 ## 5. 第三方库
 
 最小依赖：
@@ -168,6 +222,7 @@ PIL: 可用
 ## 7. 验收要点
 
 - 给定 `1_TY037.png` 和包含 `TY037.png` 的印花目录，Top 1 应优先命中 `TY037.png`。
-- 能打印 Top N 候选、综合分、模板分、边缘分、匹配坐标、缩放比例。
+- 能打印 Top N 候选、综合分、模板分、边缘分、匹配坐标、`scale_x`、`scale_y`、`aspect_y`。
 - 对透明 PNG 能忽略透明区域，不让透明背景参与匹配。
+- 对 `1000x1000 -> 1000x800` 这类非等比例变形，能通过 `aspect_y=0.80` 附近候选提高匹配稳定性。
 - 找不到可靠匹配时仍打印 Top N，并提示分数偏低，便于人工判断。

tasks.md

@@ -1591,3 +1591,18 @@
 - [x] 找不到高可信结果时打印低分提示；不保存 CSV，不修改任何图片
 - [x] 支持命令行覆盖 `--image`、`--stamp-dir`、`--top`
 - [x] 验证：`python -m py_compile match_stamp.py` 通过；临时构造一张合并图和两个候选印花，Top 1 命中正确印花
+
+### 19.33 合并图印花匹配：宽高不等比例变形方案文档
+
+背景：
+
+实际合成衣服和印花时，印花可能不按原始宽高比缩放。例如原始印花 `1000x1000`，合成到衣服上时被设置为 `1000x800`。这种非等比例变形不是单一 `scale` 能覆盖的，当前脚本只做等比例多尺度搜索时匹配稳定性会下降。
+
+任务：
+
+- [x] 更新 `docs/12-stamp-template-matching.md`，明确 `matchTemplate` 对宽高不等比例变形敏感
+- [x] 将推荐方案扩展为“多尺度模板匹配 + 有限宽高比变形 + alpha mask + 边缘辅助分数”
+- [x] 明确不做完整 `scale_x × scale_y` 暴力搜索，优先用基础 `scale` 加少量 `aspect_y` 候选控制耗时
+- [x] 明确 `1000x1000 -> 1000x800` 可由 `scale_x=1.00`、`scale_y=0.80`、`aspect_y=0.80` 覆盖
+- [x] 更新输出字段建议：从单一 `scale` 改为 `scale_x`、`scale_y`、`aspect_y`
+- [x] 验证：文档路径、标题、示例和验收点检查通过