@aspiresys/visor 1.2.10 → 1.3.0

package/readme.md

@@ -18,13 +18,16 @@ Visor is designed for automating desktop workflows using visual interactions ins
 * OpenCV-based image matching
 * Multi-scale image matching
 * OCR automation using Tesseract
-* OCR occurrence indexing
+* OCR occurrence indexing (beta)
 * Region OCR support
 * Automatic display scaling detection
 * Mouse automation
+* Region-based mouse automation
+* Region OCR support
+* Region-based mouse automation
+* Target offset support
 * Keyboard automation
 * Drag & drop support
-* Multi-theme image handling
 * Screenshot capture
 * Desktop application automation
 * OCR text searching
@@ -35,6 +38,17 @@ Visor is designed for automating desktop workflows using visual interactions ins
 
 ---
 
+## What's New in 1.3.0
+
+* Region class API
+* Region image matching
+* Region OCR search
+* Region interaction methods
+* Improved Inspector workflow
+* Target offset support
+
+---
+
 # Installation
 
 ```bash
@@ -51,10 +65,27 @@ npm install @aspiresys/visor
 
 ---
 
+# Visor Inspector
+
+Visor includes an optional desktop Inspector tool for:
+
+* Capturing templates
+* Testing image matches
+* Measuring screen coordinates
+* Validating confidence thresholds
+
+Run:
+
+```bash
+npx visor-inspector
+```
+
+---
+
 # Quick Start
 
 ```ts
-import { visor } from "@aspiresys/visor";
+import { visor, Region } from "@aspiresys/visor";
 
 async function main() {
 
@@ -160,18 +191,215 @@ await visor.click("save.png");
 
 ## Find Image
 
+```ts
+const region = await visor.find("icon.png");
+```
+
+---
+
+## Region-Based Automation
+
+Regions can be obtained from:
+
+* visor.find()
+* visor.findAll()
+* visor.findText()
+* Visor Inspector
+
+### Move To Region
+
 ```ts
 const region =
-  await visor.find("icon.png");
+  await visor.find(
+    "save.png"
+  );
+
+await visor.moveToRegion(
+  region
+);
+```
+
+### Click Region
+
+```ts
+const region =
+  await visor.find(
+    "save.png"
+  );
+
+await visor.clickRegion(
+    region
+  );
+```
+
+### Double Click Region
+
+```ts
+await visor.doubleClickRegion(new Region(
+  100,
+  200,
+  150,
+  50
+));
+```
+
+### Right Click Region
+
+```ts
+await visor.rightClickRegion(new Region(
+  100,
+  200,
+  150,
+  50
+));
+```
+
+Display scaling is automatically applied when using region-based APIs.
+
+---
+
+# Region Object API
+
+Regions returned by Visor are first-class objects that provide built-in automation methods.
+
+Regions can be obtained from:
+
+* visor.find()
+* visor.findAll()
+* visor.findText()
+* Visor Inspector
+
+Example:
+
+```ts
+const dialog = await visor.find("dialog.png");
+
+const save = await dialog.find("save.png");
+
+await save.click();
 ```
 
 ---
 
+```md
+## Region.find()
+
+Search for an image within the current region.
+```
+```ts
+const dialog = await visor.find("dialog.png");
+
+const save = await dialog.find("save.png");
+```
+
+---
+
+```md
+## Region.findAll()
+
+Find all image matches within the current region.
+```
+```ts
+const dialog = await visor.find("dialog.png");
+
+const buttons = await dialog.findAll("button.png");
+```
+
+---
+
+```md
+## Region.exists()
+
+Check whether an image exists within the current region.
+```
+```ts
+const dialog = await visor.find("dialog.png");
+
+const exists = await dialog.exists("save.png");
+```
+
+---
+
+```md
+## Region.findText()
+
+Search for text within the current region.
+```
+```ts
+const dialog = await visor.find("dialog.png");
+
+const submit = await dialog.findText("Submit");
+```
+
+---
+
+```md
+## Region.existsText()
+
+Check whether text exists within the current region.
+```
+```ts
+const dialog = await visor.find("dialog.png");
+
+const exists = await dialog.existsText("Success");
+```
+
+---
+
+```md
+## Region.readText()
+
+Extract OCR text from the current region.
+```
+```ts
+const dialog = await visor.find("dialog.png");
+
+const result = await dialog.readText();
+
+console.log(result.text);
+```
+
+---
+
+```md
+## Region.click()
+```
+```ts
+const save = await visor.find("save.png");
+
+await save.click();
+```
+
+---
+
+```md
+## Region.doubleClick()
+```
+```ts
+await save.doubleClick();
+```
+---
+
+```md
+## Region.rightClick()
+```
+```ts
+await save.rightClick();
+```
+---
+
+```md
+## Region.move()
+```
+```ts
+await save.move();
+```
+---
+
 ## Check Image Exists
 
 ```ts
-const exists =
-  await visor.exists("login.png");
+const exists = await visor.exists("login.png");
 ```
 
 ---
@@ -230,6 +458,47 @@ await visor.hover("menu.png");
 
 ---
 
+## Target Offsets
+
+Target offsets allow mouse actions to be performed relative to the center of a matched image.
+
+Useful for:
+
+* Dropdown arrows
+* Adjacent controls
+* Dynamic layouts
+* Composite UI elements
+
+### Click With Offset
+
+```ts
+await visor.click(
+  "search.png",
+  0.8,
+  {
+    x: 50,
+    y: 0
+  }
+);
+```
+
+### Hover With Offset
+
+```ts
+await visor.hover(
+  "menu.png",
+  0.8,
+  {
+    x: -20,
+    y: 10
+  }
+);
+```
+
+Offsets are applied relative to the center of the matched region before display scaling adjustments are performed.
+
+---
+
 # OCR Automation
 
 Visor includes OCR automation powered by Tesseract.js.
@@ -248,8 +517,7 @@ OCR supports:
 ## Read Screen
 
 ```ts
-const result =
-  await visor.readScreen();
+const result = await visor.readScreen();
 
 console.log(result.text);
 ```
@@ -260,12 +528,12 @@ console.log(result.text);
 
 ```ts
 const result =
-  await visor.readRegion({
-    x: 100,
-    y: 100,
-    width: 500,
-    height: 300
-  });
+  await visor.readRegion(new Region(
+    100,
+    100,
+    500,
+    300
+  ));
 
 console.log(result.text);
 ```
@@ -275,8 +543,7 @@ console.log(result.text);
 ## Find Text
 
 ```ts
-const region =
-  await visor.findText("Submit");
+const region = visor.findText("Submit");
 ```
 
 ---
@@ -351,6 +618,21 @@ await visor.moveMouse(
 
 ---
 
+### Move To Inspector Region
+
+```ts
+await visor.moveToRegion(new Region(
+  90,
+  61,
+  138,
+  69
+));
+```
+
+Region coordinates can be copied directly from Visor Inspector match results.
+
+---
+
 ## Scroll Down
 
 ```ts
@@ -370,8 +652,7 @@ await visor.scrollUp(1000);
 ## Mouse Position
 
 ```ts
-const pos =
-  await visor.getMousePosition();
+const pos = await visor.getMousePosition();
 ```
 
 ---
@@ -497,9 +778,9 @@ visor.loadConfig({
 
 # Roadmap
 
-* Template cache
-* OCR cache
-* Scale cache
+* Match visualization overlay
+* Inspector coordinate picker
+* Multi-monitor support improvements
 * Parallel image matching
 * Advanced OCR tuning
 * Electron recorder