@aspiresys/visor 1.1.6 → 1.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aspiresys/visor",
-  "version": "1.1.6",
+  "version": "1.1.7",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "scripts": {
@@ -13,7 +13,6 @@
     "pngjs": "^7.0.0",
     "screenshot-desktop": "^1.15.1",
     "sharp": "^0.34.5",
-    "systeminformation": "^5.31.7",
     "tesseract.js": "^7.0.0"
   },
   "devDependencies": {

package/readme.md

@@ -4,10 +4,10 @@ Desktop Visual Automation Framework for Node.js and TypeScript.
 
 Visor is a visual desktop automation framework that combines:
 
-- OpenCV image matching
-- OCR text recognition
-- Mouse & keyboard automation
-- Desktop application automation
+* OpenCV image matching
+* OCR text recognition
+* Mouse & keyboard automation
+* Desktop application automation
 
 Visor is designed for automating desktop workflows using visual interactions instead of traditional DOM/browser automation.
 
@@ -15,26 +15,28 @@ Visor is designed for automating desktop workflows using visual interactions ins
 
 # Features
 
-- OpenCV-based image matching
-- OCR automation using Tesseract
-- Mouse automation
-- Keyboard automation
-- Drag & drop support
-- Multi-theme image handling
-- Screenshot capture
-- Desktop application automation
-- OCR text searching
-- Wait APIs
-- Multi-image matching
-- Config-driven initialization
-- High-DPI display scaling support
+* OpenCV-based image matching
+* Multi-scale image matching
+* OCR automation using Tesseract
+* OCR occurrence indexing
+* Region OCR support
+* Automatic display scaling detection
+* Mouse automation
+* Keyboard automation
+* Drag & drop support
+* Multi-theme image handling
+* Screenshot capture
+* Desktop application automation
+* OCR text searching
+* Wait APIs
+* Multi-image matching
+* Config-driven initialization
+* High-DPI display scaling support
 
 ---
 
 # Installation
 
-## Install from npm
-
 ```bash
 npm install @aspiresys/visor
 ```
@@ -43,23 +45,20 @@ npm install @aspiresys/visor
 
 # Requirements
 
-Visor currently supports:
-
-- Windows
-- Node.js 18+
-- TypeScript
+* Windows
+* Node.js 18+
+* TypeScript
 
 ---
 
 # Quick Start
 
 ```ts
-import { visor } from "visor";
+import { visor } from "@aspiresys/visor";
 
 async function main() {
 
   visor.loadConfig({
-    scaleFactor: 1.5,
     imagePath: "./images",
     debug: true
   });
@@ -73,7 +72,6 @@ async function main() {
   await visor.type(
     "Hello from Visor"
   );
-
 }
 
 main();
@@ -83,11 +81,8 @@ main();
 
 # Configuration
 
-Visor supports centralized framework configuration.
-
 ```ts
 visor.loadConfig({
-  scaleFactor: 1.5,
   imagePath: "./images",
   debug: true
 });
@@ -97,38 +92,59 @@ visor.loadConfig({
 
 ## Configuration Options
 
-| Option | Description |
-|---|---|
-| `scaleFactor` | Display scaling factor |
-| `imagePath` | Default image directory |
-| `debug` | Enables debug logging |
+| Option       | Description                              |
+| ------------ | ---------------------------------------- |
+| scaleFactor  | Optional manual display scaling override |
+| imagePath    | Default image directory                  |
+| ssOutputPath | Screenshot output directory              |
+| debug        | Enable debug logging                     |
 
 ---
 
 # Display Scaling
 
-Display scaling is extremely important for desktop automation.
+Visor automatically detects Windows display scaling and adjusts mouse coordinates accordingly.
 
-Common values:
+Common scaling values:
 
 | Scaling | Value |
-|---|---|
-| 100% | `1.0` |
-| 125% | `1.25` |
-| 150% | `1.5` |
-| 200% | `2.0` |
+| ------- | ----- |
+| 100%    | 1.0   |
+| 125%    | 1.25  |
+| 150%    | 1.5   |
+| 175%    | 1.75  |
+| 200%    | 2.0   |
 
-Example:
+Manual override is still supported:
 
 ```ts
-visor.setScaleFactor(1.5);
+visor.loadConfig({
+  scaleFactor: 1.5
+});
 ```
 
-Incorrect scaling values may cause:
+---
+
+# Multi-Scale Image Matching
+
+Visor automatically performs multi-scale template matching to support:
+
+* Different Windows scaling settings
+* Different screen resolutions
+* High-DPI displays
+* Cross-machine execution
+
+By default Visor evaluates templates across multiple scale levels and automatically selects the best match.
+
+Supported environments include:
+
+* 100% scaling
+* 125% scaling
+* 150% scaling
+* 175% scaling
+* 200% scaling
 
-- failed image matching
-- incorrect mouse positioning
-- OCR region issues
+This significantly improves image matching reliability when automation is executed across different machines.
 
 ---
 
@@ -163,7 +179,12 @@ const exists =
 ## Wait For Image
 
 ```ts
-await visor.wait("loading-complete.png");
+await visor.wait("save.png");
+
+await visor.wait("save.png", {
+  confidence: 0.9,
+  timeout: 10000
+});
 ```
 
 ---
@@ -172,8 +193,8 @@ await visor.wait("loading-complete.png");
 
 ```ts
 await visor.waitAny([
-  "home-light.png",
-  "home-dark.png"
+  "light-theme.png",
+  "dark-theme.png"
 ]);
 ```
 
@@ -194,8 +215,8 @@ await visor.clickAny([
 
 ```ts
 await visor.dragDrop(
-  "file.png",
-  "folder.png"
+  "source.png",
+  "target.png"
 );
 ```
 
@@ -211,14 +232,16 @@ await visor.hover("menu.png");
 
 # OCR Automation
 
-Visor includes OCR automation using Tesseract.js.
+Visor includes OCR automation powered by Tesseract.js.
 
 OCR supports:
 
-- full screen text detection
-- region-based OCR
-- text matching
-- OCR click automation
+* Full-screen OCR
+* Region OCR
+* Text search
+* Text clicking
+* Text waiting
+* OCR occurrence indexing
 
 ---
 
@@ -233,6 +256,22 @@ console.log(result.text);
 
 ---
 
+## Read Region
+
+```ts
+const result =
+  await visor.readRegion({
+    x: 100,
+    y: 100,
+    width: 500,
+    height: 300
+  });
+
+console.log(result.text);
+```
+
+---
+
 ## Find Text
 
 ```ts
@@ -258,21 +297,44 @@ await visor.waitText("Success");
 
 ---
 
+# OCR Occurrence Indexing
+
+When the same text appears multiple times on screen, Visor allows selecting a specific occurrence.
+
+```ts
+await visor.clickText("Inbox", 0);
+await visor.clickText("Inbox", 1);
+await visor.clickText("Inbox", 2);
+```
+
+OCR elements are processed from:
+
+```text
+Top → Bottom
+Left → Right
+```
+
+This improves automation stability when multiple matching text elements exist on screen.
+
+---
+
 # OCR Optimizations
 
 Visor includes:
 
-- shared OCR worker reuse
-- OCR preprocessing
-- confidence filtering
-- grayscale normalization
-- sharpened OCR processing
+* Shared OCR worker reuse
+* OCR preprocessing
+* Grayscale normalization
+* Image sharpening
+* Confidence filtering
+* OCR occurrence indexing
 
-These optimizations improve:
+Benefits:
 
-- OCR speed
-- OCR accuracy
-- framework stability
+* Faster OCR execution
+* Improved OCR accuracy
+* Lower memory usage
+* Improved framework stability
 
 ---
 
@@ -339,8 +401,6 @@ await visor.press(
 
 # Screenshot Automation
 
-## Capture Screenshot
-
 ```ts
 await visor.captureScreenshot(
   "./screenshots/home.png"
@@ -367,128 +427,34 @@ await visor.closeApp("notepad.exe");
 
 ---
 
-# Teams Automation Example
-
-```ts
-import { visor } from "visor";
-
-async function teamsDemo() {
-
-  visor.loadConfig({
-    scaleFactor: 1.5,
-    imagePath: "./images",
-    debug: true
-  });
-
-  await visor.openApp(
-    "ms-teams.exe"
-  );
-
-  await visor.waitAny([
-    "teams-light.png",
-    "teams-dark.png"
-  ]);
-
-  await visor.clickAny([
-    "chat-light.png",
-    "chat-dark.png"
-  ]);
-
-  await visor.clickText("Search");
-
-  await visor.type("John");
-
-}
-```
-
----
-
 # Confidence Thresholds
 
-Most image matching APIs support confidence values.
-
-Accepted range:
+Supported range:
 
-```txt
-0.0 to 1.0
+```text
+0.0 - 1.0
 ```
 
 Recommended values:
 
-| Confidence | Usage |
-|---|---|
-| `0.7` | Dynamic UI |
-| `0.8` | Standard usage |
-| `0.9+` | Strict matching |
-
-Lower confidence increases flexibility but may increase false positives.
-
----
-
-# Performance Notes
-
-## OCR
-
-OCR operations are computationally expensive.
-
-OCR speed depends on:
-
-- display resolution
-- text density
-- screen complexity
-- hardware performance
-
----
-
-# Debug Logging
-
-Enable debug logs:
-
-```ts
-visor.setDebug(true);
-```
-
----
-
-# Best Practices
-
-## Use Stable Images
-
-Prefer:
-
-- high contrast images
-- unique UI elements
-- properly cropped templates
-
-Avoid:
-
-- blurry screenshots
-- partially hidden elements
-- scaled screenshots
-
----
-
-## Use Proper Scaling
-
-Always configure:
-
-```ts
-visor.setScaleFactor(...);
-```
-
-before automation begins.
+| Confidence | Usage           |
+| ---------- | --------------- |
+| 0.7        | Dynamic UI      |
+| 0.8        | General usage   |
+| 0.9        | Strict matching |
 
 ---
 
-## Prefer Wait APIs
+# Performance Improvements
 
-Prefer:
+Visor includes:
 
-```ts
-await visor.wait(...);
-```
+* Shared OCR worker reuse
+* Multi-scale image matching
+* OCR preprocessing pipeline
+* Automatic display scaling detection
 
-instead of excessive hard sleeps.
+These improvements increase reliability across varying display configurations and reduce OCR initialization overhead.
 
 ---
 
@@ -498,10 +464,10 @@ instead of excessive hard sleeps.
 
 Possible causes:
 
-- incorrect scaling
-- wrong image path
-- low confidence threshold
-- theme mismatch
+* Incorrect image path
+* Low confidence threshold
+* Theme mismatch
+* Poor template quality
 
 ---
 
@@ -509,40 +475,42 @@ Possible causes:
 
 Possible causes:
 
-- blurry UI
-- small font size
-- low contrast text
+* Small fonts
+* Low contrast text
+* Blurry UI elements
 
 ---
 
 ## Mouse Clicking Incorrect Position
 
-Possible causes:
+Visor automatically detects Windows display scaling.
+
+If required, manually override:
 
-- incorrect scale factor
-- Windows DPI scaling mismatch
+```ts
+visor.loadConfig({
+  scaleFactor: 1.5
+});
+```
 
 ---
 
 # Roadmap
 
-Planned features:
-
-- Parallel image matching
-- Advanced OCR tuning
-- Electron recorder
-- AI-assisted automation
+* Template cache
+* OCR cache
+* Scale cache
+* Parallel image matching
+* Advanced OCR tuning
+* Electron recorder
+* AI-assisted automation
 
 ---
 
 # Tech Stack
 
-Visor uses:
-
-- OpenCV
-- Tesseract.js
-- screenshot-desktop
-- sharp
-- nut.js
-
----
+* OpenCV
+* Tesseract.js
+* screenshot-desktop
+* sharp
+* nut.js