scanic 0.1.7 → 1.0.2

package/README.md

@@ -11,49 +11,58 @@
     <a href="https://npmjs.com/package/scanic"><img src="https://badgen.net/npm/v/scanic"></a>
 </p>
 
-# Scanic
+# Scanic 📄⚡
 
-**Modern Document Scanner for the Web**
+**Ultra-fast, production-ready document scanning for the modern Web.**
 
-Scanic is a blazing-fast, lightweight, and modern document scanner library written in JavaScript and rust (WASM). It enables developers to detect, scan, and process documents from images directly in the browser or Node.js, with no dependencies or external services.
+Scanic is a high-performance document scanner library that brings professional-grade document edge detection and perspective correction to the browser and Node.js. By combining **Rust-powered WebAssembly** for pixel crunching and **GPU-accelerated Canvas** for image warping, Scanic delivers near-native performance (~10ms transforms) with a tiny footprint.
 
-## Why Scanic?
+---
 
-I always wanted to use document scanning features within web environments for years. While OpenCV makes this easy, it comes at the cost of a **30+ MB** download.
+## 🚀 Why Scanic?
 
-Scanic combines pure JavaScript algorithms with **Rust-compiled WebAssembly** for performance-critical operations like Gaussian blur, Canny edge detection, and gradient calculations. This hybrid approach delivers near-native performance while maintaining JavaScript's accessibility and a lightweight footprint.
+Traditional web scanning solutions often force a trade-off:
+- **OpenCV.js**: Powerful, but requires a massive **30MB+** download.
+- **Pure JS**: Lightweight, but struggles with real-time performance and complex transforms.
 
-Performance-wise, I'm working to match OpenCV solutions while maintaining the lightweight footprint - this is an ongoing area of improvement.
+**Scanic bridges this gap:**
+- **Hybrid Engine**: Rust/WASM handles the CPU-heavy edge detection.
+- **Turbo Warp**: Custom Triangle Subdivision algorithm utilizes the GPU for perspective correction.
+- **Zero Latency**: Designed for real-time applications like webcam scanning.
 
