@aspiresys/visor 1.3.5 → 1.4.0

package/dist/types.js

@@ -1,4 +1,7 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Region = void 0;
 const nut_js_1 = require("@nut-tree-fork/nut-js");
@@ -11,6 +14,9 @@ const path_1 = require("./path");
 const config_1 = require("./config");
 const console_1 = require("console");
 const display_1 = require("./display");
+const templateMetadata_1 = require("./templateMetadata");
+const opencv_js_1 = __importDefault(require("@techstark/opencv-js"));
+const fs_1 = __importDefault(require("fs"));
 /**
  * Represents a rectangular screen region.
  *
@@ -48,90 +54,134 @@ class Region {
         }
         const missing = [];
         if (!config_1.visorConfig.imagePath) {
-            missing.push("imagePath");
+            missing.push('imagePath');
         }
         if (!config_1.visorConfig.outputPath) {
-            missing.push("outputPath");
+            missing.push('outputPath');
         }
         if (missing.length > 0) {
             (0, console_1.warn)(`[VISOR] Configuration incomplete.\n` +
-                `Missing: ${missing.join(", ")}\n\n` +
+                `Missing: ${missing.join(', ')}\n\n` +
                 `Relative paths may not work correctly.\n` +
                 `Use visor.loadConfig(...) or provide absolute paths directly to functions.`);
         }
         if (!config_1.visorConfig.initialized) {
             config_1.visorConfig.scaleFactor = (0, display_1.getWindowsScaleFactor)();
-            (0, console_1.warn)(`[VISOR] Configuration not loaded.\n` +
-                `Auto-detected scaleFactor=${config_1.visorConfig.scaleFactor}.\n`);
+            (0, console_1.warn)(`[VISOR] Configuration not loaded.\n` + `Auto-detected scaleFactor=${config_1.visorConfig.scaleFactor}.\n`);
         }
         if (missing.length > 0 || !config_1.visorConfig.initialized) {
             Region.configWarningShown = true;
         }
     }
     /**
-   * Returns the center point of the region.
-   *
-   * Useful for:
-   * - mouse movement
-   * - coordinate calculations
-   * - custom interactions
-   */
+     * Captures a screenshot of the
+     * region and saves it
+     * to the specified path.
+     *
+     * Supported formats depend on
+     * the output file extension.
+     *
+     * @param path Output image path.
+     *
+     * @example
+     * await region.capture(
+     *   "./screenshots/output.png"
+     * );
+     */
+    async capture(path) {
+        this.checkConfig();
+        const screenshot = await (0, screen_1.captureScreen)();
+        path = config_1.visorConfig.outputPath + '/' + path;
+        try {
+            const cropped = (0, matcher_1.cropMat)(screenshot, this);
+            const png = new opencv_js_1.default.Mat();
+            opencv_js_1.default.cvtColor(cropped, png, opencv_js_1.default.COLOR_RGBA2BGRA);
+            const imageData = {
+                width: png.cols,
+                height: png.rows,
+                data: Buffer.from(png.data),
+            };
+            const { PNG } = require('pngjs');
+            const output = new PNG({
+                width: imageData.width,
+                height: imageData.height,
+            });
+            output.data = imageData.data;
+            await new Promise((resolve) => {
+                output.pack().pipe(fs_1.default.createWriteStream(path)).on('finish', resolve);
+            });
+            png.delete();
+            cropped.delete();
+        }
+        finally {
+            screenshot.delete();
+        }
+    }
+    /**
+     * Returns the center point of the region.
+     *
+     * Useful for:
+     * - mouse movement
+     * - coordinate calculations
+     * - custom interactions
+     */
     center() {
         return {
             x: this.x + Math.floor(this.width / 2),
-            y: this.y + Math.floor(this.height / 2)
+            y: this.y + Math.floor(this.height / 2),
         };
     }
     /**
-   * Moves the mouse to the center of the region.
-   *
-   * Mouse coordinates are automatically
-   * adjusted for display scaling.
-   */
+     * Moves the mouse to the center of the region.
+     *
+     * Mouse coordinates are automatically
+     * adjusted for display scaling.
+     */
     async move() {
         await (0, mouse_1.moveToRegion)(this);
     }
     /**
-   * Performs a left click on the region.
-   *
-   * Clicks the center of the region by default.
-   *
-   * Optional offset can be supplied to click
-   * a specific position relative to the center.
-   */
+     * Performs a left click on the region.
+     *
+     * Clicks the center of the region by default.
+     *
+     * Optional offset can be supplied to click
+     * a specific position relative to the center.
+     */
     async click(offset) {
         await (0, mouse_1.clickRegion)(this, offset);
+        console.log(`[CLICK] ${this.constructor.name} at center (${this.center().x}, ${this.center().y}) with confidence ${this.confidence.toFixed(2)})`);
     }
     /**
-   * 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);
-   */
+     * 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);
@@ -211,130 +261,230 @@ class Region {
         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");
-   */
+     * 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++) {
+            (0, console_1.log)(`[WAIT] ${image} (${i + 1}/${attempts})`);
             if (await this.exists(image, confidence)) {
+                (0, console_1.log)(`[WAIT] Found: ${image}`);
                 return true;
             }
             await this.sleep(interval);
         }
