natscan

Offline OCR pipeline for React Native/Expo receipt scanning with multilingual support (Simplified Chinese, Traditional Chinese, and English) using Google ML Kit.

Features

• ✅ Offline Processing - No internet connection required
• ✅ React Native 0.81 & Expo SDK 54+ Compatible - Works seamlessly with latest versions
• ✅ Multilingual Support - English, Simplified Chinese, Traditional Chinese
• ✅ Automatic Language Detection - Detects receipt language automatically
• ✅ Native Performance - Uses Google ML Kit for fast, on-device OCR
• ✅ Structured Data Extraction - Extracts 7 key fields from receipts plus raw OCR text
• ✅ TypeScript Support - Full type definitions included
• ✅ Cross-Platform - Works on both iOS and Android

Installation

npm install natscan

That's it! ML Kit will be installed automatically as a dependency.

iOS Setup

cd ios && pod install && cd ..

Quick Start

import { processReceipt } from "natscan";

// Process a receipt image
const result = await processReceipt("path/to/receipt.jpg");

console.log(result);
// {
//   receiptno: "INV-123456",
//   shopname: "ABC Supermarket",
//   date: "2025-12-19",
//   time: "14:30",
//   netAmount: 45.5,
//   grossAmount: 50.0,
//   totalItems: 5,
//   rawInput: "Full OCR text..."
// }

Response Format

The pipeline returns a ReceiptScanResponse object with the following structure:

{
  receiptno: string; // Receipt/invoice number
  shopname: string; // Store/shop name
  date: string; // Date in ISO format (YYYY-MM-DD)
  time: string; // Time in 24-hour format (HH:MM)
  netAmount: number; // Net amount (before tax)
  grossAmount: number; // Gross amount (total including tax)
  totalItems: number; // Total number of items purchased
  rawInput: string; // Raw OCR text extracted from the image
}

Usage Examples

Basic Usage

import { processReceipt } from "natscan";

const result = await processReceipt("./receipt.jpg");
console.log("Shop:", result.shopname);
console.log("Total:", result.grossAmount);

Advanced Usage

import { OCRPipeline } from "natscan";

const pipeline = new OCRPipeline({
  languages: ["eng", "chi_sim", "chi_tra"],
  preprocessingLevel: "high",
  confidenceThreshold: 0.7,
  debug: true,
});

// Process single receipt
const result = await pipeline.processReceipt("receipt.jpg");

// Process multiple receipts
const results = await pipeline.processBatch([
  "receipt1.jpg",
  "receipt2.jpg",
  "receipt3.jpg",
]);

// Clean up resources
await pipeline.cleanup();

Configuration

Default Configuration

{
  languages: ['eng', 'chi_sim', 'chi_tra'],
  preprocessingLevel: 'medium',
  confidenceThreshold: 0.6,
  debug: false,
}

Configuration Options

interface OCRConfig {
  languages: ("chi_sim" | "chi_tra" | "eng")[];
  preprocessingLevel: "low" | "medium" | "high";
  confidenceThreshold: number; // 0-1
  debug?: boolean;
}

Supported Languages

• English (eng) - US, UK, international formats
• Simplified Chinese (chi_sim) - Mainland China formats
• Traditional Chinese (chi_tra) - Taiwan, Hong Kong formats

Supported Image Formats

• JPEG (.jpg, .jpeg)
• PNG (.png)
• WebP (.webp)
• TIFF (.tiff, .tif)

Requirements

• React Native >= 0.81.0 (tested with 0.81)
• Expo SDK >= 50.0.0 (tested with SDK 54)
• Node.js >= 18.0.0
• iOS >= 15.5 (required by ML Kit)
• Android >= API 21 (Android 5.0)

Documentation

For detailed documentation, please refer to the docs folder:

• Getting Started - Quick start guide and basic usage
• API Reference - Complete API documentation
• Response Format - Detailed response structure and examples
• React Native & Expo - React Native/Expo specific guide
• Best Practices - Tips for optimal results
• Troubleshooting - Common issues and solutions

Development

Build

npm run build

Test

# Interactive test script
npm run test:local

# Unit tests
npm test

Development Mode

npm run dev

Performance

• Average processing time: 2-5 seconds per receipt
• Accuracy: 85-95% on clear, well-lit receipts
• Image requirements:
  • Minimum width: 800px
  • Supported formats: JPG, PNG, WEBP, TIFF
  • Recommended: Good lighting, minimal blur

License

MIT

Support

For issues and questions, please refer to the Troubleshooting guide or open an issue on the repository.