Function Reference


Searches a rectangle of pixels for the pixel color provided.

PixelSearch ( left, top, right, bottom, color [, shade-variation = 0 [, step = 1 [, hwnd]]] )


left left coordinate of rectangle.
top top coordinate of rectangle.
right right coordinate of rectangle.
bottom bottom coordinate of rectangle.
color Color value of pixel to find (in decimal or hex).
shade-variation [optional] A number between 0 and 255 to indicate the allowed number of shades of variation of the red, green, and blue components of the color. Default is 0 (exact match).
step [optional] Instead of searching each pixel use a value larger than 1 to skip pixels (for speed). E.g. A value of 2 will only check every other pixel. Default is 1. It is not recommended to use a step value greater than 1.
hwnd [optional] Window handle to be used. Default is the desktop window. See remark.

Return Value

Success: a two-element array of pixel's coordinates. (Array[0] = x, Array[1] = y).
Failure: sets the @error flag to 1 if the color is not found.


The search direction varies as follows:
    Left-to-Right - left < right
    Right-to-Left - right < left
    Top-to-Bottom - top < bottom
    Bottom-to-Top - bottom < top
Changing the search direction can be a useful optimization if the color being searched for frequently appears in a specific quadrant of the search area since less searching is done if the search starts in the most common quadrant.

Remember, a typical display at 1024 x 768 has 786432 pixels. Although PixelSearch() is optimized, narrowing the search area helps speed up the result.

If PixelCoordMode is set to its default SCREEN (1) mode the hwnd parameter is ignored. Only if PixelCoordMode is set to WINDOW (0) or CLIENT (2) will it be honoured.


PixelChecksum, PixelCoordMode (Option), PixelGetColor


#include <MsgBoxConstants.au3>

; Find a pure red pixel in the range 0,0-20,300
Local $aCoord = PixelSearch(0, 0, 20, 300, 0xFF0000)
If Not @error Then
        MsgBox($MB_SYSTEMMODAL, "", "X and Y are: " & $aCoord[0] & "," & $aCoord[1])

; Find a pure red pixel or a red pixel within 10 shades variations of pure red
$aCoord = PixelSearch(0, 0, 20, 300, 0xFF0000, 10)
If Not @error Then
        MsgBox($MB_SYSTEMMODAL, "", "X and Y are: " & $aCoord[0] & "," & $aCoord[1])