imporvemnt paths

README.md

@@ -1,112 +1,117 @@
-# Text Extracted - OCR Web Application
+# 🧠 DocIQ — Advanced Intelligent Document Processing (IDP) Platform
+
+[![Python](https://img.shields.io/badge/Python-3.10%2B-blue.svg)](https://www.python.org/)
+[![Streamlit](https://img.shields.io/badge/Streamlit-1.40%2B-FF4B4B.svg)](https://streamlit.io/)
+[![EasyOCR](https://img.shields.io/badge/EasyOCR-PyTorch%20GPU-green.svg)](https://github.com/JaidedAI/EasyOCR)
+[![License](https://img.shields.io/badge/License-MIT-purple.svg)](LICENSE)
+
+**DocIQ** is an Intelligent Document Processing (IDP) platform built with Streamlit, EasyOCR, OpenCV, Sentence-Transformers, and PyMuPDF. It transforms raw document images, receipts, invoices, and scans into clean, structured, searchable, and semantically indexed data.
+
+---
+
+## 🚀 Key Features
+
+### 1. 🖼️ Computer Vision Preprocessing Pipeline (`src/preprocessor.py`)
+- **Auto-Deskew**: Automatically detects document tilt using Hough line transform and corrects orientation.
+- **Adaptive Contrast (CLAHE)**: Enhances faded or low-contrast document scans.
+- **Bilateral Denoising**: Smooths scanner grain while preserving crisp character edges.
+- **Multiple Modes**:
+  - `auto`: Deskew + CLAHE + Denoise
+  - `binarize`: High-contrast black & white document thresholding (Otsu adaptive)
+  - `warp`: Perspective transformation for flattened documents
+  - `raw`: Process image as uploaded
+
+### 2. ⚡ Accelerated OCR Inference (`src/ocr_engine.py`)
+- Powered by **EasyOCR** with PyTorch CUDA GPU acceleration.
+- Built-in multi-lingual support: **English (`en`)**, **Hindi (`hi`)**, French, German, Spanish, Chinese, and Arabic.
+- Caching with `@st.cache_resource` for zero-redundancy model loading across sessions.
+- Detailed bounding box coordinates `[x_min, y_min, x_max, y_max]`, confidence scores, and reading order.
+
+### 3. 🎨 Visual Canvas & Spatial Inspection (`src/visualizer.py`)
+- **Confidence Bounding Boxes**: Visual color cues (Green ≥80%, Yellow 50–80%, Red <50%).
+- **Confidence Heatmap**: Continuous thermal density overlay showing spatial OCR certainty.
+- **Reading Order Vector Flow**: Numbered direction arrows indicating extracted line-by-line reading flow.
+- **Interactive Visual Keyword Search**: Search any keyword to immediately highlight its spatial bounding box in gold.
+
+### 4. 🗂️ Structured Entity & Invoice Extraction (`src/extractor.py`)
+- **Automated Document Classification**: Categorizes document as *Invoice / Receipt*, *Identity Document*, *Medical / Prescription*, *Legal / Contract*, or *Academic*.
+- **Regex & Context Parsing**:
+  - Dates (multiple international formats)
+  - Monetary amounts & currencies (`$`, `₹`, `€`, `£`)
+  - Contact information (emails, phones, URLs)
+  - Invoice & purchase order numbers, subtotals, tax, discounts, and due dates
+- **PII Detection & Redaction**: Detects sensitive credentials (Aadhaar, PAN, Credit Cards, SSN) with optional 1-click `████` redaction.
+
+### 5. 🧬 Semantic Embedding Vector Space (`src/embedder.py`)
+- Embeds extracted words or sentences using `sentence-transformers/all-MiniLM-L6-v2`.
+- Projects 384-dimensional dense vectors down to 2D via **PCA**, **t-SNE**, or **UMAP**.
+- Clusters related concepts using **K-Means** with interactive Plotly scatter plots.
+- Computes pairwise **Cosine Similarity Heatmaps** to discover semantic connections in document content.
+
+### 6. 📤 Multi-Format Export Engine (`src/exporter.py`)
+- **Searchable PDF**: Embedded invisible text layer enabling native `Ctrl+F` search across standard PDF viewers.
+- **Annotated Audit PDF**: Complete executive report with bounding box visual overview, confidence metrics, and entity tables.
+- **Structured JSON**: Full word coordinates, confidence scores, and detected metadata for downstream NLP pipelines.
+- **CSV / Excel**: Tabular word list with positions and confidence.
+- **Plain Text**: Formatted clean text with optional PII redaction.
+- **All-In-One ZIP Archive**: 1-click download of all formats bundled together.
+
+### 7. ✨ Preset Samples & Camera Scanner
+- **Preset Test Documents**: Built-in Commercial Invoice and Retail Receipt generators (`src/sample_docs.py`) for instant testing without needing local image files.
+- **Live Camera Scanner**: Snap physical documents in real-time via camera/webcam.
+
+---
+
+## 📁 Project Architecture
 
-## Overview
-
-Text Extracted is a web-based application designed to extract text from images using Optical Character Recognition (OCR). The application utilizes `pytesseract` for OCR processing and provides an intuitive interface using `Streamlit`. Additionally, the app features keyword extraction from the OCR-processed text, making it useful for data extraction, analysis, or research purposes.
-
-## Features
-
-- **Image Upload**: Users can upload images containing text.
-- **Text Extraction**: The app extracts text from uploaded images using `pytesseract`.
-- **Keyword Extraction**: Allows users to extract important keywords from the extracted text.
-- **User-Friendly Interface**: Simple web interface for easy interaction.
-
-## Tech Stack
-
-- **Frontend**: Streamlit
-- **Backend**: Python
-- **OCR Engine**: pytesseract (Tesseract-OCR)
-- **Libraries**:
-  - `streamlit`: For creating the web interface.
-  - `pytesseract`: For performing OCR on images.
-  - `Pillow`: For handling image files.
-  - `regex`: For text manipulation and keyword extraction.
-
-## Prerequisites
-
-Before running the application, ensure that you have the following installed:
-
-1. **Python 3.7 or higher**: You can download Python [here](https://www.python.org/downloads/).
-2. **Tesseract-OCR**: The OCR engine required by `pytesseract`. You can install it as follows:
-   - **macOS**: 
-     ```bash
-     brew install tesseract
-     ```
-   - **Ubuntu**: 
-     ```bash
-     sudo apt-get install tesseract-ocr
-     ```
-   - **Windows**: Download the installer from [here](https://github.com/tesseract-ocr/tesseract/wiki) and follow the instructions.
-
-## Installation
+```
+Text_Extracted/
+├── app.py                 # Streamlit UI, visual canvas, search, embeddings, and tabs
+├── requirements.txt       # Project dependencies
+├── README.md              # Project documentation
+└── src/
+    ├── __init__.py        # Package initialization
+    ├── preprocessor.py    # OpenCV deskew, contrast CLAHE, binarization, perspective warp
+    ├── ocr_engine.py      # EasyOCR GPU inference engine and result normalizer
+    ├── visualizer.py      # Bounding box overlays, heatmaps, search highlighter
+    ├── extractor.py       # Entity extraction (dates, amounts, contacts, invoice fields, PII)
+    ├── embedder.py        # Sentence-transformers embedding & 2D dimensionality reduction
+    ├── exporter.py        # Searchable PDF, Annotated PDF, JSON, CSV, TXT, and ZIP bundle
+    └── sample_docs.py     # Synthetic document generator for 1-click demo testing
+```
 
-### Follow the steps below to set up the project locally:
+---
 
-1. **Clone the Repository**:
-   Open your terminal or command prompt and run:
+## ⚙️ Installation & Setup
 
-```bash
-   git clone https://github.com/Goutam16-Withcode/Text_Extracted.git
-   cd Text_Extracted-main
-```
+### Prerequisites
+- Python 3.10+
+- (Optional) NVIDIA GPU with CUDA for accelerated neural OCR inference
 
-2. **Set Up a Virtual Environment (Optional but recommended)**: Create and activate a virtual environment to manage project dependencies.
-  
+### 1. Clone the Repository
 ```bash
-python -m venv venv
-# Activate the virtual environment
-source venv/bin/activate  # On Windows: venv\\Scripts\\activate
+git clone https://github.com/Goutam16-Withcode/Text_Extracted.git
+cd Text_Extracted
 ```
 
-3. **Install Dependencies:** Use the `requirements.txt` file to install the necessary Python packages:
-
+### 2. Install Dependencies
 ```bash
-   pip install -r requirements.txt
+pip install -r requirements.txt
 ```
 
-4. **Run the Application:** Start the Streamlit application by running the command below:
-   
+### 3. Launch the Application
 ```bash
 streamlit run app.py
 ```
+Open **http://localhost:8501** in your browser to begin.
 
-5. **Open the Application:** Once the application starts, Streamlit will automatically open your default web browser. If not, you can manually visit http://localhost:8501.
-   
-## File Structure
-
-`**app.py:**`  The main application file that handles the Streamlit interface and coordinates image uploads, OCR processing, and keyword extraction.
-
-`**ocr.py:**`  Contains the logic for processing images using `pytesseract` and extracting keywords from the extracted text.
-**requirements.txt:** Lists all the Python dependencies needed to run the application.
-
-## Upload an Image: On the application page, you will see an option to upload an image file. Click the "Browse" button and select an image that contains text.
-**Extract Text:** Once the image is uploaded, the application will process the image and display the extracted text.
-Extract Keywords (Optional): If required, you can click the button to extract keywords from the extracted text.
-
-## Example
-**Input**
-An image containing text such as a scanned document, a screenshot, or any image with visible words.
-
-**Output**
-The raw text extracted from the image.
-A list of keywords derived from the extracted text.
-**Dependencies**
-The project uses the following Python libraries:
-
-1. `streamlit`
-2. `pytesseract`
-3. `Pillow`
-4. `regex`
-These dependencies are listed in the `requirements.txt` file and can be installed using `pip install -r requirements.txt`.
-
-
-## Screen Shots:
-![1](https://github.com/user-attachments/assets/9c3a5779-769f-4367-9ea9-e501a25b89b8)![2](https://github.com/user-attachments/assets/e83695e4-1ba8-48e9-b820-add607abdbf3)
-
-![3](https://github.com/user-attachments/assets/b0116d65-6193-44dd-a3ba-c639638d80d2)![4](https://github.com/user-attachments/assets/12b6a0bd-8f8b-435a-9e79-c2f7272eb0ef)
-
-## Image Uploaded: 
-![6](https://github.com/user-attachments/assets/91204189-0396-4bb5-a05c-2876b4c0425f)
+---
 
+## 🛡️ Privacy & Compliance
+- **Local Execution**: All OCR inference, image preprocessing, and embedding calculations happen locally on your machine.
+- **PII Redaction**: Sensitive IDs and financial numbers can be stripped or masked before exporting.
 
+---
 
+## 📄 License
+This project is open-source and available under the [MIT License](LICENSE).

app.py

@@ -552,16 +552,45 @@ with tab_entities:
     with col_b:
         # Invoice fields
         inv = entities.get("invoice_fields", {})
+        FIELD_ICONS = {
+            "invoice_number": "🧾",
+            "po_number": "📋",
+            "total": "💰",
+            "subtotal": "💵",
+            "tax": "🏛️",
+            "discount": "🏷️",
+            "gstin": "🏢",
+            "due_date": "⏳",
+            "vendor": "🏬",
+        }
         if inv:
-            inv_html = "".join(f"""
-            <div style="display:flex;justify-content:space-between;padding:6px 0;border-bottom:1px solid rgba(99,102,241,0.1);">
-                <span style="color:#64748b;font-size:0.82rem;">{k.replace('_',' ').title()}</span>
-                <span style="color:#e2e8f0;font-size:0.82rem;font-weight:500;">{v}</span>
-            </div>""" for k, v in inv.items())
+            inv_rows = []
+            for k, v in inv.items():
+                icon = FIELD_ICONS.get(k, "📌")
+                title = k.replace('_', ' ').title()
+                inv_rows.append(f"""
+                <div style="display:flex; justify-content:space-between; align-items:center; padding:9px 12px; margin-bottom:6px; background:rgba(15,23,42,0.6); border:1px solid rgba(99,102,241,0.18); border-radius:10px;">
+                    <span style="color:#94a3b8; font-size:0.84rem; display:flex; align-items:center; gap:6px;">
+                        <span>{icon}</span>
+                        <strong style="color:#cbd5e1; font-weight:500;">{title}</strong>
+                    </span>
+                    <span style="color:#38bdf8; font-size:0.86rem; font-weight:600; font-family:monospace; background:rgba(56,189,248,0.1); padding:2px 8px; border-radius:6px; border:1px solid rgba(56,189,248,0.25);">
+                        {v}
+                    </span>
+                </div>""")
+            inv_html = "".join(inv_rows)
             st.markdown(f"""<div class="doc-card">
-                <div style="font-weight:600;color:#e2e8f0;margin-bottom:8px;">🧾 Invoice / Receipt Fields</div>
+                <div style="font-weight:600; color:#e2e8f0; margin-bottom:12px; display:flex; align-items:center; justify-content:space-between;">
+                    <span>🧾 Key Document Fields</span>
+                    <span class="badge badge-cyan">{len(inv)} detected</span>
+                </div>
                 {inv_html}
             </div>""", unsafe_allow_html=True)
+        else:
+            st.markdown("""<div class="doc-card">
+                <div style="font-weight:600; color:#e2e8f0; margin-bottom:6px;">🧾 Key Document Fields</div>
+                <div style="color:#64748b; font-size:0.82rem;">No structured invoice or PO fields detected in this document.</div>
+            </div>""", unsafe_allow_html=True)
 
         # PII
         pii = entities.get("pii", {})

src/extractor.py

@@ -42,15 +42,14 @@ PASSPORT_PATTERN = r"\b[A-Z][1-9][0-9]{7}\b"
 
 # Invoice / Receipt fields
 INVOICE_FIELDS = {
-    "invoice_number": r"(?i)(?:invoice|inv|bill|order)[\s#:\.]*([A-Z0-9\-/]+)",
-    "po_number": r"(?i)(?:p\.?o\.?|purchase order)[\s#:\.]*([A-Z0-9\-/]+)",
-    "gstin": r"(?i)(?:GSTIN|GST No\.?)[\s:\.]*([0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z])",
-    "due_date": r"(?i)(?:due|payment due|pay by)[\s:]*(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})",
-    "total": r"(?i)(?:total|grand total|amount due|net payable)[\s:₹$]*([0-9,]+(?:\.[0-9]{2})?)",
-    "subtotal": r"(?i)(?:subtotal|sub-total|taxable amount)[\s:₹$]*([0-9,]+(?:\.[0-9]{2})?)",
-    "tax": r"(?i)(?:tax|gst|vat|igst|cgst|sgst)[\s:₹$%]*([0-9,]+(?:\.[0-9]{2})?)",
-    "discount": r"(?i)(?:discount|offer)[\s:₹$%-]*([0-9,]+(?:\.[0-9]{2})?)",
-    "vendor": r"(?i)(?:from|vendor|billed by|company)[\s:]*([A-Za-z][A-Za-z\s&.,]{2,40})",
+    "invoice_number": r"(?i)\b(?:invoice|inv|bill|order)[\s#:\.-]*([A-Z0-9\-_/]{3,30})",
+    "po_number": r"(?i)\b(?:p\.?o\.?\s*(?:#|num(?:ber)?)?|purchase\s+order(?:\s*#)?)[\s#:\.-]*([A-Z0-9\-_/]{3,30})",
+    "gstin": r"(?i)\b(?:GSTIN|GST\s*No\.?)[\s:\.]*([0-9]{2}[A-Z]{5}[0-9]{4}[A-Z][0-9A-Z]Z[0-9A-Z])",
+    "due_date": r"(?i)\b(?:due\s+date|payment\s+due|pay\s+by)[\s:]*(\d{1,2}[/-]\d{1,2}[/-]\d{2,4})",
+    "total": r"(?i)\b(?:grand\s+total|total\s+due|total\s+amount|amount\s+due|net\s+payable|total)[\s:₹$]*([0-9,]+(?:\.[0-9]{2})?)",
+    "subtotal": r"(?i)\b(?:subtotal|sub-total|taxable\s+amount)[\s:₹$]*([0-9,]+(?:\.[0-9]{2})?)",
+    "tax": r"(?i)\b(?:tax(?:\s*\(\d+%\))?|gst|vat|igst|cgst|sgst)[\s:₹$%]*([0-9,]+(?:\.[0-9]{2})?)",
+    "discount": r"(?i)\b(?:discount|special\s+offer)[\s:₹$%-]*([0-9,]+(?:\.[0-9]{2})?)",
 }
 
 DOCUMENT_TYPE_KEYWORDS = {
@@ -130,10 +129,15 @@ def redact_pii(text: str, redact_char: str = "█") -> tuple[str, int]:
 def extract_invoice_fields(text: str) -> Dict[str, str]:
     """Extract structured key-value invoice fields."""
     fields = {}
+    stopwords = {"se", "no", "is", "of", "to", "in", "on", "at", "by", "or", "and", "the", "for"}
     for field_name, pattern in INVOICE_FIELDS.items():
         match = re.search(pattern, text)
         if match:
-            fields[field_name] = match.group(1).strip() if match.lastindex else match.group(0).strip()
+            val = match.group(1).strip() if match.lastindex else match.group(0).strip()
+            # Eliminate trivial noise and punctuation-only values
+            clean_val = val.strip(" :#-.")
+            if len(clean_val) >= 2 and clean_val.lower() not in stopwords:
+                fields[field_name] = clean_val
     return fields
 
 

src/ocr_engine.py

@@ -1,52 +1,44 @@
 """
-ocr_engine.py — Cached EasyOCR inference engine.
+ocr_engine.py — Advanced EasyOCR inference engine with accuracy measurement.
 Features:
   - GPU-accelerated inference (CUDA auto-detect)
-  - @st.cache_resource singleton (loads weights once)
-  - Returns rich structured results: bbox, text, confidence
-  - Supports multi-language (English + Hindi)
+  - @st.cache_resource singleton reader
+  - High-sensitivity parameters tuned for live camera & scanned photos
+  - Fallback multi-pass OCR for difficult lighting / low-contrast text
+  - Comprehensive OCR accuracy and quality metrics calculation
 """
 
 import streamlit as st
 import easyocr
 import numpy as np
+import re
 from PIL import Image
-from typing import List, Dict, Any
+from typing import List, Dict, Any, Tuple
 
 
-@st.cache_resource(show_spinner="🧠 Loading OCR engine (one-time)...")
-def get_reader(languages: list = None) -> easyocr.Reader:
+@st.cache_resource(show_spinner="🧠 Loading EasyOCR engine (one-time initialization)...")
+def get_reader(languages: Tuple[str, ...]) -> easyocr.Reader:
     """
     Cached singleton OCR reader. Loaded once per session.
     Auto-detects CUDA GPU for acceleration.
     """
-    if languages is None:
-        languages = ["en", "hi"]
     try:
         import torch
         gpu = torch.cuda.is_available()
-    except ImportError:
+    except Exception:
         gpu = False
-    return easyocr.Reader(languages, gpu=gpu)
+    return easyocr.Reader(list(languages), gpu=gpu)
 
 
 def run_ocr(
     pil_img: Image.Image,
     languages: list = None,
-    confidence_threshold: float = 0.3
+    confidence_threshold: float = 0.25,
+    camera_mode: bool = False,
 ) -> List[Dict[str, Any]]:
     """
-    Run OCR on a PIL image.
-
-    Returns list of dicts:
-    {
-        "bbox": [[x1,y1],[x2,y1],[x2,y2],[x1,y2]],
-        "text": "...",
-        "confidence": 0.97,
-        "center": (cx, cy),
-        "width": w,
-        "height": h
-    }
+    Execute neural OCR with parameters tuned for maximum detection recall and precision.
+    Supports camera mode with multi-pass recognition for challenging live captures.
     """
     if languages is None:
         languages = ["en", "hi"]
@@ -54,16 +46,42 @@ def run_ocr(
     reader = get_reader(tuple(languages))
     img_array = np.array(pil_img.convert("RGB"))
 
-    raw_results = reader.readtext(img_array)
+    # Primary pass with optimized thresholds
+    text_th = 0.35 if camera_mode else 0.40
+    low_th = 0.20 if camera_mode else 0.25
+    contrast_th = 0.05 if camera_mode else 0.10
+
+    raw_results = reader.readtext(
+        img_array,
+        text_threshold=text_th,
+        low_text=low_th,
+        contrast_ths=contrast_th,
+        adjust_contrast=0.7 if camera_mode else 0.5,
+        link_threshold=0.35,
+        decoder="greedy",
+    )
+
+    # If very few words detected on a live capture, attempt secondary high-sensitivity pass
+    if len(raw_results) < 4:
+        raw_results_fallback = reader.readtext(
+            img_array,
+            text_threshold=0.25,
+            low_text=0.15,
+            contrast_ths=0.03,
+            adjust_contrast=0.9,
+            link_threshold=0.25,
+        )
+        if len(raw_results_fallback) > len(raw_results):
+            raw_results = raw_results_fallback
 
     structured = []
     for (bbox, text, prob) in raw_results:
+        clean_text = text.strip()
         if prob < confidence_threshold:
             continue
-        if not text.strip():
+        if not clean_text:
             continue
 
-        # bbox is [[x1,y1],[x2,y1],[x2,y2],[x1,y2]]
         xs = [p[0] for p in bbox]
         ys = [p[1] for p in bbox]
         cx = int(np.mean(xs))
@@ -73,7 +91,7 @@ def run_ocr(
 
         structured.append({
             "bbox": bbox,
-            "text": text.strip(),
+            "text": clean_text,
             "confidence": float(prob),
             "center": (cx, cy),
             "width": w,
@@ -88,48 +106,105 @@ def run_ocr(
 
 
 def get_full_text(results: List[Dict]) -> str:
-    """Reconstruct full plain text from OCR results, preserving reading order."""
-    # Sort by y then x (reading order)
-    sorted_results = sorted(results, key=lambda r: (r["y_min"], r["x_min"]))
+    """Reconstruct full plain text from OCR results preserving natural reading order."""
+    sorted_results = sorted(results, key=lambda r: (r["y_min"] // 20, r["x_min"]))
     return " ".join(r["text"] for r in sorted_results)
 
 
-def get_lines(results: List[Dict], line_gap_threshold: int = 15) -> List[List[Dict]]:
-    """Group OCR results into lines based on vertical proximity."""
+def compute_accuracy_metrics(results: List[Dict], full_text: str = "") -> Dict[str, Any]:
+    """
+    Measure comprehensive OCR accuracy, character recognition quality, and text coherence.
+    Returns:
+      - overall_accuracy: 0-100%
+      - quality_grade: 'A+' | 'A' | 'B' | 'C' | 'D'
+      - avg_confidence: float (0-1)
+      - high_conf_pct: % words with conf >= 80%
+      - medium_conf_pct: % words with conf 50-79%
+      - low_conf_pct: % words with conf < 50%
+      - lexical_validity: % of recognized tokens with standard alphanumeric structure
+      - readability_status: Description of reliability
+    """
     if not results:
-        return []
-
-    sorted_results = sorted(results, key=lambda r: r["y_min"])
-    lines = []
-    current_line = [sorted_results[0]]
+        return {
+            "overall_accuracy": 0.0,
+            "quality_grade": "N/A",
+            "avg_confidence": 0.0,
+            "high_conf_count": 0,
+            "medium_conf_count": 0,
+            "low_conf_count": 0,
+            "high_conf_pct": 0.0,
+            "medium_conf_pct": 0.0,
+            "low_conf_pct": 0.0,
+            "total_words": 0,
+            "total_characters": 0,
+            "lexical_validity": 0.0,
+            "reliability_label": "No Text Detected",
+            "reliability_color": "#94a3b8",
+        }
 
-    for result in sorted_results[1:]:
-        prev_y = current_line[-1]["center"][1]
-        curr_y = result["center"][1]
-        if abs(curr_y - prev_y) <= line_gap_threshold:
-            current_line.append(result)
-        else:
-            lines.append(sorted(current_line, key=lambda r: r["x_min"]))
-            current_line = [result]
-
-    if current_line:
-        lines.append(sorted(current_line, key=lambda r: r["x_min"]))
+    confidences = [r["confidence"] for r in results]
+    total_words = len(results)
+    avg_conf = float(np.mean(confidences))
+
+    high_c = sum(1 for c in confidences if c >= 0.80)
+    med_c = sum(1 for c in confidences if 0.50 <= c < 0.80)
+    low_c = sum(1 for c in confidences if c < 0.50)
+
+    # Lexical validity: check if word contains intelligible alphanumeric patterns
+    valid_tokens = 0
+    total_chars = 0
+    for r in results:
+        t = r["text"]
+        total_chars += len(t)
+        # Token has letters or numbers (not pure punctuation noise)
+        if re.search(r"[A-Za-z0-9\u0900-\u097F]", t):
+            valid_tokens += 1
+
+    lexical_validity = (valid_tokens / total_words) if total_words > 0 else 0.0
+
+    # Composite OCR Accuracy Index (weighted: 70% confidence + 30% lexical validity)
+    overall_accuracy = (avg_conf * 0.70 + lexical_validity * 0.30) * 100.0
+
+    # Determine Quality Grade
+    if overall_accuracy >= 90.0:
+        grade = "A+"
+        label = "Exceptional Accuracy"
+        color = "#16a34a"  # Green
+    elif overall_accuracy >= 80.0:
+        grade = "A"
+        label = "High Accuracy (Production Ready)"
+        color = "#22c55e"
+    elif overall_accuracy >= 68.0:
+        grade = "B"
+        label = "Good / Readable"
+        color = "#eab308"  # Yellow
+    elif overall_accuracy >= 50.0:
+        grade = "C"
+        label = "Moderate (Review Recommended)"
+        color = "#f97316"  # Orange
+    else:
+        grade = "D"
+        label = "Low (Retake photo with better lighting)"
+        color = "#ef4444"  # Red
 
-    return lines
+    return {
+        "overall_accuracy": round(overall_accuracy, 1),
+        "quality_grade": grade,
+        "avg_confidence": round(avg_conf, 3),
+        "high_conf_count": high_c,
+        "medium_conf_count": med_c,
+        "low_conf_count": low_c,
+        "high_conf_pct": round((high_c / total_words) * 100.0, 1),
+        "medium_conf_pct": round((med_c / total_words) * 100.0, 1),
+        "low_conf_pct": round((low_c / total_words) * 100.0, 1),
+        "total_words": total_words,
+        "total_characters": total_chars,
+        "lexical_validity": round(lexical_validity * 100.0, 1),
+        "reliability_label": label,
+        "reliability_color": color,
+    }
 
 
 def get_statistics(results: List[Dict]) -> Dict[str, Any]:
-    """Compute statistics about the OCR results."""
-    if not results:
-        return {}
-
-    confidences = [r["confidence"] for r in results]
-    return {
-        "total_words": len(results),
-        "avg_confidence": float(np.mean(confidences)),
-        "min_confidence": float(np.min(confidences)),
-        "max_confidence": float(np.max(confidences)),
-        "high_conf_count": sum(1 for c in confidences if c >= 0.8),
-        "medium_conf_count": sum(1 for c in confidences if 0.5 <= c < 0.8),
-        "low_conf_count": sum(1 for c in confidences if c < 0.5),
-    }
+    """Compatibility wrapper that delegates to compute_accuracy_metrics."""
+    return compute_accuracy_metrics(results)

src/preprocessor.py

@@ -1,19 +1,30 @@
 """
-preprocessor.py — OpenCV Computer Vision preprocessing pipeline.
+preprocessor.py — Advanced Computer Vision preprocessing pipeline for documents and live camera photos.
 Features:
+  - EXIF rotation normalization (vital for mobile/camera photos)
   - Auto-deskew via Hough line transform
-  - CLAHE contrast enhancement
-  - Bilateral denoising
-  - Perspective warp (4-corner flattening)
-  - Adaptive binarization
+  - Background shadow & illumination normalization
+  - Unsharp masking for camera blur correction
+  - CLAHE adaptive contrast enhancement
+  - Bilateral edge-preserving denoising
+  - Adaptive Otsu binarization
+  - Perspective warp for angled captures
 """
 
 import cv2
 import numpy as np
-from PIL import Image
+from PIL import Image, ImageOps
 import math
 
 
+def fix_exif_orientation(pil_img: Image.Image) -> Image.Image:
+    """Normalize image orientation using EXIF data (crucial for phone & webcam photos)."""
+    try:
+        return ImageOps.exif_transpose(pil_img)
+    except Exception:
+        return pil_img
+
+
 def pil_to_cv2(pil_img: Image.Image) -> np.ndarray:
     """Convert PIL Image → OpenCV BGR ndarray."""
     arr = np.array(pil_img.convert("RGB"))
@@ -26,6 +37,37 @@ def cv2_to_pil(cv2_img: np.ndarray) -> Image.Image:
     return Image.fromarray(rgb)
 
 
+def remove_shadows_and_normalize(cv2_img: np.ndarray) -> np.ndarray:
+    """
+    Remove uneven background shadows and normalize illumination.
+    Particularly effective for phone photos with cast shadows or glare.
+    """
+    # Split into color planes
+    rgb_planes = cv2.split(cv2_img)
+    result_planes = []
+
+    for plane in rgb_planes:
+        # Dilate to approximate background
+        dilated_img = cv2.dilate(plane, np.ones((7, 7), np.uint8))
+        bg_img = cv2.medianBlur(dilated_img, 21)
+        # Difference between plane and estimated background
+        diff_img = 255 - cv2.absdiff(plane, bg_img)
+        # Normalize to full dynamic range
+        norm_img = cv2.normalize(
+            diff_img, None, alpha=0, beta=255, norm_type=cv2.NORM_MINMAX, dtype=cv2.CV_8UC1
+        )
+        result_planes.append(norm_img)
+
+    return cv2.merge(result_planes)
+
+
+def sharpen_image(cv2_img: np.ndarray, strength: float = 1.3) -> np.ndarray:
+    """Apply unsharp mask filter to sharpen slightly blurry camera captures."""
+    gaussian = cv2.GaussianBlur(cv2_img, (0, 0), 2.0)
+    sharpened = cv2.addWeighted(cv2_img, 1.0 + strength, gaussian, -strength, 0)
+    return sharpened
+
+
 def auto_deskew(img: np.ndarray) -> np.ndarray:
     """Detect text tilt and rotate image to align text horizontally."""
     gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
@@ -44,8 +86,8 @@ def auto_deskew(img: np.ndarray) -> np.ndarray:
     else:
         angle = -angle
 
-    # Only correct if tilt is significant
-    if abs(angle) < 0.5 or abs(angle) > 45:
+    # Only correct if tilt is moderate and significant
+    if abs(angle) < 0.6 or abs(angle) > 40:
         return img
 
     h, w = img.shape[:2]
@@ -59,51 +101,54 @@ def auto_deskew(img: np.ndarray) -> np.ndarray:
     return rotated
 
 
-def enhance_contrast(img: np.ndarray) -> np.ndarray:
-    """Apply CLAHE (Contrast Limited Adaptive Histogram Equalization) per channel."""
+def enhance_contrast(img: np.ndarray, clip_limit: float = 2.5) -> np.ndarray:
+    """Apply CLAHE (Contrast Limited Adaptive Histogram Equalization)."""
     lab = cv2.cvtColor(img, cv2.COLOR_BGR2LAB)
     l, a, b = cv2.split(lab)
-    clahe = cv2.createCLAHE(clipLimit=3.0, tileGridSize=(8, 8))
+    clahe = cv2.createCLAHE(clipLimit=clip_limit, tileGridSize=(8, 8))
     l_enhanced = clahe.apply(l)
     merged = cv2.merge([l_enhanced, a, b])
     return cv2.cvtColor(merged, cv2.COLOR_LAB2BGR)
 
 
 def denoise(img: np.ndarray) -> np.ndarray:
-    """Bilateral filter to remove noise while preserving text edges."""
-    return cv2.bilateralFilter(img, d=9, sigmaColor=75, sigmaSpace=75)
+    """Bilateral filter to remove camera noise while preserving text edges."""
+    return cv2.bilateralFilter(img, d=7, sigmaColor=50, sigmaSpace=50)
 
 
 def binarize(img: np.ndarray) -> np.ndarray:
-    """Adaptive Otsu binarization for high-contrast black/white output."""
+    """Adaptive Gaussian thresholding for crisp black/white document text."""
     gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
-    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY | cv2.THRESH_OTSU)
+    # Background shadow removal prior to binarization
+    dilated = cv2.dilate(gray, np.ones((7, 7), np.uint8))
+    bg = cv2.medianBlur(dilated, 21)
+    diff = 255 - cv2.absdiff(gray, bg)
+    norm = cv2.normalize(diff, None, alpha=0, beta=255, norm_type=cv2.NORM_MINMAX, dtype=cv2.CV_8UC1)
+    
+    binary = cv2.adaptiveThreshold(
+        norm, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C, cv2.THRESH_BINARY, 21, 10
+    )
     return cv2.cvtColor(binary, cv2.COLOR_GRAY2BGR)
 
 
 def detect_document_corners(img: np.ndarray):
-    """
-    Detect the 4 corners of a document for perspective warp.
-    Returns corners array or None if not detected.
-    """
+    """Detect the 4 corners of a document for perspective warp."""
     gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
     blurred = cv2.GaussianBlur(gray, (5, 5), 0)
-    edged = cv2.Canny(blurred, 75, 200)
+    edged = cv2.Canny(blurred, 50, 150)
 
     contours, _ = cv2.findContours(edged.copy(), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
     if not contours:
         return None
 
     contours = sorted(contours, key=cv2.contourArea, reverse=True)[:5]
-    screen_cnt = None
     for c in contours:
         peri = cv2.arcLength(c, True)
         approx = cv2.approxPolyDP(c, 0.02 * peri, True)
-        if len(approx) == 4:
-            screen_cnt = approx
-            break
+        if len(approx) == 4 and cv2.contourArea(c) > (img.shape[0] * img.shape[1] * 0.15):
+            return approx
 
-    return screen_cnt
+    return None
 
 
 def order_points(pts):
@@ -132,6 +177,9 @@ def perspective_warp(img: np.ndarray, corners) -> np.ndarray:
     height_b = np.linalg.norm(tl - bl)
     max_height = max(int(height_a), int(height_b))
 
+    if max_width < 100 or max_height < 100:
+        return img
+
     dst = np.array([
         [0, 0],
         [max_width - 1, 0],
@@ -146,39 +194,65 @@ def perspective_warp(img: np.ndarray, corners) -> np.ndarray:
 
 def full_preprocess(pil_img: Image.Image, mode: str = "auto") -> tuple[Image.Image, dict]:
     """
-    Full preprocessing pipeline.
-    mode: 'raw' | 'auto' | 'binarize' | 'warp'
-    Returns (processed_pil_image, metadata_dict)
+    Comprehensive document preprocessing pipeline.
+    Modes:
+      - 'auto': EXIF fix + deskew + shadow removal + CLAHE + sharpening + gentle denoise
+      - 'camera_enhance': Specialized for live camera / phone photos (shadows, glare, blur compensation)
+      - 'binarize': High contrast B&W text thresholding
+      - 'warp': 4-corner perspective flattening
+      - 'raw': Passthrough with EXIF rotation fixed
     """
-    cv2_img = pil_to_cv2(pil_img)
-    steps_applied = []
+    # Always normalize EXIF orientation first
+    fixed_pil = fix_exif_orientation(pil_img)
+    steps_applied = ["exif_orientation_fixed"]
 
     if mode == "raw":
-        return pil_img, {"steps": ["raw"]}
+        return fixed_pil, {"steps": ["raw_passthrough"]}
+
+    cv2_img = pil_to_cv2(fixed_pil)
+
+    # Resolution scaling check: if too small (e.g. low-res webcam), upscale with bicubic
+    h, w = cv2_img.shape[:2]
+    if min(h, w) < 700:
+        scale = 800.0 / min(h, w)
+        cv2_img = cv2.resize(cv2_img, (int(w * scale), int(h * scale)), interpolation=cv2.INTER_CUBIC)
+        steps_applied.append("rescale_upscale")
+
+    # Step 1: Perspective Warp if explicitly selected
+    if mode == "warp":
+        corners = detect_document_corners(cv2_img)
+        if corners is not None:
+            cv2_img = perspective_warp(cv2_img, corners)
+            steps_applied.append("perspective_warp")
+        else:
+            steps_applied.append("warp_not_detected")
 
-    # Step 1: Auto deskew
+    # Step 2: Auto Deskew
     deskewed = auto_deskew(cv2_img)
     if not np.array_equal(deskewed, cv2_img):
-        steps_applied.append("deskew")
+        steps_applied.append("auto_deskew")
     cv2_img = deskewed
 
-    # Step 2: Contrast enhancement
-    cv2_img = enhance_contrast(cv2_img)
-    steps_applied.append("CLAHE contrast")
+    # Step 3: Camera photo shadow removal & illumination flattening
+    if mode in ("camera_enhance", "auto"):
+        cv2_img = remove_shadows_and_normalize(cv2_img)
+        steps_applied.append("shadow_illumination_norm")
+
+    # Step 4: CLAHE Contrast Enhancement
+    cv2_img = enhance_contrast(cv2_img, clip_limit=3.0 if mode == "camera_enhance" else 2.2)
+    steps_applied.append("clahe_contrast")
 
-    # Step 3: Denoise
+    # Step 5: Unsharp masking to sharpen characters
+    cv2_img = sharpen_image(cv2_img, strength=1.2 if mode == "camera_enhance" else 0.8)
+    steps_applied.append("unsharp_mask_sharpen")
+
+    # Step 6: Denoise
     cv2_img = denoise(cv2_img)
-    steps_applied.append("bilateral denoise")
+    steps_applied.append("bilateral_denoise")
 
+    # Step 7: Binarization if requested
     if mode == "binarize":
         cv2_img = binarize(cv2_img)
-        steps_applied.append("Otsu binarize")
-    elif mode == "warp":
-        corners = detect_document_corners(cv2_img)
-        if corners is not None:
-            cv2_img = perspective_warp(cv2_img, corners)
-            steps_applied.append("perspective warp")
-        else:
-            steps_applied.append("warp not detected")
+        steps_applied.append("adaptive_binarize")
 
     return cv2_to_pil(cv2_img), {"steps": steps_applied}