ImageOpsAHK：基于 ImagePut 的图片处理业务封装

AHK 做自动化时，截图和图片处理非常常见：保存失败现场、裁剪界面区域、给报告图片加水印、把多张截图拼成对比图、批量压缩图片。单个功能看起来不难，但项目里写多了以后，代码很容易散。

ImageOpsAHK 是我基于 ImagePut.ahk 整理的一层业务封装。底层图片读取、保存、截图、剪贴板、窗口图像这些能力仍然交给 ImagePut；ImageOpsAHK 负责把日常自动化里反复用到的流程封成更顺手的函数。

它不是替代 ImagePut

这一点要先说清楚。ImagePut 本身已经很强，ImageOpsAHK 不重复造底层轮子。这个库更像“工作流工具箱”：截图、裁剪、缩放、水印、拼图、差异报告、失败现场包。

所以使用时建议把两个库都放好，并按顺序引入：

#Requires AutoHotkey v1.1
#Include <ImagePut>
#Include <ImageOpsAHK>

ImageOps_CaptureScreen([0, 0, 900, 520], "截图.png")
ImageOps_WatermarkText("截图.png", "ahk66 自动化截图", {"Anchor": "br"}, "水印.png")

常用场景

• 自动化脚本失败时，保存当前页面截图和说明文件。
• 把操作步骤截图裁剪成统一尺寸，放进 Word 或网页报告。
• 给一批截图加水印，方便归档和分享。
• 比较两张截图是否发生变化，做简单 UI 回归检查。
• 批量压缩、转格式、生成缩略图。

几个我觉得实用的函数

输出目录 := A_ScriptDir . "\示例输出"
FileCreateDir, %输出目录%

屏幕截图 := 输出目录 . "\01_屏幕截图.png"
ImageOps_CaptureScreen([0, 0, 900, 520], 屏幕截图)

裁剪缩放图 := 输出目录 . "\02_裁剪并缩放.jpg"
ImageOps_CropResize(屏幕截图, [0, 0, 520, 300], 0.7, 裁剪缩放图, 88)

水印图 := 输出目录 . "\03_添加中文水印.png"
ImageOps_WatermarkText(屏幕截图, "ahk66 自动化截图 " . A_Now, {"Anchor": "br", "FontSize": 26}, 水印图)

拼接图 := 输出目录 . "\04_横向拼接对比.png"
ImageOps_StackHorizontal([裁剪缩放图, 水印图], 12, 16, 拼接图)

失败现场包

我个人比较喜欢这个功能。很多脚本出错时，只弹一个 MsgBox，事后根本不知道当时界面是什么状态。把截图、缩略图、文字信息放到同一个目录，排查问题会轻松很多。

pack := ImageOps_SaveFailurePack("页面截图.png"
    , A_ScriptDir . "\失败现场"
    , "页面断言失败"
    , {"URL": "https://example.com", "原因": "按钮没有出现"})

MsgBox, % pack.folder

适合和不适合

它适合办公自动化、UI 自动化、截图归档、报告插图、批量图片处理。不适合当 OCR、OpenCV、专业修图软件来用。如果目标是识别复杂图像内容，那应该考虑 FindText、WinCapture、OpenCV 或 OCR；如果只是把截图整理得更规范，ImageOpsAHK 就很合适。

示例和打包库【包含1.1.33.10可用的ImagePut库】的下载地址：

demo代码片段展示：

#NoEnv
#SingleInstance Force
SetBatchLines -1
#Include <ImagePut>
#Include <ImageOpsAHK>
输出目录 := A_ScriptDir . "\示例输出"
FileCreateDir, %输出目录%

; 1. 截取当前屏幕左上角区域，保存为 PNG。
屏幕截图 := 输出目录 . "\01_屏幕截图.png"
ImageOps_CaptureScreen([0, 0, 900, 520], 屏幕截图)

; 2. 在截图上裁剪左上角区域，并缩放成更小的预览图。
裁剪缩放图 := 输出目录 . "\02_裁剪并缩放.jpg"
ImageOps_CropResize(屏幕截图, [0, 0, 520, 300], 0.7, 裁剪缩放图, 88)

; 3. 给图片添加中文水印，适合截图归档、报告插图、失败现场标记。
水印图 := 输出目录 . "\03_添加中文水印.png"
ImageOps_WatermarkText(屏幕截图, "ahk66 自动化截图 " . A_Now, {"Anchor": "br", "FontSize": 26}, 水印图)

; 4. 把多张图片横向拼接，适合做前后对比图、步骤说明图。
拼接图 := 输出目录 . "\04_横向拼接对比.png"
ImageOps_StackHorizontal([裁剪缩放图, 水印图], 12, 16, 拼接图, 92, 0xFFF5F5F5)

; 5. 旋转、翻转和等比适配，适合统一报告插图尺寸。
旋转图 := 输出目录 . "\05_旋转90度.png"
ImageOps_Rotate(裁剪缩放图, 90, 旋转图)

翻转图 := 输出目录 . "\06_水平翻转.png"
ImageOps_Flip(裁剪缩放图, "horizontal", 翻转图)

