macos-vision 0.1.0

package/README.md

@@ -0,0 +1,164 @@
+# macos-vision
+
+> Apple Vision for Node.js — native, fast, offline, no API keys required.
+
+Uses macOS's built-in [Vision framework](https://developer.apple.com/documentation/vision) via a compiled Swift binary. Works completely offline. No cloud services, no API keys, no Python, zero runtime dependencies.
+
+## Requirements
+
+- macOS 12+
+- Node.js 18+
+- Xcode Command Line Tools
+
+```bash
+xcode-select --install
+```
+
+## Installation
+
+```bash
+npm install macos-vision
+```
+
+The native Swift binary is compiled automatically on install.
+
+## Usage
+
+```js
+import { ocr, detectFaces, detectBarcodes, detectRectangles, detectDocument, classify } from 'macos-vision'
+
+// OCR — plain text
+const text = await ocr('photo.jpg')
+
+// OCR — structured blocks with bounding boxes
+const blocks = await ocr('photo.jpg', { format: 'blocks' })
+
+// Detect faces
+const faces = await detectFaces('photo.jpg')
+
+// Detect barcodes and QR codes
+const codes = await detectBarcodes('invoice.jpg')
+
+// Detect rectangular shapes (tables, forms, cards)
+const rects = await detectRectangles('document.jpg')
+
+// Find document boundary in a photo
+const doc = await detectDocument('photo.jpg') // DocumentBounds | null
+
+// Classify image content
+const labels = await classify('photo.jpg')
+```
+
+## API
+
+### `ocr(imagePath, options?)`
+
+Extracts text from an image.
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `imagePath` | `string` | — | Path to image (PNG, JPG, JPEG, WEBP) |
+| `options.format` | `'text' \| 'blocks'` | `'text'` | Plain text or structured blocks with coordinates |
+
+Returns `Promise<string>` or `Promise<VisionBlock[]>`.
+
+```ts
+interface VisionBlock {
+  text: string
+  x: number       // 0–1 from left
+  y: number       // 0–1 from top
+  width: number   // 0–1
+  height: number  // 0–1
+}
+```
+
+---
+
+### `detectFaces(imagePath)`
+
+Detects human faces and returns their bounding boxes.
+
+```ts
+interface Face {
+  x: number; y: number; width: number; height: number
+  confidence: number  // 0–1
+}
+```
+
+---
+
+### `detectBarcodes(imagePath)`
+
+Detects barcodes and QR codes and decodes their payload.
+
+```ts
+interface Barcode {
+  type: string    // e.g. 'org.iso.QRCode', 'org.gs1.EAN-13'
+  value: string   // decoded content
+  x: number; y: number; width: number; height: number
+}
+```
+
+---
+
+### `detectRectangles(imagePath)`
+
+Finds rectangular shapes (documents, tables, cards, forms).
+
+```ts
+interface Rectangle {
+  topLeft: [number, number]; topRight: [number, number]
+  bottomLeft: [number, number]; bottomRight: [number, number]
+  confidence: number
+}
+```
+
+---
+
+### `detectDocument(imagePath)`
+
+Finds the boundary of a document in a photo (e.g. paper on a desk). Returns `null` if no document is found.
+
+```ts
+interface DocumentBounds {
+  topLeft: [number, number]; topRight: [number, number]
+  bottomLeft: [number, number]; bottomRight: [number, number]
+  confidence: number
+}
+```
+
+---
+
+### `classify(imagePath)`
+
+Returns top image classification labels with confidence scores.
+
+```ts
+interface Classification {
+  identifier: string   // e.g. 'document', 'outdoor', 'animal'
+  confidence: number   // 0–1
+}
+```
+
+---
+
+## Why macos-vision?
+
+| | macos-vision | Tesseract.js | Cloud APIs |
+|---|---|---|---|
+| Offline | ✅ | ✅ | ❌ |
+| No API key | ✅ | ✅ | ❌ |
+| Native speed | ✅ | ❌ | — |
+| Zero runtime deps | ✅ | ❌ | ❌ |
+| OCR with bounding boxes | ✅ | ✅ | ✅ |
+| Face detection | ✅ | ❌ | ✅ |
+| Barcode / QR | ✅ | ❌ | ✅ |
+| Document detection | ✅ | ❌ | ✅ |
+| Image classification | ✅ | ❌ | ✅ |
+| macOS only | ✅ | ❌ | ❌ |
+
+Apple Vision is the same engine used by macOS Spotlight, Live Text, and Shortcuts — highly optimized and accurate.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,85 @@
+export interface VisionBlock {
+    /** Recognized text */
+    text: string;
+    /** Horizontal position, 0–1 from left */
+    x: number;
+    /** Vertical position, 0–1 from top */
+    y: number;
+    /** Width, 0–1 relative to image */
+    width: number;
+    /** Height, 0–1 relative to image */
+    height: number;
+}
+export interface OcrOptions {
+    /** Return plain text (default) or structured blocks with coordinates */
+    format?: 'text' | 'blocks';
+}
+export declare function ocr(imagePath: string, options?: {
+    format?: 'text';
+}): Promise<string>;
+export declare function ocr(imagePath: string, options: {
+    format: 'blocks';
+}): Promise<VisionBlock[]>;
+export interface Face {
+    /** Horizontal position, 0–1 from left */
+    x: number;
+    /** Vertical position, 0–1 from top */
+    y: number;
+    /** Width, 0–1 relative to image */
+    width: number;
+    /** Height, 0–1 relative to image */
+    height: number;
+    /** Detection confidence, 0–1 */
+    confidence: number;
+}
+export declare function detectFaces(imagePath: string): Promise<Face[]>;
+export interface Barcode {
+    /** Symbology type, e.g. 'org.iso.QRCode', 'org.gs1.EAN-13', 'org.iso.Code128' */
+    type: string;
+    /** Decoded payload value */
+    value: string;
+    /** Horizontal position, 0–1 from left */
+    x: number;
+    /** Vertical position, 0–1 from top */
+    y: number;
+    /** Width, 0–1 relative to image */
+    width: number;
+    /** Height, 0–1 relative to image */
+    height: number;
+}
+export declare function detectBarcodes(imagePath: string): Promise<Barcode[]>;
+export interface Rectangle {
+    /** Top-left corner [x, y], values 0–1 */
+    topLeft: [number, number];
+    /** Top-right corner [x, y], values 0–1 */
+    topRight: [number, number];
+    /** Bottom-left corner [x, y], values 0–1 */
+    bottomLeft: [number, number];
+    /** Bottom-right corner [x, y], values 0–1 */
+    bottomRight: [number, number];
+    /** Detection confidence, 0–1 */
+    confidence: number;
+}
+export declare function detectRectangles(imagePath: string): Promise<Rectangle[]>;
+export interface DocumentBounds {
+    /** Top-left corner [x, y], values 0–1 */
+    topLeft: [number, number];
+    /** Top-right corner [x, y], values 0–1 */
+    topRight: [number, number];
+    /** Bottom-left corner [x, y], values 0–1 */
+    bottomLeft: [number, number];
+    /** Bottom-right corner [x, y], values 0–1 */
+    bottomRight: [number, number];
+    /** Detection confidence, 0–1 */
+    confidence: number;
+}
+/** Returns the detected document boundary, or null if no document found. */
+export declare function detectDocument(imagePath: string): Promise<DocumentBounds | null>;
+export interface Classification {
+    /** Category identifier, e.g. 'document', 'outdoor', 'animal' */
+    identifier: string;
+    /** Confidence score, 0–1 */
+    confidence: number;
+}
+/** Returns top image classifications sorted by confidence (highest first). */
+export declare function classify(imagePath: string): Promise<Classification[]>;

