local-ocr

light-ocr is a local OCR engine. It runs offline, returns text with coordinates and confidence, and follows a strict stdout/stderr contract for scripting.

Scenarios

Screenshot with small text

A user shares a screenshot and asks about specific text that is too small or dense to read visually.

# Step 1: recognize the full image
light-ocr screenshot.png --format json

If the result has low confidence or missing text in a region:

# Step 2: re-run on the specific region (coordinates from step 1 boxes)
light-ocr recognize screenshot.png --region 100,80,640,320 --format json

Form or receipt field extraction

Need to extract specific fields (names, amounts, dates) from a form or receipt image.

# Step 1: detect where text regions are (fast, no recognition)
light-ocr detect receipt.png

# Step 2: recognize only the region containing the target field
light-ocr recognize receipt.png --region 50,200,300,80 --format json

This two-step pattern saves time on large images: detect first, then recognize only the regions of interest.

Counting text regions

Need to count how many text lines or regions exist in an image.

light-ocr detect image.png | python -c "import json,sys; print(len(json.load(sys.stdin)['pages'][0]['detections']))"

Verifying multimodal model output

A multimodal model claims to read text from an image. Verify the claim against deterministic OCR.

light-ocr image.png --format text

Compare the text output with the model's claim. If they differ, trust the OCR text field — do not fabricate.

Batch processing via shell

Process multiple images sequentially with JSONL output.

for f in *.png; do
  light-ocr recognize "$f" --format jsonl
done

Each line is one page record. Check exit codes: a non-zero exit for one image does not stop the loop, but stdout for that image may be empty.

PDF and multi-page documents

Need to extract text from a PDF file or process multiple images as one document.

# Full PDF with JSON output
light-ocr report.pdf --format json

# Page range with streaming JSONL
light-ocr report.pdf --pages 1-10 --format jsonl

# Multiple images as one document
light-ocr document scan1.png scan2.png --format text

# Check if PDF support is available
light-ocr document info

PDF support is part of @arcships/light-ocr. The matching PDFium binary is inside the npm platform package; do not install another package and do not download a renderer at runtime.

System diagnostics

Need to check hardware or execution provider status.

light-ocr doctor --json

Returns system info (Node.js version, OS, CPU, memory), native runtime status, and available providers. No user content, hostname, username, path, or stable device identifier is collected.

Decision flow

Need text from an image or document?
├── Know which region? → recognize --region x,y,w,h --format json
├── Need full text only? → recognize --format text
├── Need text + coordinates? → recognize --format json
├── Only need where text is? → detect
├── Large image, unsure where text is? → detect first, then recognize --region
├── PDF? → light-ocr <file.pdf> --format json
├── Multiple images? → light-ocr document <files> --format json
├── Need system/hardware info? → doctor --json
└── Need engine info or version? → info --model-info / info --version

Output schema

{
  "schemaVersion": 1,
  "source": { "kind": "image", "mediaType": "...", "identity": {}, "appliedTransforms": {} },
  "pages": [{
    "index": 0,
    "width": 640, "height": 480,
    "coordinateSpace": "pageSpace",
    "structure": "ocr-order",
    "lines": [{ "id": "L0", "text": "HELLO", "confidence": 0.99, "box": [4 points] }]
  }]
}

• box is 4 points in pageSpace (top-left origin, x right, y down, post-EXIF pixels)
• detect replaces lines with detections[] ({ id, score, box }) and sets structure: "detect"
• --format text: recognized text only, one line per line, no coordinates
• --format jsonl: one page record per line (for streaming/batch)

Exit codes

Rules

1. Never fabricate OCR text. Only use the text field from results. If confidence < 0.5, state it.
2. Cite coordinates when relevant. Box coordinates are in pageSpace.
3. Use --schema-version 1 for reproducible output. Do not parse help text.
4. Prefer detect first on large images, then recognize --region on areas of interest.
5. Check exit codes before parsing stdout. Non-zero exit means stdout may be empty; read stderr.