# mac-system-ocr

**Repository Path**: mirrors_magic-akari/mac-system-ocr

## Basic Information

- **Project Name**: mac-system-ocr
- **Description**: A MacOS OCR Native Node.js Module
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-03
- **Last Updated**: 2026-10-20

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# @cherrystudio/mac-system-ocr

> ⚠️ **IMPORTANT UPDATE NOTICE**: Version 1.0.0 includes critical fixes for electron-builder compatibility. Please update to the latest version:
> ```bash
> 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.

[![npm version](https://badge.fury.io/js/@cherrystudio%2Fmac-system-ocr.svg)](https://badge.fury.io/js/@cherrystudio%2Fmac-system-ocr)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

## 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

```bash
npm install @cherrystudio/mac-system-ocr
```

## Development

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

## Quick Start

```typescript
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

```typescript
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

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

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

### Multi-language Recognition

```typescript
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](LICENSE) file for details.