@aspiresys/visor 1.2.9 → 1.2.11

package/dist/index.d.ts

@@ -1,11 +1,129 @@
 import { Key, Button, Point } from "@nut-tree-fork/nut-js";
+import { Region } from "./types";
 export declare class Visor {
-    mouse: import("@nut-tree-fork/nut-js").MouseClass;
-    keyboard: import("@nut-tree-fork/nut-js").KeyboardClass;
+    private mouse;
+    private keyboard;
     Key: typeof Key;
     Button: typeof Button;
     private configWarningShown;
     private checkConfig;
+    /**
+   * Moves the mouse cursor to the
+   * center of a specific screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.moveToRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    moveToRegion(region: Region, offset?: {
+        x: number;
+        y: number;
+    }): Promise<void>;
+    /**
+   * Performs a left mouse click at the
+   * center of a specific screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.clickRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    clickRegion(region: Region, offset?: {
+        x: number;
+        y: number;
+    }): Promise<void>;
+    /**
+   * Performs a double left mouse click
+   * at the center of a specific
+   * screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.doubleClickRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    doubleClickRegion(region: Region, offset?: {
+        x: number;
+        y: number;
+    }): Promise<void>;
+    /**
+   * Performs a right mouse click at the
+   * center of a specific screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.rightClickRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    rightClickRegion(region: Region, offset?: {
+        x: number;
+        y: number;
+    }): Promise<void>;
     /**
      * Finds an image on screen using OpenCV
      * and performs a left mouse click
@@ -126,7 +244,7 @@ export declare class Visor {
      * const region =
      *   await visor.find("save.png");
      */
-    find(image: string, confidence?: number): Promise<import("./types").Region>;
+    find(image: string, confidence?: number): Promise<Region>;
     /**
      * Checks whether an image exists
      * on the current screen.
@@ -169,7 +287,7 @@ export declare class Visor {
      * const matches =
      *   await visor.findAll("icon.png");
      */
-    findAll(image: string, confidence?: number): Promise<import("./types").Region[]>;
+    findAll(image: string, confidence?: number): Promise<Region[]>;
     /**
      * Finds all image matches and prints
      * a formatted match preview including
@@ -192,7 +310,7 @@ export declare class Visor {
      * @example
      * await visor.previewMatches("button.png");
      */
-    previewMatches(image: string, confidence?: number): Promise<import("./types").Region[]>;
+    previewMatches(image: string, confidence?: number): Promise<Region[]>;
     /**
      * Waits until an image appears
      * on the screen.
@@ -342,7 +460,7 @@ export declare class Visor {
         y: number;
         width: number;
         height: number;
-    }): Promise<import("./types").Region>;
+    }): Promise<Region>;
     /**
      * Checks whether specific text exists
      * on screen using OCR.
@@ -601,11 +719,12 @@ export declare class Visor {
      *
      * @param x X coordinate.
      * @param y Y coordinate.
+     * @param inspectorCoords Boolean to represent if the coords are from visor-inspector
      *
      * @example
      * await visor.moveMouse(500, 300);
      */
-    moveMouse(x: number, y: number): Promise<void>;
+    moveMouse(x: number, y: number, inspectorCoords?: boolean): Promise<void>;
     /**
      * Returns the current mouse cursor
      * position.
@@ -783,7 +902,7 @@ export declare class Visor {
      */
     findAny(images: string[], confidence?: number): Promise<{
         image: string;
-        region: import("./types").Region;
+        region: Region;
     }>;
     /**
      * Checks whether any image from

package/dist/index.js

@@ -48,6 +48,134 @@ class Visor {
             this.configWarningShown = true;
         }
     }
+    /**
+   * Moves the mouse cursor to the
+   * center of a specific screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.moveToRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    async moveToRegion(region, offset = {
+        x: 0,
+        y: 0
+    }) {
+        await (0, mouse_1.moveToRegion)(region, offset);
+    }
+    /**
+   * Performs a left mouse click at the
+   * center of a specific screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.clickRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    async clickRegion(region, offset = {
+        x: 0,
+        y: 0
+    }) {
+        await (0, mouse_1.moveToRegion)(region, offset);
+        await this.mouse.click(this.Button.LEFT);
+    }
+    /**
+   * Performs a double left mouse click
+   * at the center of a specific
+   * screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.doubleClickRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    async doubleClickRegion(region, offset = {
+        x: 0,
+        y: 0
+    }) {
+        await (0, mouse_1.moveToRegion)(region, offset);
+        await this.mouse.doubleClick(this.Button.LEFT);
+    }
+    /**
+   * Performs a right mouse click at the
+   * center of a specific screen region.
+   *
+   * Region coordinates typically come from:
+   * - visor.find()
+   * - visor.findAll()
+   * - OCR text matching
+   * - Visor Inspector
+   *
+   * Display scaling is automatically
+   * applied using the configured
+   * scale factor.
+   *
+   * @param region Screen region coordinates.
+   * @param offset Offset coords.
+   *
+   * @example
+   * await visor.rightClickRegion({
+   *   x: 100,
+   *   y: 200,
+   *   width: 150,
+   *   height: 50
+   * });
+   */
+    async rightClickRegion(region, offset = {
+        x: 0,
+        y: 0
+    }) {
+        await (0, mouse_1.moveToRegion)(region, offset);
+        await this.mouse.click(this.Button.RIGHT);
+    }
     /**
      * Finds an image on screen using OpenCV
      * and performs a left mouse click
@@ -208,8 +336,12 @@ class Visor {
         const start = Date.now();
         const screen = await (0, screen_1.captureScreen)();
         const template = await (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
+        const scaleFactor = config_1.visorConfig.scaleFactor;
         try {
             const result = (0, matcher_1.matchTemplate)(screen, template, confidence);
+            if (result) {
+                (0, logger_1.log)(`[FIND] Actual coords: (${Math.floor(result.x * scaleFactor)}, ${Math.floor(result.y * scaleFactor)})`);
+            }
             (0, logger_1.log)(`[FIND] Total: ${Date.now() - start} ms`);
             return result;
         }
@@ -801,13 +933,19 @@ CONF:${m.confidence.toFixed(3)}
      *
      * @param x X coordinate.
      * @param y Y coordinate.
+     * @param inspectorCoords Boolean to represent if the coords are from visor-inspector
      *
      * @example
      * await visor.moveMouse(500, 300);
      */
-    async moveMouse(x, y) {
+    async moveMouse(x, y, inspectorCoords = false) {
         this.checkConfig();
-        await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(x, y)));
+        if (inspectorCoords) {
+            await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(x, y)));
+            return;
+        }
+        const scaleFactor = config_1.visorConfig.scaleFactor;
+        await this.mouse.move((0, nut_js_1.straightTo)(new nut_js_1.Point(Math.floor(x / scaleFactor), Math.floor(y / scaleFactor))));
     }
     /**
      * Returns the current mouse cursor

package/inspector/index.html

@@ -24,7 +24,8 @@
               <div class="input-wrapper">
                 <span class="input-hint">Confidence</span>
                 <input id="confidenceInput" type="number" min="0" max="1" step="0.01" value="0.8" />
-                <span class="input-hint">(0.0 - 1.0)</span>
+                <span class="input-hint">(0.0 - 1.0)    </span>
+                Current Template: <span id="currentTemplate" class="template-status">None</span>
               </div>
             </div>
           </div>
@@ -32,26 +33,16 @@
       </section>
       <div class="capture-layout">
         <div class="capture-panel">
-          <h3 class="section-title"> Current Capture </h3>
+          <h3 class="section-title"> Current Capture (X:<span id="mousex"></span>, Y:<span id="mousey"></span>)</h3>
           <canvas id="screenCanvas" class="canvas"></canvas>
         </div>
         <div class="result-panel">
+          <h3 class="section-title"> Template </h3>
+          <img id="templatePreview" class="template-preview" alt="No Template Loaded" src="data:image/gif;base64,R0lGODlhAQABAAD/ACwAAAAAAQABAAACADs="/>
           <h3 class="section-title"> Match Result </h3>
           <div id="matchResult"> No Match Tested </div>
-        </div>
+         </div>
       </div>
-      <section class="template-section">
-        <h3 class="section-title">Template Management</h3>
-        <div class="template-grid">
-          <div class="template-info">
-            <p>
-              <strong>Current Template: </strong>
-              <span id="currentTemplate" class="template-status">None</span>
-            </p>
-          </div>
-          <img id="templatePreview" class="template-preview" />
-        </div>
-      </section>
     </div>
     <script src="./src/renderer.js"></script>
   </body>

package/inspector/src/renderer.js

@@ -30,6 +30,7 @@ captureBtn.addEventListener("click",
 			const scale = image.width > maxWidth ? maxWidth / image.width : 1;
 			canvas.width = image.width * scale;
 			canvas.height = image.height * scale;
+			matchResult.textContent = " No Match Tested ";
 			ctx.drawImage(
 				image,
 				0,
@@ -58,6 +59,8 @@ canvas.addEventListener("mousedown",
 canvas.addEventListener("mousemove",
 	(e) => {
 		if (!selecting) {
+			document.getElementById("mousex").innerHTML = Math.round(e.offsetX * imageScaleX);
+			document.getElementById("mousey").innerHTML = Math.round(e.offsetY * imageScaleY);
 			return;
 		}
 		displayEndX = e.offsetX;
@@ -95,6 +98,7 @@ canvas.addEventListener("mouseup",
 	}
 );
 
+
 saveBtn.addEventListener("click",
 	async () => {
 		if (
@@ -122,8 +126,18 @@ saveBtn.addEventListener("click",
 				height: Math.abs(endY - startY),
 				outputPath: filePath
 			});
+		const fileName = filePath.split(/[\\/]/).pop();
 		selectedTemplatePath = filePath;
-		currentTemplate.textContent = filePath;
+		currentTemplate.textContent = fileName;
+		currentTemplate.title = filePath;
+		matchResult.textContent = " No Match Tested ";
+		ctx.drawImage(
+			image,
+			0,
+			0,
+			canvas.width,
+			canvas.height
+		);
 		templatePreview.src = filePath + "?t=" + Date.now();
 		alert("Template Saved");
 	}
@@ -152,8 +166,30 @@ testMatchBtn.addEventListener("click", async () => {
 
   if (!result) {
 	matchResult.textContent = "✗ MATCH NOT FOUND";
+	ctx.drawImage(
+		image,
+		0,
+		0,
+		canvas.width,
+		canvas.height
+	);
     return;
   }
+  ctx.drawImage(
+  	image,
+	0,
+	0,
+	canvas.width,
+	canvas.height
+  );
+  ctx.strokeStyle = "lime";
+  ctx.lineWidth = 3;
+  ctx.strokeRect(
+	result.x / imageScaleX,
+	result.y / imageScaleY,
+	result.width / imageScaleX,
+	result.height / imageScaleY
+  );
   matchResult.textContent = `
 	✓ MATCH FOUND
 
@@ -175,8 +211,18 @@ loadTemplateBtn.addEventListener("click",
 		if (!path) {
 			return;
 		}
+		const fileName = path.split(/[\\/]/).pop();
 		selectedTemplatePath = path;
-		currentTemplate.textContent = path;
+		currentTemplate.textContent = fileName;
+		currentTemplate.title = path;
+		matchResult.textContent = " No Match Tested ";
+		ctx.drawImage(
+			image,
+			0,
+			0,
+			canvas.width,
+			canvas.height
+		);
 		templatePreview.src = path + "?t=" + Date.now();
 	}
 );

package/inspector/styles.css

@@ -238,6 +238,7 @@ input[type="number"]:focus {
   display: block;
   margin-top: 15px;
   box-shadow: 0 0 20px rgba(0, 212, 255, 0.1);
+  width: stretch;
 }
 
 /* TEMPLATE SECTION */
