🏥 med-ocr-toolkit

OCR document processor for healthcare — extracts patient URNs and clinical metadata from scanned PDFs.

Built to handle real-world messy scans, not just clean test inputs. Outputs structured data to Excel for clinical admin use.

---

The Problem

Clinical teams often receive scanned PDF referrals and discharge summaries that need patient URNs manually keyed into spreadsheets. It's slow, error-prone, and pulls admin staff away from patient-facing work.

This tool automates that extraction — handling the messiness of real scanned documents (skewed pages, low contrast, varied fonts) that simpler approaches can't deal with.

---

Features

• 📄 PDF → structured data — extracts patient URNs, dates, and reference numbers
• 🧹 Adaptive preprocessing — sharpening and contrast enhancement for poor-quality scans
• 📊 Excel output — colour-coded results ready for clinical admin workflows
• 🔁 Batch processing — process an entire folder of PDFs in one command
• 🧪 Well tested — extraction logic covered independently of Tesseract
• 🖥️ CLI + Python API — use from the command line or import into your own pipeline

---

Quick Start

pip install med-ocr-toolkit

System requirement: Tesseract OCR must be installed separately.

• macOS: brew install tesseract
• Ubuntu: sudo apt install tesseract-ocr
• Windows: installer here

Process a single document

med-ocr process patient_referral.pdf

==================================================
  File      : patient_referral.pdf
  Pages     : 3
  Confidence: 87%
  URNs      : URN-2024-001234, URN-2024-001235
  Dates     : 15/03/2024, 22/03/2024
==================================================

Batch process a folder

med-ocr batch ./incoming_referrals/ --output results.xlsx

✓ Processed 47 files — 45 successful
✓ Results saved to: results.xlsx

Use as a Python library

from med_ocr_toolkit import OCRProcessor, export_to_excel

processor = OCRProcessor(dpi=300)

# Single file
result = processor.process("referral.pdf")
print(result.urns)        # ['URN-2024-001234']
print(result.confidence)  # 0.87

# Batch
results = processor.process_batch("./scans/")
export_to_excel(results, "output.xlsx")

---

How It Works

PDF file
   │
   ▼
PDF → Images (pdf2image, 300 DPI)
   │
   ▼
Preprocessing (grayscale → sharpen → contrast boost)
   │
   ▼
Tesseract OCR (OEM 3, PSM 6)
   │
   ▼
Regex extraction (URN patterns, date patterns)
   │
   ▼
ExtractionResult (urns, dates, confidence, errors)
   │
   ▼
Excel output (openpyxl, colour-coded by status)

---

URN Patterns Supported

Format	Example
Standard URN	URN-2024-001234
Short alphanumeric	MR-123456, NHS-12345678
Labelled field	Patient ID: ABC1234567

Need a different format? Open an issue or submit a PR — patterns are easy to add.

---

Configuration

processor = OCRProcessor(
    dpi=400,      # Higher DPI for very poor quality scans (slower)
    lang="eng",   # Tesseract language code
)

---

Running Tests

Tests cover the extraction and export logic without requiring Tesseract:

pip install pytest
pytest tests/ -v

---

Contributing

Contributions welcome — especially:

• Additional URN/reference number patterns from different NHS trusts or private providers
• Support for other output formats (CSV, JSON, HL7)
• Better preprocessing for specific scan types (e.g. fax-quality documents)

Please open an issue before starting work on larger changes.

---

Background

This tool grew out of work automating clinical document processing at a private healthcare provider in Belfast. The main challenge was reliability on real-world scanned inputs — documents that arrived skewed, low-contrast, or with mixed fonts — rather than the clean PDFs most OCR examples use.

---

License

MIT — free to use, modify, and distribute.

---

Author

Monika Sonnad Math — Senior Software Developer
LinkedIn · GitHub