npm package: @osca16/slnic
Description: Sri Lankan NIC parser + optional OCR & PDF417 barcode verification (Sinhala/Tamil/English) – pure JavaScript
Latest version: 0.1.7

# Sri Lankan NIC toolkit

JavaScript helpers for working with Sri Lankan National Identity Cards (NIC). The package provides:

- NIC parser with gender, DOB, sequence and age extraction for both legacy and 2016+ formats.
- OCR-driven extraction helpers backed by Tesseract.js with Sinhala/Tamil/English language packs.
- PDF417 barcode decoding with rotation fallbacks and metadata comparison utilities.
- A high-level `verifyNicFromImages` orchestrator for combining front/back/selfie checks.

## Installation

```bash
npm install @osca16/slnic
```

## Usage

```js
import { parseSriLankaNIC, ocrNicFromImage, decodeBackBarcode, verifyNicFromImages } from "@osca16/slnic";

const parsed = parseSriLankaNIC("####");

const ocr = await ocrNicFromImage(frontCanvas);
const barcode = await decodeBackBarcode(backCanvas);

const verification = await verifyNicFromImages({
	frontImage: frontCanvas,
	backImage: backCanvas,
	selfieImage: selfieCanvas,
	languages: ["en-LK", "si-LK"]
});
```

## React + Vite quick start

1. Install the dependencies:

	 ```bash
	 npm install @osca16/slnic tesseract.js @techstark/opencv-js
	 ```

2. Teach Vite to keep the OpenCV WebAssembly asset and avoid pre-bundling the large module (optional but reduces build warnings):

	 ```js
	 // vite.config.js
	 import { defineConfig } from "vite";
	 import react from "@vitejs/plugin-react";

	 export default defineConfig({
		 plugins: [react()],
		 assetsInclude: ["**/*.wasm"],
		 optimizeDeps: {
			 exclude: ["@osca16/slnic", "@techstark/opencv-js"]
		 }
	 });
	 ```

3. Use the helpers from a React component. The `verifyNicFromImages` helper takes care of OCR, barcode scan, and OpenCV-based selfie comparison:

	 ```jsx
	 import { useState } from "react";
	 import { verifyNicFromImages } from "@osca16/slnic";

	 export function NicVerifier() {
		 const [result, setResult] = useState();

		 async function handleSubmit(event) {
			 event.preventDefault();
			 const form = event.currentTarget;
			 const front = form.front.files[0];
			 const back = form.back.files[0];
			 const selfie = form.selfie.files[0];

			 if (!front) return;

			 const verification = await verifyNicFromImages({
				 frontImage: front,
				 backImage: back,
				 selfieImage: selfie,
				 ocrOptions: {
					 workerPath: new URL("tesseract.worker.min.js", import.meta.url).href,
					 langPath: "/tesseract-langs/"
				 },
				 faceOptions: {
					 targetSize: 192,
					 blurThreshold: 14
				 }
			 });

			 setResult(verification);
		 }

		 return (
			 <form onSubmit={handleSubmit}>
				 <input name="front" type="file" accept="image/*" required />
				 <input name="back" type="file" accept="image/*" />
				 <input name="selfie" type="file" accept="image/*" />
				 <button type="submit">Verify</button>
				 <pre>{result ? JSON.stringify(result, null, 2) : ""}</pre>
			 </form>
		 );
	 }
	 ```

	 Place `tesseract` language data (e.g. `eng.traineddata`, `sin.traineddata`, `tam.traineddata`) under `public/tesseract-langs/` so the worker can load them when offline.

## Environment notes

- The library targets modern browsers. For Node.js usage, provide `HTMLCanvasElement`, `ImageData`, or run under a DOM-enabled environment (e.g. `canvas` + `jsdom`).
- Ensure the Tesseract language data for `eng`, `sin`, and `tam` is available; `tesseract.js` downloads files on first use.
- When working with large images, pre-scale to improve recognition speed.
- You can control OCR worker/core/lang paths by passing an options object as the second argument to `ocrNicFromImage` or via `verifyNicFromImages({ ocrOptions: {...} })`.
- `compareFaces` now uses a lightweight OpenCV-based blur + similarity heuristic. Pass `{ faceOptions: { blurThreshold, targetSize } }` to tune thresholds for your camera setup.
- When bundling, make sure `opencv_js.wasm` from `@techstark/opencv-js` is served (copy it to `public/` or expose via `Module.locateFile`) so that face comparison can initialise correctly.

## Feedback

If you encounter issues or have feature requests, please open an issue or share improvements.