# ImageSearch

在屏幕的某个区域中搜索图像.

    ImageSearch &OutputVarX, &OutputVarY, X1, Y1, X2, Y2, ImageFile

## 参数

&OutputVarX, &OutputVarY

  类型: VarRef

  用来保存在屏幕上找到的图像的左上角像素的 X 和 Y 坐标的变量的引用(如果没有找到匹配, 则这两个变量被置空). 坐标相对于活动窗口, 除非曾使用 CoordMode 改变了这个设置.

X1, Y1

  类型: 整数

  要搜索的矩形区域的左上角的 X 和 Y 坐标. 坐标相对于活动窗口, 除非曾使用 CoordMode 改变了这个设置.

X2,Y2

  类型: 整数

  要搜索的矩形区域的右下角的 X 和 Y 坐标. 坐标相对于活动窗口, 除非曾使用 CoordMode 改变了这个设置.

ImageFile

  类型: 字符串

  图像文件名, 如果未指定绝对路径, 则假定在 A_WorkingDir 中. 支持的图片格式包括 ANI, BMP, CUR, EMF, Exif, GIF, ICO, JPG, PNG, TIF 和 WMF(BMP 图像必须为 16 位或更高). 图标的其他来源包括以下类型的文件: EXE, DLL, CPL, SCR 和其他包含图标资源的类型.

  选项: 在文件名前面可以直接添加零个或多个下列字符串. 在选项间使用单个空格或 tab 分隔. 例如: `"*2 *w100 *h-1 C:\Main Logo.bmp"`.

  *IconN: 要使用文件中第一个图标以外的图标组, 请指定 `*Icon` 后紧跟着图标组编号. 例如, `*Icon2` 将加载第二个图标组中的默认图标.

  *n(渐变值): 指定 n 为介于 0 和 255(包含) 之间的数字, 用于表示每个像素颜色红/绿/蓝通道强度在任一方向上允许的渐变值. 例如, 如果指定了 `*2`, 并且像素的颜色是 0x444444, 那么从 0x424242 到 0x464646 的任何颜色都将被视为匹配. 此参数可用于图像的颜色轻微变化或 ImageFile 使用的格式(例如 GIF 或 JPG) 不能准确地在屏幕上表示图像. 如果指定 255 为渐变值, 则匹配所有颜色. 默认渐变值为 0.

  *TransN: 此选项通过指定图像内的某种颜色能匹配屏幕上的任何颜色, 使得更容易找到匹配. 它常用于寻找含有透明区域的 PNG, GIF 和 TIF 文件(然而, 对于图标则不需要此选项, 因为它们的透明度是自动支持的). 对于 GIF 文件, `*TransWhite` 很可能会有用. 对于 PNG 和 TIF 文件, `*TransBlack` 可能是最佳的. 否则, 指定 N 为其他颜色名称或 RGB 值(有关详情, 请参阅颜色图表, 或使用 PixelGetColor 的 RGB 模式). 例如: `*TransBlack`, `*TransFFFFAA`, `*Trans0xFFFFAA`.

  *wn 和 *hn: 用于缩放图像尺寸的宽度和高度(此宽度和高度也决定了从多图标的 .ICO 文件中加载哪个图标). 如果同时省略这两个选项, 则把从 ICO, DLL 或 EXE 文件中加载的图标调整到系统默认的小图标大小, 通常为 16X16(通过指定 `*w0 *h0` 您可以强制使用实际/内部的大小). 图标外的其他图像以它们的实际大小加载. 要保持高宽比来缩放图像, 请在其中一个尺寸中指定 -1, 而在另一个中指定正数. 例如, 指定 `*w200 *h-1` 将缩放图像到 200 像素的宽度同时自动设置其高度.

  位图或图标句柄可用于替代文件名. 例如, `"HBITMAP:*" handle`.

## 返回值

类型: 整数(布尔值)

如果在指定的区域内找到了图像, 该函数返回 1(true), 如果没有找到, 则返回 0(false).

## 错误处理

如果检测到无效的参数或图像无法加载, 则抛出 ValueError.

如果内部函数调用失败, 则抛出 OSError.

## 备注

ImageSearch 可以用来检测屏幕上缺少文本或文本不容易被检索的图形对象. 例如, 它可以用来查找图片按钮, 图标, 网页链接, 或游戏对象的位置. 一旦找到了这些对象, 就可以通过Click 来点击.

在有些时候有用的一个策略是搜索图像中的一小块剪辑而不是整个图像. 此方法可以在图像整体发生变化而其内部某些部分保持不变时提高可靠性. 提取剪辑的一种方法是:

1. 在活动窗口中图像可见时按下 `Alt`+`PrtScr`. 这样把屏幕截图放在了剪贴板中.
2. 打开图像处理程序, 例如 Paint.
3. 粘贴剪贴板的内容(即屏幕截图).
4. 选择对图像而言唯一且不变的区域.
5. 复制并粘贴那个区域到新的图像文档.
6. 保存为小文件供 ImageSearch 使用.

要实现匹配, 屏幕上的图像必须与通过 ImageFile 参数及其选项加载的图像具有相同的尺寸.

要搜索的目标区域必须是可见的; 换句话说, 无法搜索隐藏在其他窗口背后的窗口区域. 与之相比, 部分在鼠标光标下方的图像通常可以检测出来. 例外情况是游戏的指针, 在大多数情况下它会遮住在它下方的任何图像.

由于搜索从目标区域的顶行开始往下, 所以如果有多个匹配, 则会找到最接近顶部的那个.

包含透明色的图标会自动允许那个颜色匹配屏幕上的任何颜色. 因此, 在图标后的颜色是不重要的.

ImageSearch 支持 8 位色(256 色) 或更高的屏幕.

搜索行为可能会因显示适配器的颜色深度而变化(尤其对于 GIF 和 JPG 文件). 因此, 如果脚本会在多种颜色深度下运行, 最好在每种深度设置下进行测试. 您可以使用渐变选项(*n) 来辅助协调在多种颜色深度下的搜索行为.

如果屏幕上的图像是半透明的, 则 ImageSearch 很可能无法找到它. 要避免此问题, 请尝试渐变选项(*n) 或使用 `WinSetTransparent("Off")` 临时地关闭窗口的透明.

## 相关

PixelSearch, PixelGetColor, CoordMode, MouseGetPos

## 示例

在活动窗口的某个区域搜索图像, 并在 FoundX 和 FoundY 中存储找到图像的左上角像素的 X 和 Y 坐标.

    ImageSearch &FoundX, &FoundY, 40, 40, 300, 300, "C:\My Images\test.bmp"

在屏幕的某个区域搜索图像, 并在 FoundX 和 FoundY 中存储找到图像的左上角像素的 X 和 Y 坐标, 包括高级错误处理.

    CoordMode "Pixel"  ; 将下面的坐标解释为相对于屏幕而不是活动窗口.
    try
    {
        if ImageSearch(&FoundX, &FoundY, 0, 0, A_ScreenWidth, A_ScreenHeight, "*Icon3 " A_ProgramFiles "\SomeApp\SomeApp.exe")
            MsgBox "The icon was found at " FoundX "x" FoundY
        else
            MsgBox "Icon could not be found on the screen."
    }
    catch as exc
        MsgBox "Could not conduct the search due to the following error:`n" exc.Message

dftg