Multilingual PureJS OCR 🚀

A powerful onnxruntime-node based, pure JavaScript OCR library that works directly in Node.js - no Python dependencies required! Extract text from images with industry-leading accuracy using PaddleOCR models.

✨ Features

• 🌍 Multilingual Support: English, Chinese, Japanese, Korean, and Latin languages
• 🎯 High Accuracy: Based on PaddleOCR v3/v4 models
• 📦 Zero Python Dependencies: 100% JavaScript/Node.js implementation
• 🧠 ONNX Runtime Node: Efficient, high-performance model inference directly in Node.js
• 🔧 Highly Customizable: Configure detection, recognition, and grouping parameters
• 🎨 Smart Text Grouping: Automatically groups text into paragraphs
• 🔌 Bring Your Own Models: Use custom ONNX models
• ⚡ Production Ready: Built with performance and reliability in mind
• 🚀 Plug and Play: All models and dictionaries included - just install and run!

📥 Installation

npm install multilingual-purejs-ocr

🚀 Quick Start

import Ocr from 'multilingual-purejs-ocr';

// Create OCR instance with default settings (English)
const ocr = await Ocr.create();

// Detect text in an image
const result = await ocr.detect('./image.jpg');

console.log('Total elements:', result.totalElements);
console.log('Paragraphs:', result.paragraphs);
console.log('Individual elements:', result.data);

📖 Usage Examples

Basic Usage - Different Languages

// English (default)
const ocrEn = await Ocr.create({ language: 'en' });
const resultEn = await ocrEn.detect('./english.jpg');

// Chinese
const ocrCh = await Ocr.create({ language: 'ch' });
const resultCh = await ocrCh.detect('./chinese.jpg');

// Japanese
const ocrJa = await Ocr.create({ language: 'ja' });
const resultJa = await ocrJa.detect('./japanese.jpg');

// Korean
const ocrKo = await Ocr.create({ language: 'ko' });
const resultKo = await ocrKo.detect('./korean.jpg');

// Latin languages (Portuguese, Spanish, French, etc.)
const ocrLatin = await Ocr.create({ language: 'latin' });
const resultLatin = await ocrLatin.detect('./latin.jpg');

Advanced Configuration

const ocr = await Ocr.create({
  // Language selection
  language: 'en',
  
  // Detection parameters
  detectionThreshold: 0.1,      // Lower = more sensitive (0-1)
  minBoxSize: 3,                // Minimum text box size in pixels
  maxBoxSize: 2000,             // Maximum text box size in pixels
  unclipRatio: 1.5,             // Box expansion ratio
  
  // Recognition parameters
  confidenceThreshold: 0.5,     // Minimum confidence to accept text (0-1)
  imageHeight: 48,              // Recognition model input height
  removeDuplicateChars: true,   // Remove duplicate characters
  
  // Text grouping configuration
  grouping: {
    verticalThresholdRatio: 1.2,
    horizontalThresholdRatio: 2.5,
    minOverlapRatio: 0.3,
    maxVerticalOffsetRatio: 0.5
  }
});

const result = await ocr.detect('./image.jpg');

Using Custom Models

const ocr = await Ocr.create({
  language: 'en',
  detectionModelPath: './my-models/custom_detection.onnx',
  recognitionModelPath: './my-models/custom_recognition.onnx',
  dictionaryPath: './my-models/custom_dict.txt'
});

Performance Tuning with ONNX Options

const ocr = await Ocr.create({
  language: 'en',
  
  // Detection model ONNX options
  detectionOnnxOptions: {
    executionProviders: ['cpu'],
    intraOpNumThreads: 4,          // Use 4 CPU threads
    graphOptimizationLevel: 'all',
    enableCpuMemArena: true
  },
  
  // Recognition model ONNX options
  recognitionOnnxOptions: {
    executionProviders: ['cpu'],
    intraOpNumThreads: 2,
    executionMode: 'sequential'
  }
});

Without Text Grouping

const ocr = await Ocr.create({ language: 'en' });

// Get only individual text elements (no paragraph grouping)
const result = await ocr.detect('./image.jpg', { grouped: false });

console.log(result.data); // Array of individual text elements
// result.paragraphs will not be present

Dynamic Grouping Configuration

const ocr = await Ocr.create({ language: 'en' });

// Update grouping configuration at runtime
ocr.setGroupingConfig({
  verticalThresholdRatio: 1.5,
  horizontalThresholdRatio: 3.0
});

// Get current configuration
const config = ocr.getGroupingConfig();
console.log(config);

📊 Output Format

Complete Response Structure

{
  totalElements: 31,           // Total text elements detected
  totalParagraphs: 9,          // Number of grouped paragraphs
  
  // Grouped paragraphs (when grouped: true)
  paragraphs: [
    {
      text: "BECAUSE OF YOU,",
      confidence: 0.923,
      boundingBox: {
        left: 485,
        top: 61,
        width: 84,
        height: 43
      },
      elements: [              // Individual elements in this paragraph
        {
          text: "BECAUSE",
          confidence: 0.96,
          frame: { left: 485, top: 61, width: 84, height: 20 }
        },
        {
          text: "OF YOU,",
          confidence: 0.86,
          frame: { left: 489, top: 81, width: 75, height: 23 }
        }
      ]
    }
  ],
  
  // Individual text elements
  data: [
    {
      text: "BECAUSE",
      confidence: 0.9598,
      frame: {
        left: 485,
        top: 61,
        width: 84,
        height: 20
      },
      box: [[485, 61], [569, 61], [569, 81], [485, 81]]  // 4-point polygon
    }
  ]
}

