graphicsearch.ahk

KO | EN

gitlite — search

#react #typescript #llm #golang #rust #linux #macos #java #windows #kubernetes #vue #ios #mcp #openai

graphicsearch.ahk

(★ 59)

A fast, super powerful, and flexible screen searching library for AutoHotkey

File Explorer

Download Latest Version (.zip)

- - drawing.svg
  - gui_capture.jpg
  - gui_capturetext.jpg
  - gui_editcapture.jpg
  - gui_edittag.jpg
  - gui_editthreshold.jpg
  - gui_edittrim.jpg
  - gui_finalquery.jpg
  - gui_window.jpg
  - header.svg
  - logo.svg
  - prism-autohotkey.min.js
  - style.css
  - tutorial-1.png
  - tutorial-2.png
- - _sidebar.md
  - docs.md
  - generating-queries.md
  - readme.md
  - tutorial.md
- .nojekyll
- _sidebar.md
- favicon.ico
- index.html
- prism-autohotkey.min.js
- readme.md
- style.css
- themebackup.txt
- image.png
- test-all.ahk
.gitignore
export.ahk
graphicsearch_gui.ahk
LICENSE
logo.svg
package.json
PicFind.c
README.md

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

Online Documentation: https://chunjee.github.io/graphicsearch.ahk

## graphicsearch.ahk

A lightning-fast, highly versatile, and powerful screen searching library for AutoHotkey

## What is it?

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.

## Installation

In a terminal or command line:
```bash
npm install graphicsearch.ahk
```
In your code only export.ahk needs to be included:
```autohotkey
#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](https://github.com/Chunjee/graphicsearch.ahk) #Incude as you would normally when manually downloading.

# Main Methods

# 
# Search Methods

## .search
`.search(graphicsearch_query [, options])`

finds GraphicSearch queries on the screen

##### Arguments
| 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`. |

##### Return
| Type   | Description |
|--------|-------------|
| array  | Returns an array of objects containing all lookup results, or `false` if no matches are found. |

##### Example
```autohotkey
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
`.searchAgain([graphicsearch_query])`

performs the last .search with the last arguments supplied

##### Example
```autohotkey
oGraphicSearch.search("|<tag>*165$22.03z", {x2: 1028, y2: 720})

oGraphicSearch.searchAgain()
oGraphicSearch.searchAgain("|<HumanReadableTag>*99$26.z7z")
```

## .scan
`.scan(graphicsearch_query [, y1, x2, y2, err1, err0, screenshot, findall, joinqueries, offsetx, offsety])`

finds GraphicSearch queries on the screen

##### Arguments
| 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`. |

#### Return
| 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. |

#### Example
```autohotkey
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
`.scanAgain([graphicsearch_query, y1, x2, y2, err1, err0, screenshot, findall, joinqueries, offsetx, offsety])`

performs the last .search with the last arguments supplied

#### Example
```autohotkey
oGraphicSearch.scan("|<tag>*165$22.03z", {x2: 1028, y2: 720})

oGraphicSearch.scanAgain()
oGraphicSearch.scanAgain("|<HumanReadableTag>*99$26.z7z")
```

## .find
`.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

#### Arguments
| 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`. |

#### Return
| 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. |

#### Example
```autohotkey
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}]
```

# Sorting Methods

## .resultSort
`.resultSort(resultsObject[, ydistance])`

Sort the results object from left to right and top to bottom, ignoring slight height difference

#### Arguments
| Argument             | Type    | Description |
|----------------------|---------|-------------|
| `resultsobject`      | object  | The GraphicSearch results object to sort. |
| `ydistance`          | number  | The amount of height difference to ignore, in pixels. Default: `10`. |

#### Return
| Type   | Description                                               |
|--------|-----------------------------------------------------------|
| array  | Returns an array of objects containing all lookup results.|

#### Example
```autohotkey
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
`.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

#### Arguments

| 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`. |

#### Return
| Type   | Description |
|--------|-------------|
| array  | Returns an array of objects containing all lookup results. |

#### Example
```autohotkey
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}]
*/
```

# Display Methods

## .showMatches
`.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.

#### Arguments
| 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"` |

#### Returns
| Type   | Description |
|--------|-------------|
| none   | No value is returned. |

#### Example
```autohotkey
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})
```

# Misc

## .resultMerge
`.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.

#### Arguments
| 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. |

#### Returns
| 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.                                      |

#### Example
```autohotkey
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"}
```

graphicsearch.ahk

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

graphicsearch.ahk

File Explorer

Today's picks

Was this content helpful?

Recent Feedback

Download README