感知式(YIQ)影像比對含反鋸齒抑制

visual_regression.image_difference 計算原始逐通道最大差像素數,``ssim_compare`` 給出整體結構分數。兩者都未使用 感知式*色彩度量,也都不忽略**反鋸齒邊緣*——那是跨 DPI 與字體微調時視覺比對誤報的首要來源。perceptual_diff 在 YIQ 空間比較像素(pixelmatch 的色彩度量,比 RGB 更接近人眼感知),並預設移除反鋸齒造成的單像素細邊差異 (形態學開運算),因此只計算*實心*變化區域。

在可注入的影像配對(ndarray / 路徑 / PIL)上執行,因此可對合成陣列做無頭測試。OpenCV + NumPy 透過 je_open_cv 引入;沿用共用的連通元件輔助與 RGB 載入器。不匯入 PySide6。

無頭 API

from je_auto_control import perceptual_diff, assert_perceptual

result = perceptual_diff("actual.png", "golden.png", threshold=0.1)
print(result.diff_pixels, result.diff_ratio, result.regions)

# 把關視覺回歸測試(超出比例則拋例外)。
assert_perceptual("actual.png", "golden.png", max_diff_ratio=0.01)

perceptual_diff 回傳 PerceptualDiffResult``(``diff_pixels、total_pixels、diff_ratio,以及變化叢集 的 regions 方框)。threshold``(0..1)是 pixelmatch 靈敏度。``include_aa=True 會保留細邊差異而不抑制。 assert_perceptual 在 diff_ratio 超過 max_diff_ratio 時丟出 AutoControlActionException。不同尺寸的 影像會丟出 ValueError。

執行器命令

AC_perceptual_diff``(``actual / expected / threshold / include_aa / max_diff_ratio → {diff_pixels, total_pixels, diff_ratio, regions};給定 max_diff_ratio 且超出時拋例外)。它以 MCP 工具 ac_perceptual_diff 以及 Script Builder 中 Image 分類下的命令提供。