@aspiresys/visor 1.3.1 → 1.3.3

package/dist/matcher.js

@@ -117,6 +117,7 @@ function findAllInspectorMatches(screen, template, confidence = 0.8) {
             }
         }
     }
+    matches.sort((a, b) => b.confidence - a.confidence);
     const filtered = [];
     for (const match of matches) {
         const tooClose = filtered.some((existing) => {
@@ -128,6 +129,12 @@ function findAllInspectorMatches(screen, template, confidence = 0.8) {
             filtered.push(match);
         }
     }
+    filtered.sort((a, b) => {
+        if (a.y !== b.y) {
+            return a.y - b.y;
+        }
+        return a.x - b.x;
+    });
     result.delete();
     return filtered;
 }

package/dist/types.d.ts

@@ -59,6 +59,128 @@ export declare class Region {
    */
     click(offset?: Offset): Promise<void>;
     /**
+   * Finds an image in the Region using OpenCV
+   * and performs a left mouse click
+   * on the matched region.
+   *
+   * @param image Optional image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * Lower confidence increases
+   * flexibility but may increase
+   * false positives.
+   *
+   * @example
+   * await region.clickImg("save.png");
+   *
+   * @example
+   * await region.clickImg("./images/save.png", 0.9);
+   */
+    clickImg(image?: string, confidence?: number, offset?: Offset): Promise<void>;
+    /**
+     * Finds the image in the Region and
+     * moves the mouse to the matched region
+     * before performing the click.
+     *
+     * @param image Image filename or path.
+     * @param confidence Match confidence threshold.
+     *
+     * Accepted range:
+     * 0.0 to 1.0
+     *
+     * Default:
+     * 0.8
+     * @throws Error if image is not found.
+     *
+     * @example
+     * await region.rightClickImg("file.png");
+     *
+     * @example
+     * await region.rightClickImg();
+     */
+    rightClickImg(image?: string, confidence?: number, offset?: Offset): Promise<void>;
+    private sleep;
+    /**
+     * Finds an image in the Region using OpenCV
+     * and performs a double left mouse click
+     * on the matched region.
+     *
+     * @param image Optional image filename or path.
+     *
+     * @param confidence Match confidence threshold.
+     *
+     * Accepted range:
+     * 0.0 to 1.0
+     *
+     * Default:
+     * 0.8
+     *
+     * Recommended values:
+     * - 0.7 for dynamic UI
+     * - 0.8 for standard usage
+     * - 0.9+ for strict matching
+     *
+     * Lower confidence increases
+     * flexibility but may increase
+     * false positives.
+     *
+     * @example
+     * await region.doubleClickImg("save.png");
+     *
+     * @example
+     * await region.doubleClickImg("./images/save.png", 0.9);
+     */
+    doubleClickImg(image?: string, confidence?: number, offset?: Offset): Promise<void>;
+    /**
+   * Waits until an image appears
+   * in the Region.
+   *
+   * @param image Image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   *
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await region.waitImg("loading-done.png");
+   */
+    waitImg(image: string, { confidence, timeout }?: {
+        confidence?: number;
+        timeout?: number;
+    }): Promise<boolean>;
+    /**
    * Performs a double left click on the region.
    *
    * Optional offset can be supplied to click

package/dist/types.js

@@ -103,6 +103,159 @@ class Region {
         await (0, mouse_1.clickRegion)(this, offset);
     }
     /**
+   * Finds an image in the Region using OpenCV
+   * and performs a left mouse click
+   * on the matched region.
+   *
+   * @param image Optional image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * Lower confidence increases
+   * flexibility but may increase
+   * false positives.
+   *
+   * @example
+   * await region.clickImg("save.png");
+   *
+   * @example
+   * await region.clickImg("./images/save.png", 0.9);
+   */
+    async clickImg(image, confidence = 0.8, offset) {
+        this.checkConfig();
+        const region = await this.find(image, confidence);
+        if (!region) {
+            throw new Error(`Image not found: ${image}`);
+        }
+        await region.click(offset);
+    }
+    /**
+     * Finds the image in the Region and
+     * moves the mouse to the matched region
+     * before performing the click.
+     *
+     * @param image Image filename or path.
+     * @param confidence Match confidence threshold.
+     *
+     * Accepted range:
+     * 0.0 to 1.0
+     *
+     * Default:
+     * 0.8
+     * @throws Error if image is not found.
+     *
+     * @example
+     * await region.rightClickImg("file.png");
+     *
+     * @example
+     * await region.rightClickImg();
+     */
+    async rightClickImg(image, confidence = 0.8, offset) {
+        this.checkConfig();
+        const region = await this.find(image, confidence);
+        if (!region) {
+            throw new Error(`Image not found: ${image}`);
+        }
+        await region.rightClick(offset);
+    }
+    async sleep(ms) {
+        return new Promise((r) => setTimeout(r, ms));
+    }
+    /**
+     * Finds an image in the Region using OpenCV
+     * and performs a double left mouse click
+     * on the matched region.
+     *
+     * @param image Optional image filename or path.
+     *
+     * @param confidence Match confidence threshold.
+     *
+     * Accepted range:
+     * 0.0 to 1.0
+     *
+     * Default:
+     * 0.8
+     *
+     * Recommended values:
+     * - 0.7 for dynamic UI
+     * - 0.8 for standard usage
+     * - 0.9+ for strict matching
+     *
+     * Lower confidence increases
+     * flexibility but may increase
+     * false positives.
+     *
+     * @example
+     * await region.doubleClickImg("save.png");
+     *
+     * @example
+     * await region.doubleClickImg("./images/save.png", 0.9);
+     */
+    async doubleClickImg(image, confidence = 0.8, offset) {
+        this.checkConfig();
+        const region = await this.find(image, confidence);
+        if (!region) {
+            throw new Error(`Image not found: ${image}`);
+        }
+        await region.doubleClick(offset);
+    }
+    /**
+   * Waits until an image appears
+   * in the Region.
+   *
+   * @param image Image filename or path.
+   *
+   * @param confidence Match confidence threshold.
+   *
+   * Accepted range:
+   * 0.0 to 1.0
+   *
+   * Default:
+   * 0.8
+   *
+   * Recommended values:
+   * - 0.7 for dynamic UI
+   * - 0.8 for standard usage
+   * - 0.9+ for strict matching
+   *
+   * @param timeout Timeout duration
+   * in milliseconds.
+   *
+   * Default:
+   * 5000ms
+   *
+   * Recommended range:
+   * 1000ms to 30000ms
+   *
+   * @throws Error if timeout occurs.
+   *
+   * @example
+   * await region.waitImg("loading-done.png");
+   */
+    async waitImg(image, { confidence = 0.8, timeout = 5000 } = {}) {
+        this.checkConfig();
+        const interval = 300;
+        const attempts = Math.ceil(timeout / interval);
+        for (let i = 0; i < attempts; i++) {
+            if (await this.exists(image, confidence)) {
+                return true;
+            }
+            await this.sleep(interval);
+        }
+        throw new Error(`Timeout waiting for image: ${image}`);
+    }
+    /**
    * Performs a double left click on the region.
    *
    * Optional offset can be supplied to click
@@ -219,7 +372,7 @@ class Region {
         const croppedScreenshot = await (0, matcher_1.cropMat)(screenshot, this);
         const template = await (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
         try {
-            const match = (0, matcher_1.matchInspectorTemplate)(croppedScreenshot, template, confidence, false);
+            const match = (0, matcher_1.matchTemplate)(croppedScreenshot, template, confidence);
             if (!match) {
                 return null;
             }

package/inspector/index.html

@@ -39,7 +39,7 @@
       </section>
       <div class="capture-layout">
         <div class="capture-panel">
-          <h3 class="section-title"> Current Capture (X:<span id="mousex"></span>, Y:<span id="mousey"></span>)</h3>
+          <h3 class="section-title"> Current Capture (X:<span id="mousex"></span>, Y:<span id="mousey"></span>, Width:<span id="mousew"></span>, Height:<span id="mouseh"></span>)</h3>
           <canvas id="screenCanvas" class="canvas"></canvas>
         </div>
         <div class="result-panel">

package/inspector/src/renderer.js

@@ -90,6 +90,8 @@ canvas.addEventListener("mousemove",
 canvas.addEventListener("mouseup",
 	() => {
 		selecting = false;
+		document.getElementById("mousew").innerHTML = Math.round(Math.abs(endX - startX));
+		document.getElementById("mouseh").innerHTML = Math.round(Math.abs(endY - startY));
 		console.log(startX, startY, endX, endY);
 	}
 );
@@ -121,7 +123,7 @@ saveBtn.addEventListener("click",
 		selectedTemplatePath = filePath;
 		currentTemplate.textContent = fileName;
 		currentTemplate.title = filePath;
-		matchResult.textContent = "<b>No Match Tested</b>";
+		matchResult.innerHTML = "<b>No Match Tested</b>";
 		ctx.drawImage(
 			image,
 			0,

package/package.json

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

package/readme.md

@@ -38,7 +38,7 @@ Visor is designed for automating desktop workflows using visual interactions ins
 
 ---
 
-## What's New in 1.3.0
+## What's New in 1.3.x
 
 * Region class API
 * Region image matching