🎛️ Configuration Options

Detection Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | detectionThreshold | number | 0.1 | Text detection sensitivity (0-1, lower = more sensitive) | | minBoxSize | number | 3 | Minimum text box size in pixels | | maxBoxSize | number | 2000 | Maximum text box size in pixels | | unclipRatio | number | 1.5 | Box expansion ratio for better text capture | | baseSize | number | 32 | Image size base unit (must be multiple of 32) | | maxImageSize | number | 960 | Maximum image dimension |

Recognition Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | language | string | 'en' | Language code: en, ch, ja, ko, latin | | confidenceThreshold | number | 0.5 | Minimum confidence to accept text (0-1) | | imageHeight | number | 48 | Recognition model input height | | removeDuplicateChars | boolean | true | Remove consecutive duplicate characters |

Grouping Options

| Option | Type | Default | Description | |--------|------|---------|-------------| | verticalThresholdRatio | number | 1.2 | Max vertical gap ratio for grouping | | horizontalThresholdRatio | number | 2.5 | Max horizontal gap ratio for same line | | minOverlapRatio | number | 0.3 | Minimum vertical overlap for same line | | maxVerticalOffsetRatio | number | 0.5 | Max vertical offset ratio for same line |

🌍 Supported Languages

// Get list of available languages
const languages = Ocr.getAvailableLanguages();
console.log(languages);

| Code | Language | Model | |------|----------|-------| | en | English | PP-OCRv4 | | ch | Chinese | PP-OCRv4 | | ja | Japanese | PP-OCRv3 | | ko | Korean | PP-OCRv4 (Korean dict) | | latin | Latin (PT, ES, FR, etc.) | PP-OCRv3 |

📁 Included Models

The package ships with all required models and dictionaries for plug-and-play usage:

models/
├── ch_PP-OCRv4_det_infer.onnx         # Detection model (shared)
├── en_PP-OCRv4_rec_infer.onnx         # English recognition
├── en_dict.txt                         # English dictionary
├── ch_PP-OCRv4_rec_infer.onnx         # Chinese recognition
├── ch_dict.txt                         # Chinese dictionary
├── japan_PP-OCRv3_rec_infer.onnx      # Japanese recognition
├── japan_dict.txt                      # Japanese dictionary
├── korean_dict.txt                     # Korean dictionary
├── latin_PP-OCRv3_rec_infer.onnx      # Latin recognition
└── latin_dict.txt                      # Latin dictionary

No additional setup required - everything is ready to use out of the box!

🔧 Custom Models

You can use your own ONNX models:

const ocr = await Ocr.create({
  detectionModelPath: './path/to/detection.onnx',
  recognitionModelPath: './path/to/recognition.onnx',
  dictionaryPath: './path/to/dictionary.txt'
});

Model Requirements

• Detection Model: ONNX format, input shape [1, 3, H, W], output: binary mask
• Recognition Model: ONNX format, input shape [1, 3, 48, W], output: character probabilities
• Dictionary: Text file with one character per line

🎯 Use Cases

• 📸 Document Scanning: Extract text from scanned documents
• 🎫 Receipt Processing: Parse receipts and invoices
• 🚗 License Plate Recognition: Read vehicle plates
• 📝 Form Processing: Extract data from forms
• 🌐 Translation Apps: Detect and translate text in images
• 📱 Screenshot OCR: Extract text from screenshots
• 🏷️ Label Reading: Read product labels and barcodes

⚡ Performance Tips

1. Adjust Detection Threshold: Lower for harder-to-read text, higher for cleaner images
2. Use Appropriate Language Model: Select the correct language for better accuracy
3. Optimize Image Size: Resize very large images before processing
4. Tune ONNX Threads: Adjust intraOpNumThreads based on your CPU cores
5. Disable Grouping: Use grouped: false if you only need individual elements

🐛 Troubleshooting

Low Accuracy

• Adjust detectionThreshold (try 0.05 for harder images)
• Increase unclipRatio (try 1.8 or 2.0)
• Ensure correct language model is selected
• Preprocess image (increase contrast, remove noise)

Missing Text

• Lower detectionThreshold
• Reduce minBoxSize
• Increase unclipRatio

Performance Issues

• Reduce maxImageSize
• Adjust ONNX thread settings
• Process images in batches

Wrong Grouping

• Adjust grouping ratios in configuration
• Use grouped: false and implement custom grouping

📝 API Reference

Ocr.create(options)

Creates a new OCR instance with the specified configuration.

Parameters:

• options (Object): Configuration options

Returns: Promise<Ocr> - OCR instance

ocr.detect(imagePath, options)

Detects and recognizes text in an image.

Parameters:

• imagePath (string): Path to image file
• options (Object): Detection options
  • grouped (boolean): Return grouped paragraphs (default: true)
  • onnxOptions (Object): Runtime ONNX options

Returns: Promise<Object> - Detection results

ocr.setGroupingConfig(config)

Updates the text grouping configuration.

Parameters:

• config (Object): New grouping configuration

ocr.getGroupingConfig()

Returns the current grouping configuration.

Returns: Object - Current grouping configuration

Ocr.getAvailableLanguages()

Static method that returns available languages.

Returns: Object - Language configurations

🤝 Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

📄 License

ISC

🙏 Acknowledgments

• Built on PaddleOCR models
• Uses ONNX Runtime Node for efficient model inference in Node.js
• Powered by Sharp for image processing

📧 Support

For issues and questions, please open an issue on GitHub.

Made with ❤️ for the JavaScript community