报告适配图 := 输出目录 . "\07_等比适配到800x600报告图.jpg"
ImageOps_FitCanvas(屏幕截图, [800, 600], 报告适配图, 88, 0xFFFFFFFF)

预览封面图 := 输出目录 . "\08_裁切填满800x600预览图.jpg"
ImageOps_Fit(屏幕截图, [800, 600], 预览封面图, 88, "", "cover")

; 6. 图片叠加和 Logo 水印：先从截图做一个小 Logo，再半透明贴到右上角。
Logo图 := 输出目录 . "\09_示例Logo小图.png"
ImageOps_CropResize(屏幕截图, [0, 0, 260, 120], [160, 74], Logo图)

Logo水印图 := 输出目录 . "\10_图片叠加Logo水印.png"
ImageOps_WatermarkImage(屏幕截图, Logo图, {"Anchor": "tr", "Padding": 24, "Opacity": 0.55, "Width": 180}, Logo水印图)

指定坐标叠加图 := 输出目录 . "\11_指定坐标叠加图片.png"
ImageOps_Overlay(屏幕截图, Logo图, {"X": 40, "Y": 40, "Opacity": 0.72, "Width": 180}, 指定坐标叠加图)

; 7. 差异报告：输出差异图和差异百分比，适合网页截图回归测试。
差异图 := 输出目录 . "\12_图片差异报告_红色为差异.png"
差异结果 := ImageOps_DiffReport(屏幕截图, 水印图, 差异图)

; 8. 批量处理目录：准备几张输入图，然后批量压缩、转格式、加水印、生成缩略图。
批处理输入目录 := 输出目录 . "\13_批处理输入"
批量压缩目录 := 输出目录 . "\14_批量压缩输出"
批量转格式目录 := 输出目录 . "\15_批量转jpg输出"
批量水印目录 := 输出目录 . "\16_批量加水印输出"
批量缩略图目录 := 输出目录 . "\17_批量缩略图输出"
FileCreateDir, %批处理输入目录%
FileCopy, %屏幕截图%, %批处理输入目录%\屏幕截图.png, 1
FileCopy, %水印图%, %批处理输入目录%\水印图.png, 1
FileCopy, %Logo水印图%, %批处理输入目录%\Logo水印图.png, 1

批量压缩 := ImageOps_BatchCompress(批处理输入目录, 批量压缩目录, 76, {"Recursive": false, "Suffix": "_压缩"})
批量转格式 := ImageOps_BatchConvert(批处理输入目录, 批量转格式目录, "jpg", 86, {"Recursive": false, "Suffix": "_转jpg"})
批量水印 := ImageOps_BatchWatermark(批处理输入目录, 批量水印目录, "ahk66 批量水印", {"Anchor": "br", "FontSize": 22}, {"Recursive": false, "Suffix": "_水印"})
批量缩略图 := ImageOps_BatchThumbnail(批处理输入目录, 批量缩略图目录, [320, 180], {"Recursive": false, "Suffix": "_缩略图", "Extension": "jpg", "BgColor": 0xFFFFFFFF})

; 9. 比较两张图片是否完全一致，适合 UI 自动化验收里的像素级判断。
比较结果 := ImageOps_Compare(屏幕截图, 水印图)

; 10. 打包失败现场：原图、缩略图、文字信息放到同一个目录。
失败包目录 := 输出目录 . "\18_失败现场包"
失败包 := ImageOps_SaveFailurePack(水印图, 失败包目录, "页面断言失败", {"页面": "demo.ahk", "原因": "演示截图打包", "图片相同": 比较结果.equal})

提示 := "ImageOpsAHK 示例生成完成！`n`n"
提示 .= "屏幕截图：" . 屏幕截图 . "`n"
提示 .= "裁剪缩放：" . 裁剪缩放图 . "`n"
提示 .= "中文水印：" . 水印图 . "`n"
提示 .= "横向拼接：" . 拼接图 . "`n"
提示 .= "旋转/翻转/报告适配：" . 旋转图 . " / " . 翻转图 . " / " . 报告适配图 . "`n"
提示 .= "Logo叠加：" . Logo水印图 . "`n"
提示 .= "差异报告：" . 差异图 . "，差异比例 " . 差异结果.diffPercent . "%`n"
提示 .= "批量压缩：" . 批量压缩目录 . "（成功 " . 批量压缩.ok . "）`n"
提示 .= "批量转jpg：" . 批量转格式目录 . "（成功 " . 批量转格式.ok . "）`n"
提示 .= "批量加水印：" . 批量水印目录 . "（成功 " . 批量水印.ok . "）`n"
提示 .= "批量缩略图：" . 批量缩略图目录 . "（成功 " . 批量缩略图.ok . "）`n"
提示 .= "失败现场包：" . 失败包.folder . "`n`n"
提示 .= "图片比较结果：" . (比较结果.equal ? "完全一致" : "不一致") . "（" . 比较结果.reason . "）"

MsgBox, 64, ImageOpsAHK 示例, %提示%
Run, %输出目录%
return