🔍 sv-ocr

Perform text recognition (OCR) from images using Node.js — either as a function or a REST API server.

Ideal for document processing, attendance systems, kiosks, or AI pre-processing pipelines.

✨ Features

• 🚀 Use as a Node.js function or launch as a web server
• 📤 Supports local file paths and image uploads
• 🖼️ Works with most standard image formats (JPG, PNG, etc.)
• 📦 Lightweight and fast

📦 Installation

npm install sv-ocr

Note: This package is ESM-only. Make sure to include "type": "module" in your package.json.

{
  "type": "module"
}

🚀 Quick Start

1️⃣ Use as a Function

import { recognizeText } from 'sv-ocr';

const results = await recognizeText('/absolute/path/to/image.png');
console.log(results);

2️⃣ Use as an API Server

import { startOcrServer } from 'sv-ocr';

startOcrServer(3600); // Starts Express server on port 3600

🌐 API Endpoints

| Method | Route | Description | | ------ | ------------- | ---------------------------- | | GET | /ocrByPath | OCR from local image path | | POST | /ocr-upload | OCR from uploaded image file |

🔗 Example: GET /ocrByPath

curl "http://localhost:3600/ocrByPath?imagePath=/full/path/image.jpg"

🔗 Example: POST /ocr-upload

curl -X POST http://localhost:3600/ocr-upload \
  -F "image=@./image.png"

📚 API Methods

startOcrServer(port: number): void

Launches an Express server with two OCR routes.

recognizeText(imagePath: string): Promise<OCRResult[]>

Performs OCR on a local image path.

🧾 Output Schema

Each OCR result is an object with the following structure:

type OCRResult = {
  text: string;         // Detected text string
  mean: number;         // Confidence score (0 to 1)
  box: [                // Bounding box (4-point polygon)
    [number, number],   // Top-left
    [number, number],   // Top-right
    [number, number],   // Bottom-right
    [number, number]    // Bottom-left
  ];
};

🖥 CLI Mode

npm install -g sv-ocr

Extract text directly from an image:

sv-ocr ./path/to/image.jpg

🌐 API Server Mode

Start a REST API server:

sv-ocr-server

Two endpoints will be available:

GET /ocrByPath

curl "http://localhost:3600/ocrByPath?imagePath=/absolute/path/to/image.jpg"

POST /ocr-upload

curl -F "image=@/path/to/image.jpg" http://localhost:3600/ocr-upload

📁 Notes

• The imagePath for /ocrByPath must be absolute.
• Uploaded files are stored temporarily in the uploads/ folder.
• For best results, use high-contrast images with minimal noise.

🛡 License

MIT

👨‍💼 Author

Made with ❤️ by Vaibhav Panday

Found this useful? Star the repo or buy me a coffee ☕ PRs and feedback welcome!