Online Documentation: https://chunjee.github.io/graphicsearch.ahk
A lightning-fast, highly versatile, and powerful screen searching library for AutoHotkey
graphicsearch.ahk is a robust alternative to AutoHotkey's native ImageSearch command, addressing its limitations with innovative features tailored for modern developers. Unlike ImageSearch, which requires saved image files, exact matches, and can be slow and challenging to debug, graphicsearch.ahk simplifies the process by abstracting the screen into a lightweight representation, akin to ASCII art, using characters 0 and _.
This approach offers several key advantages:
- Array of Results: graphicsearch.ahk returns an array of objects, each representing a match with detailed properties. This structured format makes it easier to process and integrate results into modern workflows.
- Speed and Efficiency: It performs faster matches without the need to recapture the screen image for each search, streamlining searches involving multiple graphics.
- Flexibility: Its adjustable fault tolerance and abstraction layer allow fine-tuning for varying conditions.
- Comprehensive Results: Unlike
ImageSearch, which returns only the first match, graphicsearch.ahk identifies and returns all matches, enabling advanced and complex search scenarios.
With these enhancements, graphicsearch.ahk not only surpasses ImageSearch in speed and functionality but also provides a developer-friendly experience, making graphical searches more intuitive and powerful.
In a terminal or command line:
npm install graphicsearch.ahkIn your code only export.ahk needs to be included:
#Include %A_ScriptDir%\node_modules
#Include graphicsearch.ahk\export.ahk
oGraphicSearch := new graphicsearch()
result := oGraphicSearch.search("|<HumanReadableTag>*165$22.03z")
; => [{1: 1215, 2: 407, 3: 22, 4: 10, id: "HumanReadableTag", x: 1226, y: 412}]You may also review or copy the library from ./export.ahk on GitHub #Incude as you would normally when manually downloading.
.search(graphicsearch_query [, options])
finds GraphicSearch queries on the screen
| Argument | Type | Description |
|---|---|---|
graphicsearch_query |
string | The GraphicSearch query(s) to search. Must be concatenated with | if searching multiple graphics. |
options |
object | The options object. |
options.x1, options.y1 |
number | The search scope's upper left corner coordinates. Default: 0, 0. |
options.x2, options.y2 |
number | The search scope's lower right corner coordinates. Default: A_ScreenWidth, A_ScreenHeight. |
options.err1, options.err0 |
number | A number between 0 and 1 (0.1 = 10%) for fault tolerance of foreground (err1) and background (err0). Default: 0, 0. |
options.screenshot |
number | Whether or not to capture a new screenshot. If 0, the last captured screenshot will be used. Default: 1. |
options.findall |
number | Whether or not to find all instances or just one. Default: 1. |
options.joinqueries |
number | Join all GraphicSearch queries for combination lookup. Default: 1. |
options.offsetx, options.offsety |
number | The maximum offset for combination lookup. Default: 0, 0. |
| Type | Description |
|---|---|
| array | Returns an array of objects containing all lookup results, or false if no matches are found. |
optionsObj := { x1: 0
, y1: 0
, x2: A_ScreenWidth
, y2: A_ScreenHeight
, err1: 0
, err0: 0
, screenshot: 1
, findall: 1
, joinqueries: 1
, offsetx: 1
, offsety: 1 }
oGraphicSearch.search("|<tag>*165$22.03z", optionsObj)
oGraphicSearch.search("|<tag>*165$22.03z", {x2: 100, y2: 100}).searchAgain([graphicsearch_query])
performs the last .search with the last arguments supplied
oGraphicSearch.search("|<tag>*165$22.03z", {x2: 1028, y2: 720})
oGraphicSearch.searchAgain()
oGraphicSearch.searchAgain("|<HumanReadableTag>*99$26.z7z").scan(graphicsearch_query [, y1, x2, y2, err1, err0, screenshot, findall, joinqueries, offsetx, offsety])
finds GraphicSearch queries on the screen
| Argument | Type | Description |
|---|---|---|
graphicsearch_query |
string | GraphicsSearch queries as strings. Can be multiple queries separated by |. |
x1, y1 |
number | The search scope's upper left corner coordinates. Default: 0, 0. |
x2, y2 |
number | The search scope's lower right corner coordinates. Default: A_ScreenWidth, A_ScreenHeight. |
err1, err0 |
number | A number between 0 and 1 (0.1 = 10%) for fault tolerance of foreground (err1) and background (err0). Default: 0, 0. |
screenshot |
boolean | If the value is 1, a new capture of the screen will be used; otherwise, the last capture will be used. Default: 1. |
findall |
boolean | If the value is 1, GraphicSearch will find all matches. For 0, only one match is returned. Default: 1. |
joinqueries |
boolean | If the value is 1, join all GraphicsSearch queries for combination lookup. Default: 1. |
offsetx, offsety |
number | The maximum offset for combination lookup. Default: 0, 0. |
| Type | Description |
|---|---|
| array | Returns an array of objects containing all lookup results, or false if no matches are found. Each result is an associative array: {1:X, 2:Y, 3:W, 4:H, x:X+W//2, y:Y+H//2, id:tag}. Coordinates are relative to the screen, colors are in RGB format, and combination lookup requires uniform color mode. |
oGraphicSearch.scan("|<tag>*165$22.03z", 1, 1, 1028, 720, .1, .1, 1, 1, 1, 0, 0)
; => [{1: 1215, 2: 400, 3:22, 4: 10, id: "tag", x:1226, y:412}].scanAgain([graphicsearch_query, y1, x2, y2, err1, err0, screenshot, findall, joinqueries, offsetx, offsety])
performs the last .search with the last arguments supplied
oGraphicSearch.scan("|<tag>*165$22.03z", {x2: 1028, y2: 720})
oGraphicSearch.scanAgain()
oGraphicSearch.scanAgain("|<HumanReadableTag>*99$26.z7z").find(x1, y1, x2, y2, err1, err0, graphicsearch_query [, screenshot, findall, joinqueries, offsetx, offsety])
Identicle to .scan but uses legacy argument order as a convience for old scripts
| Argument | Type | Description |
|---|---|---|
x1, y1 |
number | The search scope's upper left corner coordinates. |
x2, y2 |
number | The search scope's lower right corner coordinates. |
err1, err0 |
number | A number between 0 and 1 (0.1 = 10%) for fault tolerance of foreground (err1) and background (err0). |
graphicsearch_query |
string | GraphicsSearch queries as strings. Can be multiple queries separated by |. |
screenshot |
boolean | If the value is 1, a new capture of the screen will be used; otherwise, the last capture will be used. Default: 1. |
findall |
boolean | If the value is 1, GraphicSearch will find all matches. For 0, only one match is returned. Default: 1. |
joinqueries |
boolean | If the value is 1, join all GraphicsSearch queries for combination lookup. Default: 1. |
offsetx, offsety |
number | Set the maximum offset for combination lookup. Default: 20, 10. |
direction |
number | Set the direction search is conducted in. Values: 1 (Left to Right / Top to Bottom) 2 (Right to Left / Top to Bottom) 3 (Left to Right / Bottom to Top) 4 (Right to Left / Bottom to Top) 5 (Top to Bottom / Left to Right) 6 (Bottom to Top / Left to Right) 7 (Top to Bottom / Right to Left) 8 (Bottom to Top / Right to Left) 9 (Center to Four Sides). |
zoomW, zoomH |
number | Zoom percentage of image width and height (0.1 = 10%). Default: 1, 1. |
| Type | Description |
|---|---|
| array | Returns an array of objects containing all lookup results, or false if no matches are found. Each result is an associative array: {1:X, 2:Y, 3:W, 4:H, x:X+W//2, y:Y+H//2, id:tag}. All coordinates are relative to the screen, colors are in RGB format, and combination lookup must use uniform color mode. |
oGraphicSearch.find(x1, y1, x2, y2, err1, err0, "|<tag>*165$22.03z", 1, 1, 0, 20, 10)
; => [{1: 1215, 2: 400, 3: 22, 4: 10, id: "tag", x: 1226, y: 412}].resultSort(resultsObject[, ydistance])
Sort the results object from left to right and top to bottom, ignoring slight height difference
| Argument | Type | Description |
|---|---|---|
resultsobject |
object | The GraphicSearch results object to sort. |
ydistance |
number | The amount of height difference to ignore, in pixels. Default: 10. |
| Type | Description |
|---|---|
| array | Returns an array of objects containing all lookup results. |
resultsObj := [ {1: 2000, 2: 2000, 3: 22, 4: 10, id: "HumanReadableTag", x: 2000, y: 2000}
, {1: 1215, 2: 400, 3: 22, 4: 10, id: "HumanReadableTag", x: 1226, y: 412}]
oGraphicSearch.resultSort(resultsObj)
; => [{1: 1215, 2: 400, 3: 22, 4: 10, id: "HumanReadableTag", x: 1226, y: 412}, {1: 2000, 2: 2000, 3: 22, 4: 10, id: "HumanReadableTag", x: 2000, y: 2000}].resultSortDistance(resultsObject [, x, y])
Sort the results objects by distance to a given x,y coordinate. A property "distance" is added to all elements in the returned result object
| Argument | Type | Description |
|---|---|---|
resultsObject |
object | The GraphicSearch results object. |
x |
number | The x screen coordinate to measure from. Default: A_ScreenWidth / 2. |
y |
number | The y screen coordinate to measure from. Default: A_ScreenHeight / 2. |
| Type | Description |
|---|---|
| array | Returns an array of objects containing all lookup results. |
resultsObj := [ {1: 2000, 2: 2000, 3: 22, 4: 10, id: "HumanReadableTag", x: 2000, y: 2000}
, {1: 1215, 2: 400, 3: 22, 4: 10, id: "HumanReadableTag", x: 1226, y: 412}]
oGraphicSearch.resultSortDistance(resultsObj, 2000, 2000)
/*
[ {1: 2000, 2: 2000, 3: 22, 4: 10, distance: "12.08", id: "HumanReadableTag", x: 2000, y: 2000}
, {1: 1215, 2: 400, 3: 22, 4: 10, distance: "1766.58", id: "HumanReadableTag", x: 1226, y: 412}]
*/.showMatches(resultsObject [, optionsObject])
Visually display the locations of search results on the screen. It takes in a resultsObject, and optionally an optionsObject to customize how the results are displayed.
| Argument | Type | Description |
|---|---|---|
resultsObject |
object | The GraphicSearch results object. |
options |
object | The options object. Default: {showBox:true, showLabel:true, timeout:4000, color:"0b87da"}. |
options.showBox |
number | Whether or not to display boxes. Default: 1 |
options.showLabel |
number | Whether or not to display labels. Default: 1 |
options.timeout |
number | The ammount of time in milliseconds to hide the search results on screen. Default: 4000 |
options.color |
number | The color use on screen. Default: "0b87da" |
| Type | Description |
|---|---|
| none | No value is returned. |
resultsObj := [ {1: 2000, 2: 2000, 3: 22, 4: 10, id: "HumanReadableTag", x: 2000, y: 2000}
, {1: 1215, 2: 400, 3: 22, 4: 10, id: "HumanReadableTag", x: 1226, y: 412}]
oGraphicSearch.showMatches(resultsObj, {showlabels: false, timeout: 60000}).resultMerge(resultObj, offsetX := 20, offsetY := 20, overlapW := 0)
Merge overlapping or adjacent search results into a single resultsObject. It takes in a resultsObject and optional parameters to adjust proximity and overlap thresholds. This can be used like a Optical Character Recognition (OCR) system, or just to combine nearby results into one object.
| Parameter | Type | Default Value | Description |
|---|---|---|---|
| resultObj | Object | N/A | The GraphicSearch results object containing the search results to process. |
| offsetX | number | 20 | The horizontal offset in pixels between adjacent mergable results. |
| offsetY | number | 20 | The vertical offset in pixels between adjacent mergable results. |
| overlapW | number | 0 | The overlap width in pixels. Sets the allowed horizontal overlap between labels. |
| Type | Description |
|---|---|
| Object | Returns an object containing the combined labels text and bounding box dimensions of the text. The object includes: |
text: The concatenated id string. |
|
x: The x-coordinate of the bounding box's upper-left corner. |
|
y: The y-coordinate of the bounding box's upper-left corner. |
|
w: The width of the bounding box. |
|
h: The height of the bounding box. |
resultObj := [{1:300, 2:200, 3:50, 4:30, id:"Hello"}
, {1:360, 2:200, 3:60, 4:30, id:"World"}
, {1:900, 2:250, 3:80, 4:40, id:"FOO!"}]
; merge with custom offsets
resultObj := [{1:300, 2:200, 3:50, 4:30, id:"Hello"}
, {1:360, 2:200, 3:60, 4:30, id:"World"}
, {1:900, 2:250, 3:80, 4:40, id:"FOO!"}]
resultObj := oGraphicSearch.resultMerge(resultObj, 30, 20, 10)
; => {"x":300, "y":200, "h":30, "w":110, "text":"HelloWorld"}