-This library is heavily inspired by [jscanify](https://github.com/puffinsoft/jscanify) 
+---
 
-## Features
+## ✨ Features
 
-- 📄 **Document Detection**: Accurately finds and extracts document contours from images
-- ⚡ **Pure JavaScript**: Works everywhere JavaScript runs
-- 🦀 **Rust WebAssembly**: Performance-critical operations optimized with Rust-compiled WASM
-- 🛠️ **Easy Integration**: Simple API for web apps, Electron, or Node.js applications
-- 🏷️ **MIT Licensed**: Free for personal and commercial use
-- 📦 **Lightweight**: Small bundle size (< 100kb) compared to OpenCV-based solutions (+30 mb)
+- 🎯 **Pinpoint Accuracy**: Robust document contour detection even in low-contrast environments.
+- ⚡ **Turbocharged Warp**: Perspective transforms in **< 10ms** (vs 500ms+ in standard loops).
+- 🦀 **WASM Core**: High-performance Gaussian Blur, Canny Edge Detection, and Dilation.
+- 🛠️ **Modern API**: Clean, Promise-based API with full **TypeScript** support.
+- 📦 **Featherweight**: Under **100KB** total size (gzipped).
+- 🧪 **Production Grade**: Built-in regression tests with physical image baselines.
 
-## Demo
+---
 
-Try the live demo: [Open Demo](https://marquaye.github.io/scanic/demo.html)
-
-## Installation
+## 🛠️ Installation
 
 ```bash
+# via npm
 npm install scanic
-```
 
-Or use via CDN:
+# via yarn
+yarn add scanic
+```
 
+### CDN
 ```html
 <script src="https://unpkg.com/scanic/dist/scanic.js"></script>
 ```
 
-## Usage
+---
 
+## 📖 Usage
+
+### Simple Usage
 ```js
 import { scanDocument, extractDocument } from 'scanic';
 
@@ -68,17 +77,25 @@ const extracted = await scanDocument(imageElement, { mode: 'extract' });
 if (extracted.success) {
   document.body.appendChild(extracted.output); // Display extracted document
 }
+```
 
-// Manual extraction with custom corner points (for image editors)
-const corners = {
-  topLeft: { x: 100, y: 50 },
-  topRight: { x: 400, y: 60 },
-  bottomRight: { x: 390, y: 300 },
-  bottomLeft: { x: 110, y: 290 }
-};
-const manualExtract = await extractDocument(imageElement, corners);
-if (manualExtract.success) {
-  document.body.appendChild(manualExtract.output);
+### Optimized Usage (Recommended for Batch/Real-time)
+The `Scanner` class maintains a persistent WebAssembly instance, avoiding the overhead of re-initializing WASM for every scan.
+
+```js
+import { Scanner } from 'scanic';
+
+const scanner = new Scanner();
+
+// Initialize once (optional, scan() will initialize if needed)
+await scanner.initialize();
+
+// Scan multiple images efficiently
+async function onFrame(img) {
+  const result = await scanner.scan(img, { mode: 'extract' });
+  if (result.success) {
+    // Process result...
+  }
 }
 ```
 
@@ -121,37 +138,50 @@ async function processDocument() {
 // <div id="output"></div>
 ```
 
-## API Reference
-
-### Core Functions
-
-#### `scanDocument(image, options?)`
-Main entry point for document scanning with flexible modes and output options.
-
-**Parameters:**
-- `image`: HTMLImageElement, HTMLCanvasElement, or ImageData
-- `options`: Optional configuration object
-  - `mode`: String - 'detect' (default), or 'extract'
-    - `'detect'`: Only detect document, return corners/contour info (no image processing)
-    - `'extract'`: Extract/warp the document region
-  - `output`: String - 'canvas' (default), 'imagedata', or 'dataurl'
-  - `debug`: Boolean (default: false) - Enable debug information
-  - Detection options:
-    - `maxProcessingDimension`: Number (default: 800) - Maximum dimension for processing in pixels
-    - `lowThreshold`: Number (default: 75) - Lower threshold for Canny edge detection
-    - `highThreshold`: Number (default: 200) - Upper threshold for Canny edge detection
-    - `dilationKernelSize`: Number (default: 3) - Kernel size for dilation
-    - `dilationIterations`: Number (default: 1) - Number of dilation iterations
-    - `minArea`: Number (default: 1000) - Minimum contour area for document detection
-    - `epsilon`: Number - Epsilon for polygon approximation
-
-**Returns:** `Promise<{ output, corners, contour, debug, success, message }>`
-
-- `output`: Processed image (null for 'detect' mode)
-- `corners`: Object with `{ topLeft, topRight, bottomRight, bottomLeft }` coordinates
-- `contour`: Array of contour points
-- `success`: Boolean indicating if document was detected
-- `message`: Status message
+## ⚙️ API Reference
+
+### `scanDocument(image, options?)`
+The primary function for detecting and extracting documents.
+
+| Parameter | Type | Description |
+| :--- | :--- | :--- |
+| `image` | `HTMLImage\|Canvas\|ImageData` | The source image to scan. |
+| `options` | `Object` | Configuration options (see below). |
+
+#### `options` Properties
+| Option | Type | Default | Description |
+| :--- | :--- | :--- | :--- |
+| `mode` | `'detect' \| 'extract'` | `'detect'` | `'detect'` returns coordinates; `'extract'` returns the warped image. |
+| `output` | `'canvas' \| 'imagedata' \| 'dataurl'` | `'canvas'` | The format of the returned processed image. |
+| `maxProcessingDimension` | `number` | `800` | Downscales image to this size for detection (faster). |
+| `lowThreshold` | `number` | `75` | Lower threshold for Canny edge detection. |
+| `highThreshold` | `number` | `200` | Upper threshold for Canny edge detection. |
+| `minArea` | `number` | `1000` | Minimum pixel area to consider a contour a "document". |
+| `debug` | `boolean` | `false` | If true, returns intermediate processing steps. |
+
+#### Return Value
+Returns a `Promise<ScannerResult>`:
+```ts
+{
+  success: boolean;       // Did we find a document?
+  corners: CornerPoints;  // { topLeft, topRight, bottomRight, bottomLeft }
+  output: any;            // The warped image (if mode is 'extract')
+  contour: Array<Point>;  // Raw detection points
+  timings: Array<Object>; // Performance breakdown
+  message: string;        // Status or error message
+}
+```
+
+---
+
+### `new Scanner()`
+The recommended class for high-performance applications (Webcam, Batch processing).
+
+```js
+const scanner = new Scanner();
+await scanner.initialize(); // Pre-loads WASM
+const result = await scanner.scan(image, options);
+```
 
 ## Examples
 
@@ -195,15 +225,18 @@ const rawData = await scanDocument(imageElement, {
 
 ```
 
-## Framework Examples
+## 💻 Framework Examples
 
+Scanic is framework-agnostic but works great with modern UI libraries:
 
-👉 **[Vue.js Example & Guide](docs/vue-example.md)**
+| Framework | Link |
+| :--- | :--- |
+| **Vue 3** | [Vue.js Example & Guide](docs/vue-example.md) |
+| **React** | [React Example & Guide](docs/react-example.md) |
 
-👉 **[React Example & Guide](docs/react-example.md)**
+---
 
-
-## Development
+## 🛠️ Development
 
 Clone the repository and set up the development environment:
 
@@ -237,8 +270,48 @@ npm run build:wasm
 
 This uses Docker to build the WASM module without requiring local Rust installation.
 
+### Testing
 
-### Performance Architecture
+Scanic uses Vitest for unit and regression testing. We test against real document images to ensure detection accuracy remains consistent.
+
+```bash
+npm test
+```
+
+
+## 🖥️ Node.js Support
+
+Scanic can run on the server! Since it relies on the Canvas API, you need to provide a canvas implementation (like `node-canvas`) and a DOM environment (`jsdom`).
+
+```js
+import { scanDocument } from 'scanic';
+import { loadImage } from 'canvas';
+import { JSDOM } from 'jsdom';
+
+// Setup global environment
+const dom = new JSDOM();
+global.document = dom.window.document;
+global.ImageData = dom.window.ImageData;
+
+const img = await loadImage('document.jpg');
+const result = await scanDocument(img, { mode: 'extract' });
+```
+
+---
+
+## 📊 Comparison
+
+| Feature | Scanic | jscanify | OpenCV.js |
+| :--- | :--- | :--- | :--- |
+| **Download Size** | **~100KB** | ~1MB | ~30MB |
+| **Perspective Speed** | **~10ms** | ~200ms | ~5ms |
+| **WASM Optimized** | ✅ Yes | ❌ No | ✅ Yes |
+| **GPU Acceleration** | ✅ Yes | ❌ No | ❌ No |
+| **TypeScript** | ✅ Yes | ❌ No | ✅ Yes |
+
+---
+
+## 🏗️ Performance Architecture
 
 Scanic uses a **hybrid JavaScript + WebAssembly approach**:
 
@@ -250,20 +323,25 @@ Scanic uses a **hybrid JavaScript + WebAssembly approach**:
   - Non-maximum suppression for edge thinning
   - Morphological operations (dilation/erosion)
 
-## Contributing
+## 🤝 Contributing
+
+Contributions are welcome! Whether it's reporting a bug, suggesting a feature, or submitting a pull request, your help is appreciated.
+
+1. **Report Issues**: Use the GitHub Issue tracker.
+2. **Pull Requests**:
+   - Fork the repository.
+   - Create a feature branch.
+   - Commit your changes.
+   - Open a Pull Request.
+
+---
 
-Contributions are welcome! Here's how you can help:
+## 📜 Credits
 
-1. **Report Issues**: Found a bug? Open an issue with details and reproduction steps
-2. **Feature Requests**: Have an idea? Create an issue to discuss it
-3. **Pull Requests**: Ready to contribute code? 
-   - Fork the repository
-   - Create a feature branch (`git checkout -b feature/amazing-feature`)
-   - Commit your changes (`git commit -m 'Add amazing feature'`)
-   - Push to the branch (`git push origin feature/amazing-feature`)
-   - Open a Pull Request
+- Inspired by [jscanify](https://github.com/puffinsoft/jscanify).
+- WASM Blur module powered by Rust.
 
-Please ensure your code follows the existing style.
+---
 
 ## 💖 Sponsors
 
@@ -306,15 +384,14 @@ Please ensure your code follows the existing style.
 
 </div>
 
-## Roadmap
+## 🗺️ Roadmap
 
-- [ ] Performance optimizations to match OpenCV speed
+- [x] TypeScript definitions
+- [x] High-performance perspective transformation (Triangle Subdivision)
 - [ ] Enhanced WASM module with additional Rust-optimized algorithms
-- [ ] SIMD vectorization for more image processing operations
-- [ ] TypeScript definitions
-- [ ] Additional image enhancement filters
-- [ ] Mobile-optimized processing
 - [ ] WebGPU acceleration for supported browsers
+- [ ] Mobile-optimized real-time video processing frames
+- [ ] Additional image enhancement filters (Adaptive Thresholding, B&W)
 
 ## License