@cherrystudio/mac-system-ocr v0.2.2

@cherrystudio/mac-system-ocr

⚠️ IMPORTANT UPDATE NOTICE: Version 1.0.0 includes critical fixes for electron-builder compatibility. Please update to the latest version:

npm install @cherrystudio/mac-system-ocr@latest
# or
yarn upgrade @cherrystudio/mac-system-ocr@latest

Mac OCR Native Node.js Module

A high-performance OCR (Optical Character Recognition) Node.js native module powered by macOS Vision Framework. This module provides fast and accurate text recognition capabilities for various image formats.

Features

• 🚀 Native performance using macOS Vision Framework
• 🖼️ Support for multiple image formats
• 🌍 Multi-language text recognition
• ⚡️ Promise-based async API

Requirements

• macOS 10.15 or later
• Node.js 23.0.0 or later (maybe support former version, but not tested)
• Xcode Command Line Tools

Installation

npm install @cherrystudio/mac-system-ocr

Development

git clone https://github.com/DeJeune/mac-system-ocr.git
cd mac-system-ocr
npm install
npm run build

Quick Start

import MacOCR from '@cherrystudio/mac-system-ocr';

// Basic usage
async function recognizeText() {
  try {
    const text = await MacOCR.recognizeFromPath('path/to/your/image.png');
    console.log('Recognized text:', text);
  } catch (error) {
    console.error('OCR failed:', error);
  }
}

// With options
async function recognizeWithOptions() {
  const options = {
    languages: 'en-US, zh-Hans', // Specify recognition languages
    recognitionLevel: MacOCR.RECOGNITION_LEVEL_ACCURATE,
    minConfidence: 0.5,
  };
  
  const text = await MacOCR.recognizeFromPath('path/to/your/image.jpg', options);
  console.log('Recognized text:', text);
}

API Reference

MacOCR.recognizeFromPath(imagePath: string, options?: RecognizeOptions): Promise<string>

Performs OCR on the specified image file and returns the recognized text.

Parameters

• imagePath (string): Path to the image file
• options (optional): Configuration object for OCR

RecognizeOptions

interface RecognizeOptions {
  languages?: string; // Recognition languages, multiple languages separated by commas (default: 'en-US')
  recognitionLevel?: typeof MacOCR.RECOGNITION_LEVEL_FAST | typeof MacOCR.RECOGNITION_LEVEL_ACCURATE; // Use fast recognition mode  or accurate recognition mode
  minConfidence?: number;  // Minimum confidence score (default: 0.0)
}

Supported Languages

• en-US: English
• zh-Hans: Simplified Chinese
• zh-Hant: Traditional Chinese
• ja-JP: Japanese
• And more...

Returns

Returns a Promise that resolves with the recognized text string.

Errors

The following errors may be thrown:

• FileNotFoundError: Image file does not exist
• InvalidFormatError: Unsupported image format
• OCRError: Recognition failed

MacOCR.recognizeBatchFromPath(imagePaths: string[], options?: RecognizeBatchOptions): Promise<string[]>

MacOCR.recognizeFromBuffer(imageBuffer: Buffer | Uint8Array, options?: RecognizeOptions): Promise<string>

Examples

Basic Text Recognition

import { MacOCR } from '@cherrystudio/mac-system-ocr';

const text = await MacOCR.recognizeFromPath('screenshot.png');
console.log(text);

Multi-language Recognition

import { MacOCR } from '@cherrystudio/mac-system-ocr';

const text = await MacOCR.recognizeFromPath('document.jpg', {
  languages: 'en-US, zh-Hans',
  recognitionLevel: MacOCR.RECOGNITION_LEVEL_ACCURATE,
  minConfidence: 0.5,
});
console.log(text);

Performance Tips

• Use recognitionLevel: 1 option for accurate recognition
• JPEG and PNG formats are recommended for best performance
• Ensure images have good contrast and resolution for optimal results

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT License - see the LICENSE file for details.