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

``bash
npm install natscan
`

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

$3

`bash
cd ios && pod install && cd ..
`

Quick Start

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

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

$3

`typescript
import { processReceipt } from "natscan";

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

$3

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

$3

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

$3

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

$3

`bash
npm run build
`

$3

`bash


Interactive test script

npm run test:local

Unit tests

npm test
`

$3

`bash
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.