package/dist/index.js

@@ -0,0 +1,51 @@
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+const execFileAsync = promisify(execFile);
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BIN_PATH = resolve(__dirname, '../bin/vision-helper');
+async function run(flag, imagePath) {
+    const { stdout } = await execFileAsync(BIN_PATH, [flag, resolve(imagePath)]);
+    return stdout;
+}
+export async function ocr(imagePath, options = {}) {
+    const absPath = resolve(imagePath);
+    const { format = 'text' } = options;
+    if (format === 'blocks') {
+        const { stdout } = await execFileAsync(BIN_PATH, ['--json', absPath]);
+        const raw = JSON.parse(stdout);
+        return raw.map((b) => ({ text: b.t, x: b.x, y: b.y, width: b.w, height: b.h }));
+    }
+    const { stdout } = await execFileAsync(BIN_PATH, [absPath]);
+    return stdout.trim();
+}
+export async function detectFaces(imagePath) {
+    const raw = JSON.parse(await run('--faces', imagePath));
+    return raw.map((f) => ({ x: f.x, y: f.y, width: f.w, height: f.h, confidence: f.confidence }));
+}
+export async function detectBarcodes(imagePath) {
+    const raw = JSON.parse(await run('--barcodes', imagePath));
+    return raw.map((b) => ({
+        type: b.type,
+        value: b.value,
+        x: b.x,
+        y: b.y,
+        width: b.w,
+        height: b.h,
+    }));
+}
+export async function detectRectangles(imagePath) {
+    const raw = JSON.parse(await run('--rectangles', imagePath));
+    return raw;
+}
+/** Returns the detected document boundary, or null if no document found. */
+export async function detectDocument(imagePath) {
+    const raw = JSON.parse(await run('--document', imagePath));
+    return raw.length > 0 ? raw[0] : null;
+}
+/** Returns top image classifications sorted by confidence (highest first). */
+export async function classify(imagePath) {
+    const raw = JSON.parse(await run('--classify', imagePath));
+    return raw;
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "macos-vision",
+  "version": "0.1.0",
+  "description": "Apple Vision OCR & image analysis for Node.js — native, fast, offline, no API keys",
+  "author": "Adrian Wolczuk",
+  "license": "MIT","type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/woladi/macos-vision.git"
+},
+  "scripts": {
+    "build-native": "node scripts/build-native.js",
+    "postinstall": "node scripts/build-native.js",
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "ocr",
+    "macos",
+    "apple-vision",
+    "image",
+    "text-extraction",
+    "vision",
+    "native",
+    "offline",
+    "face-detection",
+    "barcode",
+    "qr-code",
+    "document-detection",
+    "image-classification"
+  ],
+  "os": [
+    "darwin"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.9"
+  }
+}

package/scripts/build-native.js

@@ -0,0 +1,28 @@
+import { execSync } from 'child_process';
+import { mkdirSync, existsSync } from 'fs';
+import { fileURLToPath } from 'url';
+import path from 'path';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const root = path.resolve(__dirname, '..');
+const binDir = path.join(root, 'bin');
+const binPath = path.join(binDir, 'vision-helper');
+const swiftSrc = path.join(root, 'src', 'native', 'vision-helper.swift');
+
+if (existsSync(binPath)) {
+  process.exit(0);
+}
+
+if (!mkdirSync(binDir, { recursive: true }) === false) {
+  // dir created
+}
+
+try {
+  execSync(`swiftc -O "${swiftSrc}" -o "${binPath}"`, { stdio: 'inherit' });
+  console.log('✅ macos-vision: native binary compiled successfully');
+} catch {
+  console.error('❌ macos-vision: Swift compilation failed.');
+  console.error('   Make sure Xcode Command Line Tools are installed:');
+  console.error('   xcode-select --install');
+  process.exit(1);
+}