結構相似度(SSIM)比較

框架已能以原始像素差(diff_screenshots)與顏色直方圖(detect_drift)比較畫面——但兩者都不是*結構性*的。 像素差會因為一像素位移或人眼會忽略的亮度變化而誤報;直方圖則對版面無感(把畫面左右兩半互換,它毫無變化)。 SSIM 是標準的視覺回歸度量:容忍輕微光照變化,對結構變化(文字被編輯、元素移動或消失)敏感。ssim_compare 回傳單一 0..1 分數,``ssim_changed_regions`` 則回傳*哪裡*真正變了的方框。

它是純 NumPy + OpenCV 實作(不需 scikit-image),在可注入的影像配對上執行,因此可在無真實螢幕下對合成陣列做 單元測試。OpenCV + NumPy 透過 je_open_cv 引入。不匯入 PySide6。

無頭 API

from je_auto_control import ssim_compare, ssim_changed_regions

# 以黃金截圖把關視覺回歸測試。
score = ssim_compare("golden.png")           # current = 實際螢幕
assert score > 0.98

# 忽略即時時鐘 / 閃爍游標,再列出哪裡移動了。
for box in ssim_changed_regions("golden.png", ignore=[[0, 0, 120, 30]]):
    print(box["x"], box["y"], box["width"], box["height"])

ssim_compare 回傳整張影像的平均 SSIM(1.0 = 完全相同);``current`` 預設為對選用 region 的螢幕擷取。 ignore 是一組從分數與變化偵測中排除的 [x, y, w, h] 方框。ssim_changed_regions 標記局部不相似度 1 - SSIM 超過 threshold 的像素,將相連者(min_area 以上)分群,回傳 {x, y, width, height, area, center},由大到小。比較兩張不同尺寸的影像會丟出 ValueError。

執行器命令

AC_ssim_compare``(``reference / current / ignore / region → {score})與 AC_ssim_changed_regions``(另有 ``threshold / min_area → {count, regions})。它們以 MCP 工具 ac_ssim_compare / ac_ssim_changed_regions 以及 Script Builder 中 Image 分類下的命令提供。