npm package: @porosh80/react-native-bangla-ocr
Description: React Native Bangla OCR library with native preprocessing, OCR orchestration, normalization, and correction.
Latest version: 1.0.5

# @porosh80/react-native-bangla-ocr

React Native Bangla OCR library built from the existing mobile OCR pipeline in this repository.

License: MIT

## Public API

```ts
import {
  initialize,
  preloadAssets,
  recognizeFromImage,
  normalizeText,
  correctText,
  getAssetStatus,
  cancelJob,
} from '@porosh80/react-native-bangla-ocr';
```

## Install In Another App

Install the library in your React Native app:

```bash
npm install @porosh80/react-native-bangla-ocr
```

Install the required peer dependencies in the host app:

```bash
npm install react react-native react-native-fs react-native-mmkv onnxruntime-react-native base64-js fast-png jpeg-js
```

Optional peers for local Bangla AI correction:

```bash
npm install @react-native-ai/mlc
npm install llama.rn
```

iOS:

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

Notes:
- React Native autolinking should pick up this package automatically on Android and iOS.
- the OCR engine is now internal to this package; you do not need to install any separate engine package
- `onnxruntime-react-native`, `base64-js`, `fast-png`, and `jpeg-js` are still required peer dependencies for OCR runtime support
- `@react-native-ai/mlc` is only needed for the `basic` on-device AI correction path.
- `llama.rn` is only needed for the `pro` on-device AI correction path.

## Quick Start

Import the package in your app:

```ts
import {
  initialize,
  preloadAssets,
  recognizeFromImage,
  normalizeText,
  correctText,
  getAssetStatus,
  cancelJob,
} from '@porosh80/react-native-bangla-ocr';
```

Initialize and check native availability:

```ts
const info = await initialize();

console.log(info.nativeModuleAvailable);
console.log(info.assetStatus);
```

Preload OCR assets before first OCR run:

```ts
await preloadAssets({
  onProgress: (progress, stage) => {
    console.log(stage, progress);
  },
});
```

Run OCR from an image:

```ts
const result = await recognizeFromImage({
  imageUri: 'file:///path/to/image.jpg',
  sourceType: 'gallery',
  expectedLanguage: 'bn+en',
  mode: 'document',
  debug: true,
  onProgress: (progress, stage) => {
    console.log(stage, progress);
  },
});

console.log(result.rawText);
console.log(result.normalizedText);
console.log(result.correctedText);
console.log(result.fullText);
console.log(result.confidence);
console.log(result.blocks);
```

The OCR result keeps the stages separate:
- `rawText`
- `normalizedText`
- `correctedText`
- `fullText`

This library does not collapse those stages into one field.

Normalize text only:

```ts
const normalized = normalizeText('বাংলা OCR টেক্সট', {
  normalizationMode: 'standard',
});

console.log(normalized.output);
```

Correct text only:

```ts
const corrected = correctText('বাংলা OCR টেক্সট', {
  confidence: 0.72,
  correctionMode: 'safe-correction',
});

console.log(corrected.output);
```

Read asset status:

```ts
const assetStatus = await getAssetStatus();
console.log(assetStatus);
```

Cancel an active OCR job:

```ts
await cancelJob('your-job-id');
```

## API Overview

`initialize()`
- Returns whether the native module is available and the current asset status.

`preloadAssets(options?)`
- Downloads or prepares Bangla OCR assets before OCR.
- Use this before first OCR or during app startup.

`recognizeFromImage(request)`
- Runs Bangla OCR on an image URI.
- Returns structured OCR output including blocks, lines, words, confidence, warnings, Unicode diagnostics, and separate raw/normalized/corrected/final text stages.

`normalizeText(text, options?)`
- Applies Bangla Unicode normalization without running OCR.

`correctText(text, options?)`
- Applies Bangla correction logic without running OCR.

`getAssetStatus()`
- Returns current OCR asset/model availability status.

`cancelJob(jobId)`
- Cancels a running OCR job by id.

## Request Shape

Main `recognizeFromImage()` request fields:

```ts
type OcrRequest = {
  jobId?: string;
  imageUri: string;
  sourceType?: 'camera' | 'gallery' | 'filesystem' | 'batch';
  expectedLanguage?: 'bn' | 'bn+en';
  mode?: 'document' | 'region';
  debug?: boolean;
  approach?: 'basic' | 'pro' | 'api';
  advancedModel?: string;
  advancedModelPath?: string;
  normalizationMode?: 'conservative' | 'standard' | 'aggressive';
  correctionMode?: 'exact-transcription' | 'safe-correction' | 'assisted-correction';
  exactTranscription?: boolean;
  width?: number;
  height?: number;
  fileName?: string;
  mimeType?: string;
  fileSize?: number;
  timeoutMs?: number;
  targetRegion?: unknown;
  onProgress?: (progress: number, stage: string) => void;
};
```

## Result Shape

Main `recognizeFromImage()` result fields:

```ts
type OcrResult = {
  jobId: string;
  rawText: string;
  normalizedText: string;
  correctedText: string;
  fullText: string;
  confidence: number;
  languageDetected: string[];
  boundingBoxes: BoundingBox[];
  blocks: OcrBlock[];
  warnings: string[];
  correctionSuggestions: string[];
  unicode: UnicodeStageResult;
  debugArtifacts?: Record<string, unknown>;
};
```

Structured output is preserved:
- page-level text
- blocks
- lines
- words
- confidence
- bounding boxes
- warnings
- debug artifacts when enabled

## Notes

- Raw, normalized, and corrected Bangla text stages remain separate.
- Bangla-specific normalization and correction are handled by the library.
- The package is intended for offline-first mobile OCR after required assets are prepared.
- Optional local AI correction requires the matching peer dependency for the selected runtime.

## License

MIT. See [LICENSE](./LICENSE).