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，并提示分数偏低，便于人工判断。