+        (0, console_1.log)(`[WAIT] Timeout: ${image}`);
         throw new Error(`Timeout waiting for image: ${image}`);
     }
     /**
-   * Performs a double left click on the region.
-   *
-   * Optional offset can be supplied to click
-   * a specific position relative to the center.
-   */
+     * Waits until any image from
+     * a list appears in the Region.
+     *
+     * Useful for handling:
+     * - multiple themes
+     * - alternate UI layouts
+     * - dynamic application states
+     *
+     * @param images Array of image
+     * filenames or paths.
+     *
+     * @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.
+     *
+     * @param timeout Timeout duration
+     * in milliseconds.
+     *
+     * Default:
+     * 5000ms
+     *
+     * Recommended range:
+     * 1000ms to 30000ms
+     *
+     * @throws Error if timeout occurs.
+     *
+     * @example
+     * await visor.waitAnyImg([
+     *   "home-light.png",
+     *   "home-dark.png"
+     * ]);
+     */
+    async waitAnyImg(images, { confidence = 0.8, timeout = 5000 } = {}) {
+        this.checkConfig();
+        const interval = 300;
+        const attempts = Math.ceil(timeout / interval);
+        for (let i = 0; i < attempts; i++) {
+            for (const image of images) {
+                const region = await this.find(image, confidence);
+                if (region) {
+                    return region;
+                }
+            }
+            await this.sleep(interval);
+        }
+        throw new Error(`Timeout waiting for images: ${images.join(', ')}`);
+    }
+    /**
+     * Finds the first matching image
+     * within the current Region and
+     * performs a click.
+     *
+     * Useful for:
+     * - theme variations
+     * - alternate UI states
+     * - dynamic controls
+     *
+     * @param images Array of image paths.
+     * @param confidence Match confidence.
+     * @param offset Optional click offset.
+     *
+     * @returns Matched Region.
+     *
+     * @example
+     * await region.clickAny([
+     *   "save-light.png",
+     *   "save-dark.png"
+     * ]);
+     */
+    async clickAny(images, confidence = 0.8, offset) {
+        this.checkConfig();
+        for (const image of images) {
+            const region = await this.find(image, confidence);
+            if (region) {
+                await region.click(offset);
+                return region;
+            }
+        }
+        throw new Error(`None of the images were found: ${images.join(', ')}`);
+    }
+    /**
+     * Performs a double left click on the region.
+     *
+     * Optional offset can be supplied to click
+     * a specific position relative to the center.
+     */
     async doubleClick(offset) {
         await (0, mouse_1.moveToRegion)(this, offset);
         await nut_js_1.mouse.doubleClick(nut_js_1.Button.LEFT);
     }
     /**
-   * Performs a right click on the region.
-   *
-   * Optional offset can be supplied to click
-   * a specific position relative to the center.
-   */
+     * Performs a right click on the region.
+     *
+     * Optional offset can be supplied to click
+     * a specific position relative to the center.
+     */
     async rightClick(offset) {
         await (0, mouse_1.moveToRegion)(this, offset);
         await nut_js_1.mouse.click(nut_js_1.Button.RIGHT);
     }
     /**
-   * Checks whether the supplied coordinates
-   * are located inside this region.
-   *
-   * Returns:
-   * - true if inside
-   * - false otherwise
-   */
+     * Checks whether the supplied coordinates
+     * are located inside this region.
+     *
+     * Returns:
+     * - true if inside
+     * - false otherwise
+     */
     contains(x, y) {
-        return (x >= this.x) && (x <= this.x + this.width) && (y >= this.y) && (y <= this.y + this.height);
+        return x >= this.x && x <= this.x + this.width && y >= this.y && y <= this.y + this.height;
     }
     /**
-   * Creates a new Region shifted by the
-   * supplied x and y offsets.
-   *
-   * Original region remains unchanged.
-   */
+     * Creates a new Region shifted by the
+     * supplied x and y offsets.
+     *
+     * Original region remains unchanged.
+     */
     offset(x, y) {
         return new Region(this.x + x, this.y + y, this.width, this.height, this.confidence);
     }
     /**
-   * Checks whether this region overlaps
-   * with another region.
-   *
-   * Returns:
-   * - true if regions intersect
-   * - false otherwise
-   */
+     * Checks whether this region overlaps
+     * with another region.
+     *
+     * Returns:
+     * - true if regions intersect
+     * - false otherwise
+     */
     intersects(region) {
-        return (this.x <= region.x + region.width) && (this.x + this.width >= region.x) && (this.y <= region.y + region.height) && (this.y + this.height >= region.y);
+        return (this.x <= region.x + region.width &&
+            this.x + this.width >= region.x &&
+            this.y <= region.y + region.height &&
+            this.y + this.height >= region.y);
     }
     /**
-   * Returns the total area of the region
-   * in pixels.
-   */
+     * Returns the total area of the region
+     * in pixels.
+     */
     area() {
         return this.width * this.height;
     }
     /**
-   * Extracts OCR text from this region.
-   *
-   * Returns full OCR output including:
-   * - text
-   * - TSV data
-   * - HOCR data
-   * - block information
-   */
+     * Extracts OCR text from this region.
+     *
+     * Returns full OCR output including:
+     * - text
+     * - TSV data
+     * - HOCR data
+     * - block information
+     */
     async readText() {
         this.checkConfig();
         return await (0, ocr_1.extractTextFromRegion)(this);
     }
     /**
-   * Searches for text within this region.
-   *
-   * Returns the matching text region
-   * if found, otherwise null.
-   *
-   * Supports selecting a specific match
-   * using the index parameter.
-   */
+     * Searches for text within this region.
+     *
+     * Returns the matching text region
+     * if found, otherwise null.
+     *
+     * Supports selecting a specific match
+     * using the index parameter.
+     */
     async findText(text, index = 0) {
         this.checkConfig();
         const match = await (0, text_1.findText)(text, index, this);
@@ -344,35 +494,42 @@ class Region {
         return match.offset(this.x, this.y);
     }
     /**
-   * Checks whether the supplied text
-   * exists within this region.
-   *
-   * Returns:
-   * - true if found
-   * - false otherwise
-   */
+     * Checks whether the supplied text
+     * exists within this region.
+     *
+     * Returns:
+     * - true if found
+     * - false otherwise
+     */
     async existsText(text) {
         this.checkConfig();
         return await (0, text_1.existsText)(text, this);
     }
     /**
-   * Searches for an image within this region.
-   *
-   * Matching is performed only inside
-   * the current region, improving speed
-   * and reducing false positives.
-   *
-   * Returns:
-   * - matching Region if found
-   * - null otherwise
-   */
+     * Searches for an image within this region.
+     *
+     * Matching is performed only inside
+     * the current region, improving speed
+     * and reducing false positives.
+     *
+     * Returns:
+     * - matching Region if found
+     * - null otherwise
+     */
     async find(image, confidence = 0.8) {
         this.checkConfig();
         const screenshot = await (0, screen_1.captureScreen)();
         const croppedScreenshot = await (0, matcher_1.cropMat)(screenshot, this);
         const template = await (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
+        const metadata = (0, templateMetadata_1.loadTemplateMetadata)((0, path_1.resolveImagePath)(image));
         try {
-            const match = (0, matcher_1.matchTemplate)(croppedScreenshot, template, confidence);
+            if (metadata) {
+                metadata.currentResolution = {
+                    width: screenshot.cols,
+                    height: screenshot.rows,
+                };
+            }
+            const match = (0, matcher_1.matchTemplate)(croppedScreenshot, template, confidence, metadata);
             if (!match) {
                 return null;
             }
@@ -384,14 +541,17 @@ class Region {
             template.delete();
         }
     }
+    expand(pixels) {
+        return new Region(this.x - pixels, this.y - pixels, this.width + pixels * 2, this.height + pixels * 2, this.confidence);
+    }
     /**
-   * Finds all image matches within this region.
-   *
-   * Matching is performed only inside
-   * the current region.
-   *
-   * Returns an array of matching regions.
-   */
+     * Finds all image matches within this region.
+     *
+     * Matching is performed only inside
+     * the current region.
+     *
+     * Returns an array of matching regions.
+     */
     async findAll(image, confidence = 0.8) {
         this.checkConfig();
         const screenshot = await (0, screen_1.captureScreen)();
@@ -399,7 +559,7 @@ class Region {
         const template = await (0, matcher_1.loadTemplate)((0, path_1.resolveImagePath)(image));
         try {
             const matches = (0, matcher_1.findAllMatches)(croppedScreenshot, template, confidence);
-            return matches.map(match => match.offset(this.x, this.y));
+            return matches.map((match) => match.offset(this.x, this.y));
         }
         finally {
             screenshot.delete();
@@ -408,15 +568,15 @@ class Region {
         }
     }
     /**
-   * Checks whether an image exists
-   * within this region.
-   *
-   * Returns:
-   * - true if found
-   * - false otherwise
-   */
+     * Checks whether an image exists
+     * within this region.
+     *
+     * Returns:
+     * - true if found
+     * - false otherwise
+     */
     async exists(image, confidence = 0.8) {
-        return await this.find(image, confidence) !== null;
+        return (await this.find(image, confidence)) !== null;
     }
 }
 exports.Region = Region;

package/dist/version.d.ts

@@ -0,0 +1 @@
+export declare function getVersion(): string;

package/dist/version.js

@@ -0,0 +1,18 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getVersion = getVersion;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+function getVersion() {
+    try {
+        const packageJsonPath = path_1.default.join(__dirname, '..', 'package.json');
+        const packageJson = JSON.parse(fs_1.default.readFileSync(packageJsonPath, 'utf8'));
+        return packageJson.version;
+    }
+    catch (error) {
+        return 'unknown';
+    }
+}