@@ -268,26 +269,23 @@ input[type="number"]:focus {
 }
 
 .template-status {
-  display: inline-block;
-  padding: 4px 7px;
-  background: rgba(76, 175, 80, 0.15);
-  border: 1px solid rgba(76, 175, 80, 0.3);
-  border-radius: 6px;
   color: #4caf50;
-  font-weight: 500;
-  width: fit-content;
+  font-size: small;
 }
 
 .template-preview {
   border: 2px solid #00d4ff;
   border-radius: 8px;
+  width: 130px;
   max-width: 100%;
-  height: auto;
+  height: 130px;
   max-height: 150px;
   object-fit: contain;
   background: #0a0a0a;
   box-shadow: 0 0 20px rgba(0, 212, 255, 0.1);
   display: none;
+  margin-top: 15px;
+  margin-bottom: 15px;
 }
 
 .template-preview[src]:not([src=""]) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspiresys/visor",
-  "version": "1.2.9",
+  "version": "1.2.11",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {

package/readme.md

@@ -22,6 +22,8 @@ Visor is designed for automating desktop workflows using visual interactions ins
 * Region OCR support
 * Automatic display scaling detection
 * Mouse automation
+* Region-based mouse automation
+* Target offset support
 * Keyboard automation
 * Drag & drop support
 * Multi-theme image handling
@@ -51,6 +53,23 @@ 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
@@ -167,6 +186,67 @@ const region =
 
 ---
 
+## 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(
+    "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({
+  x: 100,
+  y: 200,
+  width: 150,
+  height: 50
+});
+```
+
+### Right Click Region
+
+```ts
+await visor.rightClickRegion({
+  x: 100,
+  y: 200,
+  width: 150,
+  height: 50
+});
+```
+
+Display scaling is automatically applied when using region-based APIs.
+
+---
+
 ## Check Image Exists
 
 ```ts
@@ -230,6 +310,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.
@@ -351,6 +472,21 @@ await visor.moveMouse(
 
 ---
 
+### Move To Inspector Region
+
+```ts
+await visor.moveToRegion({
+  x: 90,
+  y: 61,
+  width: 138,
+  height: 69
+});
+```
+
+Region coordinates can be copied directly from Visor Inspector match results.
+
+---
+
 ## Scroll Down
 
 ```ts
@@ -497,9 +633,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