From fa958d31f6234e5fcb8c4135a2e547d36809006b Mon Sep 17 00:00:00 2001
From: BreakPilot Dev <dev@breakpilot.app>
Date: Mon, 9 Feb 2026 23:52:35 +0100
Subject: [PATCH] feat(ocr): Add CV Document Reconstruction Pipeline for
 vocabulary extraction

New OCR method using classical Computer Vision: high-res rendering (432 DPI),
deskew, dewarp, binarization, projection-profile layout analysis, multi-pass
Tesseract OCR with region-specific PSM, and Y-coordinate line alignment.
Includes bugfix for convert_pdf_to_image call (line 869) and 39 unit tests.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
---
 admin-v2/app/(admin)/ai/ocr-compare/page.tsx  |   82 +-
 klausur-service/backend/cv_vocab_pipeline.py  | 1019 +++++++++++++++++
 .../backend/tests/test_cv_vocab_pipeline.py   |  569 +++++++++
 .../backend/vocab_worksheet_api.py            |  476 +++++++-
 4 files changed, 2096 insertions(+), 50 deletions(-)
 create mode 100644 klausur-service/backend/cv_vocab_pipeline.py
 create mode 100644 klausur-service/backend/tests/test_cv_vocab_pipeline.py

diff --git a/admin-v2/app/(admin)/ai/ocr-compare/page.tsx b/admin-v2/app/(admin)/ai/ocr-compare/page.tsx
index d2ee594..4c2e69d 100644
--- a/admin-v2/app/(admin)/ai/ocr-compare/page.tsx
+++ b/admin-v2/app/(admin)/ai/ocr-compare/page.tsx
@@ -93,6 +93,15 @@ const OCR_METHODS = {
     description: 'ARM64-nativ, Standard',
     enabled: true,
   },
+  cv_pipeline: {
+    id: 'cv_pipeline',
+    name: 'Loesung E: Document Reconstruction',
+    shortName: 'E: Doc Recon',
+    model: 'opencv + tesseract (multi-pass)',
+    color: 'green',
+    description: 'CV-Pipeline: Deskew, Dewarp, Binarisierung, Multi-Pass OCR',
+    enabled: true,
+  },
 }
 
 export default function OCRComparePage() {
@@ -115,7 +124,7 @@ export default function OCRComparePage() {
   const [uploading, setUploading] = useState(false)
 
   // Method Selection
-  const [selectedMethods, setSelectedMethods] = useState<string[]>(['vision_llm', 'tesseract'])
+  const [selectedMethods, setSelectedMethods] = useState<string[]>(['vision_llm', 'tesseract', 'cv_pipeline'])
 
   // QR Upload State
   const [showQRModal, setShowQRModal] = useState(false)
@@ -133,6 +142,9 @@ export default function OCRComparePage() {
   const [showGridOverlay, setShowGridOverlay] = useState(true)
   const [selectedCell, setSelectedCell] = useState<GridCell | null>(null)
   const [showCellDialog, setShowCellDialog] = useState(false)
+  const [showMmGrid, setShowMmGrid] = useState(false)
+  const [showTextAtPosition, setShowTextAtPosition] = useState(false)
+  const [editableText, setEditableText] = useState(false)
 
   // Block Review State
   const [blockReviewMode, setBlockReviewMode] = useState(false)
@@ -651,6 +663,7 @@ export default function OCRComparePage() {
       blue: { bg: 'bg-blue-50', border: 'border-blue-300', text: 'text-blue-700' },
       red: { bg: 'bg-red-50', border: 'border-red-300', text: 'text-red-700' },
       purple: { bg: 'bg-purple-50', border: 'border-purple-300', text: 'text-purple-700' },
+      green: { bg: 'bg-green-50', border: 'border-green-300', text: 'text-green-700' },
     }
     return colors[color]?.[type] || colors.slate[type]
   }
@@ -839,7 +852,7 @@ export default function OCRComparePage() {
                 {/* Grid Analysis Button */}
                 <button
                   onClick={analyzeGrid}
-                  disabled={analyzingGrid}
+                  disabled={analyzingGrid || !sessionId || !result}
                   className="w-full px-4 py-2 bg-teal-600 text-white rounded-lg font-medium hover:bg-teal-700 disabled:opacity-50 disabled:cursor-not-allowed text-sm"
                 >
                   {analyzingGrid ? (
@@ -874,6 +887,41 @@ export default function OCRComparePage() {
                     <span className="text-slate-700">Grid-Overlay anzeigen</span>
                   </label>
 
+                  <label className="flex items-center gap-2 text-sm cursor-pointer">
+                    <input
+                      type="checkbox"
+                      checked={showMmGrid}
+                      onChange={(e) => setShowMmGrid(e.target.checked)}
+                      className="rounded"
+                    />
+                    <span className="text-slate-700">1mm Raster anzeigen</span>
+                  </label>
+
+                  <label className="flex items-center gap-2 text-sm cursor-pointer">
+                    <input
+                      type="checkbox"
+                      checked={showTextAtPosition}
+                      onChange={(e) => {
+                        setShowTextAtPosition(e.target.checked)
+                        if (!e.target.checked) setEditableText(false)
+                      }}
+                      className="rounded"
+                    />
+                    <span className="text-slate-700">Text an Originalposition</span>
+                  </label>
+
+                  {showTextAtPosition && (
+                    <label className="flex items-center gap-2 text-sm cursor-pointer ml-5">
+                      <input
+                        type="checkbox"
+                        checked={editableText}
+                        onChange={(e) => setEditableText(e.target.checked)}
+                        className="rounded"
+                      />
+                      <span className="text-slate-700">Text bearbeitbar</span>
+                    </label>
+                  )}
+
                   {/* Block Review Button */}
                   {result && nonEmptyBlockCount > 0 && (
                     <button
@@ -1122,7 +1170,20 @@ export default function OCRComparePage() {
                               selectedCell={selectedCell}
                               showEmpty={false}
                               showNumbers={blockReviewMode}
-                              showTextLabels={true}
+                              showTextLabels={!showTextAtPosition}
+                              showMmGrid={showMmGrid}
+                              showTextAtPosition={showTextAtPosition}
+                              editableText={editableText}
+                              onCellTextChange={(cell, newText) => {
+                                if (!gridData) return
+                                const newCells = gridData.cells.map(row =>
+                                  row.map(c => c.row === cell.row && c.col === cell.col
+                                    ? { ...c, text: newText, status: 'manual' as const }
+                                    : c
+                                  )
+                                )
+                                setGridData({ ...gridData, cells: newCells })
+                              }}
                               highlightedBlockNumber={blockReviewMode ? currentBlockNumber : null}
                               className={`rounded-lg border border-slate-200 overflow-hidden ${isFullscreen ? 'max-h-[80vh] mx-auto' : 'w-full max-w-2xl mx-auto'}`}
                             />
@@ -1229,7 +1290,20 @@ export default function OCRComparePage() {
                                 selectedCell={selectedCell}
                                 showEmpty={false}
                                 showNumbers={blockReviewMode}
-                                showTextLabels={!blockReviewMode}
+                                showTextLabels={!blockReviewMode && !showTextAtPosition}
+                                showMmGrid={showMmGrid}
+                                showTextAtPosition={showTextAtPosition}
+                                editableText={editableText}
+                                onCellTextChange={(cell, newText) => {
+                                  if (!gridData) return
+                                  const newCells = gridData.cells.map(row =>
+                                    row.map(c => c.row === cell.row && c.col === cell.col
+                                      ? { ...c, text: newText, status: 'manual' as const }
+                                      : c
+                                    )
+                                  )
+                                  setGridData({ ...gridData, cells: newCells })
+                                }}
                                 highlightedBlockNumber={blockReviewMode ? currentBlockNumber : null}
                                 className="rounded-lg border border-slate-200 overflow-hidden"
                               />
diff --git a/klausur-service/backend/cv_vocab_pipeline.py b/klausur-service/backend/cv_vocab_pipeline.py
new file mode 100644
index 0000000..8ef1304
--- /dev/null
+++ b/klausur-service/backend/cv_vocab_pipeline.py
@@ -0,0 +1,1019 @@
+"""
+CV-based Document Reconstruction Pipeline for Vocabulary Extraction.
+
+Uses classical Computer Vision techniques for high-quality OCR:
+- High-resolution PDF rendering (432 DPI)
+- Deskew (rotation correction via Hough Lines)
+- Dewarp (book curvature correction) — pass-through initially
+- Dual image preparation (binarized for OCR, CLAHE for layout)
+- Projection-profile layout analysis (column/row detection)
+- Multi-pass Tesseract OCR with region-specific PSM settings
+- Y-coordinate line alignment for vocabulary matching
+- Optional LLM post-correction for low-confidence regions
+
+Lizenz: Apache 2.0 (kommerziell nutzbar)
+DATENSCHUTZ: Alle Verarbeitung erfolgt lokal.
+"""
+
+import io
+import logging
+import time
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional, Tuple
+
+import numpy as np
+
+logger = logging.getLogger(__name__)
+
+# --- Availability Guards ---
+
+try:
+    import cv2
+    CV2_AVAILABLE = True
+except ImportError:
+    cv2 = None
+    CV2_AVAILABLE = False
+    logger.warning("OpenCV not available — CV pipeline disabled")
+
+try:
+    import pytesseract
+    from PIL import Image
+    TESSERACT_AVAILABLE = True
+except ImportError:
+    pytesseract = None
+    Image = None
+    TESSERACT_AVAILABLE = False
+    logger.warning("pytesseract/Pillow not available — CV pipeline disabled")
+
+CV_PIPELINE_AVAILABLE = CV2_AVAILABLE and TESSERACT_AVAILABLE
+
+
+# --- Data Classes ---
+
+@dataclass
+class PageRegion:
+    """A detected region on the page."""
+    type: str           # 'column_en', 'column_de', 'column_example', 'header', 'footer'
+    x: int
+    y: int
+    width: int
+    height: int
+
+
+@dataclass
+class VocabRow:
+    """A single vocabulary entry assembled from multi-column OCR."""
+    english: str = ""
+    german: str = ""
+    example: str = ""
+    confidence: float = 0.0
+    y_position: int = 0
+
+
+@dataclass
+class PipelineResult:
+    """Complete result of the CV pipeline."""
+    vocabulary: List[Dict[str, Any]] = field(default_factory=list)
+    word_count: int = 0
+    columns_detected: int = 0
+    duration_seconds: float = 0.0
+    stages: Dict[str, float] = field(default_factory=dict)
+    error: Optional[str] = None
+    image_width: int = 0
+    image_height: int = 0
+
+
+# =============================================================================
+# Stage 1: High-Resolution PDF Rendering
+# =============================================================================
+
+def render_pdf_high_res(pdf_data: bytes, page_number: int = 0, zoom: float = 3.0) -> np.ndarray:
+    """Render a PDF page to a high-resolution numpy array (BGR).
+
+    Args:
+        pdf_data: Raw PDF bytes.
+        page_number: 0-indexed page number.
+        zoom: Zoom factor (3.0 = 432 DPI).
+
+    Returns:
+        numpy array in BGR format.
+    """
+    import fitz  # PyMuPDF
+
+    pdf_doc = fitz.open(stream=pdf_data, filetype="pdf")
+    if page_number >= pdf_doc.page_count:
+        raise ValueError(f"Page {page_number} does not exist (PDF has {pdf_doc.page_count} pages)")
+
+    page = pdf_doc[page_number]
+    mat = fitz.Matrix(zoom, zoom)
+    pix = page.get_pixmap(matrix=mat)
+
+    # Convert to numpy BGR
+    img_data = np.frombuffer(pix.samples, dtype=np.uint8).reshape(pix.h, pix.w, pix.n)
+    if pix.n == 4:  # RGBA
+        img_bgr = cv2.cvtColor(img_data, cv2.COLOR_RGBA2BGR)
+    elif pix.n == 3:  # RGB
+        img_bgr = cv2.cvtColor(img_data, cv2.COLOR_RGB2BGR)
+    else:  # Grayscale
+        img_bgr = cv2.cvtColor(img_data, cv2.COLOR_GRAY2BGR)
+
+    pdf_doc.close()
+    return img_bgr
+
+
+def render_image_high_res(image_data: bytes) -> np.ndarray:
+    """Load an image (PNG/JPEG) into a numpy array (BGR).
+
+    Args:
+        image_data: Raw image bytes.
+
+    Returns:
+        numpy array in BGR format.
+    """
+    img_array = np.frombuffer(image_data, dtype=np.uint8)
+    img_bgr = cv2.imdecode(img_array, cv2.IMREAD_COLOR)
+    if img_bgr is None:
+        raise ValueError("Could not decode image data")
+    return img_bgr
+
+
+# =============================================================================
+# Stage 2: Deskew (Rotation Correction)
+# =============================================================================
+
+def deskew_image(img: np.ndarray) -> Tuple[np.ndarray, float]:
+    """Correct rotation using Hough Line detection.
+
+    Args:
+        img: BGR image.
+
+    Returns:
+        Tuple of (corrected image, detected angle in degrees).
+    """
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    # Binarize for line detection
+    _, binary = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY_INV + cv2.THRESH_OTSU)
+
+    # Detect lines
+    lines = cv2.HoughLinesP(binary, 1, np.pi / 180, threshold=100,
+                            minLineLength=img.shape[1] // 4, maxLineGap=20)
+
+    if lines is None or len(lines) < 3:
+        return img, 0.0
+
+    # Compute angles of near-horizontal lines
+    angles = []
+    for line in lines:
+        x1, y1, x2, y2 = line[0]
+        angle = np.degrees(np.arctan2(y2 - y1, x2 - x1))
+        if abs(angle) < 15:  # Only near-horizontal
+            angles.append(angle)
+
+    if not angles:
+        return img, 0.0
+
+    median_angle = float(np.median(angles))
+
+    # Limit correction to ±5°
+    if abs(median_angle) > 5.0:
+        median_angle = 5.0 * np.sign(median_angle)
+
+    if abs(median_angle) < 0.1:
+        return img, 0.0
+
+    # Rotate
+    h, w = img.shape[:2]
+    center = (w // 2, h // 2)
+    M = cv2.getRotationMatrix2D(center, median_angle, 1.0)
+    corrected = cv2.warpAffine(img, M, (w, h),
+                               flags=cv2.INTER_LINEAR,
+                               borderMode=cv2.BORDER_REPLICATE)
+
+    logger.info(f"Deskew: corrected {median_angle:.2f}° rotation")
+    return corrected, median_angle
+
+
+# =============================================================================
+# Stage 3: Dewarp (Book Curvature) — Pass-Through for now
+# =============================================================================
+
+def dewarp_image(img: np.ndarray) -> np.ndarray:
+    """Correct book curvature distortion.
+
+    Currently a pass-through. Will be implemented when book scans are tested.
+
+    Args:
+        img: BGR image.
+
+    Returns:
+        Corrected image (or original if no correction needed).
+    """
+    # TODO: Implement polynomial fitting + cv2.remap() for book curvature
+    return img
+
+
+# =============================================================================
+# Stage 4: Dual Image Preparation
+# =============================================================================
+
+def create_ocr_image(img: np.ndarray) -> np.ndarray:
+    """Create a binarized image optimized for Tesseract OCR.
+
+    Steps: Grayscale → Background normalization → Adaptive threshold → Denoise.
+
+    Args:
+        img: BGR image.
+
+    Returns:
+        Binary image (white text on black background inverted to black on white).
+    """
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+
+    # Background normalization: divide by blurred version
+    bg = cv2.GaussianBlur(gray, (51, 51), 0)
+    normalized = cv2.divide(gray, bg, scale=255)
+
+    # Adaptive binarization
+    binary = cv2.adaptiveThreshold(
+        normalized, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+        cv2.THRESH_BINARY, 31, 10
+    )
+
+    # Light denoise
+    denoised = cv2.medianBlur(binary, 3)
+
+    return denoised
+
+
+def create_layout_image(img: np.ndarray) -> np.ndarray:
+    """Create a CLAHE-enhanced grayscale image for layout analysis.
+
+    Args:
+        img: BGR image.
+
+    Returns:
+        Enhanced grayscale image.
+    """
+    gray = cv2.cvtColor(img, cv2.COLOR_BGR2GRAY)
+    clahe = cv2.createCLAHE(clipLimit=2.0, tileGridSize=(8, 8))
+    enhanced = clahe.apply(gray)
+    return enhanced
+
+
+# =============================================================================
+# Stage 5: Layout Analysis (Projection Profiles)
+# =============================================================================
+
+def _find_content_bounds(inv: np.ndarray) -> Tuple[int, int, int, int]:
+    """Find the bounding box of actual text content (excluding page margins).
+
+    Returns:
+        Tuple of (left_x, right_x, top_y, bottom_y).
+    """
+    h, w = inv.shape[:2]
+
+    # Horizontal projection for top/bottom
+    h_proj = np.sum(inv, axis=1).astype(float) / (w * 255)
+
+    top_y = 0
+    for y in range(h):
+        if h_proj[y] > 0.005:
+            top_y = max(0, y - 5)
+            break
+
+    bottom_y = h
+    for y in range(h - 1, 0, -1):
+        if h_proj[y] > 0.005:
+            bottom_y = min(h, y + 5)
+            break
+
+    # Vertical projection for left/right margins
+    v_proj = np.sum(inv[top_y:bottom_y, :], axis=0).astype(float)
+    v_proj_norm = v_proj / ((bottom_y - top_y) * 255) if (bottom_y - top_y) > 0 else v_proj
+
+    left_x = 0
+    for x in range(w):
+        if v_proj_norm[x] > 0.005:
+            left_x = max(0, x - 2)
+            break
+
+    right_x = w
+    for x in range(w - 1, 0, -1):
+        if v_proj_norm[x] > 0.005:
+            right_x = min(w, x + 2)
+            break
+
+    return left_x, right_x, top_y, bottom_y
+
+
+def analyze_layout(layout_img: np.ndarray, ocr_img: np.ndarray) -> List[PageRegion]:
+    """Detect columns, header, and footer using projection profiles.
+
+    Uses content-bounds detection to exclude page margins before searching
+    for column separators within the actual text area.
+
+    Args:
+        layout_img: CLAHE-enhanced grayscale image.
+        ocr_img: Binarized image for text density analysis.
+
+    Returns:
+        List of PageRegion objects describing detected regions.
+    """
+    h, w = ocr_img.shape[:2]
+
+    # Invert: black text on white → white text on black for projection
+    inv = cv2.bitwise_not(ocr_img)
+
+    # --- Find actual content bounds (exclude page margins) ---
+    left_x, right_x, top_y, bottom_y = _find_content_bounds(inv)
+    content_w = right_x - left_x
+    content_h = bottom_y - top_y
+
+    logger.info(f"Layout: content bounds x=[{left_x}..{right_x}] ({content_w}px), "
+                f"y=[{top_y}..{bottom_y}] ({content_h}px) in {w}x{h} image")
+
+    if content_w < w * 0.3 or content_h < h * 0.3:
+        # Fallback if detection seems wrong
+        left_x, right_x = 0, w
+        top_y, bottom_y = 0, h
+        content_w, content_h = w, h
+
+    # --- Vertical projection within content area to find column separators ---
+    content_strip = inv[top_y:bottom_y, left_x:right_x]
+    v_proj = np.sum(content_strip, axis=0).astype(float)
+    v_proj_norm = v_proj / (content_h * 255) if content_h > 0 else v_proj
+
+    # Smooth the projection profile
+    kernel_size = max(5, content_w // 50)
+    if kernel_size % 2 == 0:
+        kernel_size += 1
+    v_proj_smooth = np.convolve(v_proj_norm, np.ones(kernel_size) / kernel_size, mode='same')
+
+    # Debug: log projection profile statistics
+    p_mean = float(np.mean(v_proj_smooth))
+    p_median = float(np.median(v_proj_smooth))
+    p_min = float(np.min(v_proj_smooth))
+    p_max = float(np.max(v_proj_smooth))
+    logger.info(f"Layout: v_proj stats — min={p_min:.4f}, max={p_max:.4f}, "
+                f"mean={p_mean:.4f}, median={p_median:.4f}")
+
+    # Find valleys using multiple threshold strategies
+    # Strategy 1: relative to median (catches clear separators)
+    # Strategy 2: local minima approach (catches subtle gaps)
+    threshold = max(p_median * 0.3, p_mean * 0.2)
+    logger.info(f"Layout: valley threshold={threshold:.4f}")
+
+    in_valley = v_proj_smooth < threshold
+
+    # Find contiguous valley regions
+    all_valleys = []
+    start = None
+    for x in range(len(v_proj_smooth)):
+        if in_valley[x] and start is None:
+            start = x
+        elif not in_valley[x] and start is not None:
+            valley_width = x - start
+            valley_depth = float(np.min(v_proj_smooth[start:x]))
+            # Valley must be at least 3px wide
+            if valley_width >= 3:
+                all_valleys.append((start, x, (start + x) // 2, valley_width, valley_depth))
+            start = None
+
+    logger.info(f"Layout: raw valleys (before filter): {len(all_valleys)} — "
+                f"{[(v[0]+left_x, v[1]+left_x, v[3], f'{v[4]:.4f}') for v in all_valleys[:10]]}")
+
+    # Filter: valleys must be inside the content area (not at edges)
+    inner_margin = int(content_w * 0.08)
+    valleys = [v for v in all_valleys if inner_margin < v[2] < content_w - inner_margin]
+
+    # If no valleys found with strict threshold, try local minima approach
+    if len(valleys) < 2:
+        logger.info("Layout: trying local minima approach for column detection")
+        # Divide content into 20 segments, find the 2 lowest
+        seg_count = 20
+        seg_width = content_w // seg_count
+        seg_scores = []
+        for i in range(seg_count):
+            sx = i * seg_width
+            ex = min((i + 1) * seg_width, content_w)
+            seg_mean = float(np.mean(v_proj_smooth[sx:ex]))
+            seg_scores.append((i, sx, ex, seg_mean))
+
+        seg_scores.sort(key=lambda s: s[3])
+        logger.info(f"Layout: segment scores (lowest 5): "
+                    f"{[(s[0], s[1]+left_x, s[2]+left_x, f'{s[3]:.4f}') for s in seg_scores[:5]]}")
+
+        # Find two lowest non-adjacent segments that create reasonable columns
+        candidate_valleys = []
+        for seg_idx, sx, ex, seg_mean in seg_scores:
+            # Must not be at the edges
+            if seg_idx <= 1 or seg_idx >= seg_count - 2:
+                continue
+            # Must be significantly lower than overall mean
+            if seg_mean < p_mean * 0.6:
+                center = (sx + ex) // 2
+                candidate_valleys.append((sx, ex, center, ex - sx, seg_mean))
+
+        if len(candidate_valleys) >= 2:
+            # Pick the best pair: non-adjacent, creating reasonable column widths
+            candidate_valleys.sort(key=lambda v: v[2])
+            best_pair = None
+            best_score = float('inf')
+            for i in range(len(candidate_valleys)):
+                for j in range(i + 1, len(candidate_valleys)):
+                    c1 = candidate_valleys[i][2]
+                    c2 = candidate_valleys[j][2]
+                    # Must be at least 20% apart
+                    if (c2 - c1) < content_w * 0.2:
+                        continue
+                    col1 = c1
+                    col2 = c2 - c1
+                    col3 = content_w - c2
+                    # Each column at least 15%
+                    if col1 < content_w * 0.12 or col2 < content_w * 0.12 or col3 < content_w * 0.12:
+                        continue
+                    parts = sorted([col1, col2, col3])
+                    score = parts[2] - parts[0]
+                    if score < best_score:
+                        best_score = score
+                        best_pair = (candidate_valleys[i], candidate_valleys[j])
+
+            if best_pair:
+                valleys = list(best_pair)
+                logger.info(f"Layout: local minima found 2 valleys: "
+                            f"{[(v[0]+left_x, v[1]+left_x, v[3]) for v in valleys]}")
+
+    logger.info(f"Layout: final {len(valleys)} valleys: "
+                f"{[(v[0]+left_x, v[1]+left_x, v[3]) for v in valleys]}")
+
+    regions = []
+
+    if len(valleys) >= 2:
+        # 3-column layout detected
+        valleys.sort(key=lambda v: v[2])
+
+        if len(valleys) == 2:
+            sep1_center = valleys[0][2]
+            sep2_center = valleys[1][2]
+        else:
+            # Pick the two valleys that best divide into 3 parts
+            # Prefer wider valleys (more likely true separators)
+            best_pair = None
+            best_score = float('inf')
+            for i in range(len(valleys)):
+                for j in range(i + 1, len(valleys)):
+                    c1, c2 = valleys[i][2], valleys[j][2]
+                    # Each column should be at least 15% of content width
+                    col1 = c1
+                    col2 = c2 - c1
+                    col3 = content_w - c2
+                    if col1 < content_w * 0.15 or col2 < content_w * 0.15 or col3 < content_w * 0.15:
+                        continue
+                    # Score: lower is better (more even distribution)
+                    parts = sorted([col1, col2, col3])
+                    score = parts[2] - parts[0]
+                    # Bonus for wider valleys (subtract valley width)
+                    score -= (valleys[i][3] + valleys[j][3]) * 0.5
+                    if score < best_score:
+                        best_score = score
+                        best_pair = (c1, c2)
+            if best_pair:
+                sep1_center, sep2_center = best_pair
+            else:
+                sep1_center = valleys[0][2]
+                sep2_center = valleys[1][2]
+
+        # Convert from content-relative to absolute coordinates
+        abs_sep1 = sep1_center + left_x
+        abs_sep2 = sep2_center + left_x
+
+        logger.info(f"Layout: 3 columns at separators x={abs_sep1}, x={abs_sep2} "
+                    f"(widths: {abs_sep1}, {abs_sep2-abs_sep1}, {w-abs_sep2})")
+
+        regions.append(PageRegion(
+            type='column_en', x=0, y=top_y,
+            width=abs_sep1, height=content_h
+        ))
+        regions.append(PageRegion(
+            type='column_de', x=abs_sep1, y=top_y,
+            width=abs_sep2 - abs_sep1, height=content_h
+        ))
+        regions.append(PageRegion(
+            type='column_example', x=abs_sep2, y=top_y,
+            width=w - abs_sep2, height=content_h
+        ))
+
+    elif len(valleys) == 1:
+        # 2-column layout
+        abs_sep = valleys[0][2] + left_x
+
+        logger.info(f"Layout: 2 columns at separator x={abs_sep}")
+
+        regions.append(PageRegion(
+            type='column_en', x=0, y=top_y,
+            width=abs_sep, height=content_h
+        ))
+        regions.append(PageRegion(
+            type='column_de', x=abs_sep, y=top_y,
+            width=w - abs_sep, height=content_h
+        ))
+
+    else:
+        # No columns detected — run full-page OCR as single column
+        logger.warning("Layout: no column separators found, using full page")
+        regions.append(PageRegion(
+            type='column_en', x=0, y=top_y,
+            width=w, height=content_h
+        ))
+
+    # Add header/footer info
+    if top_y > 10:
+        regions.append(PageRegion(
+            type='header', x=0, y=0,
+            width=w, height=top_y
+        ))
+    if bottom_y < h - 10:
+        regions.append(PageRegion(
+            type='footer', x=0, y=bottom_y,
+            width=w, height=h - bottom_y
+        ))
+
+    col_count = len([r for r in regions if r.type.startswith('column')])
+    logger.info(f"Layout: {col_count} columns, "
+                f"header={'yes' if top_y > 10 else 'no'}, "
+                f"footer={'yes' if bottom_y < h - 10 else 'no'}")
+
+    return regions
+
+
+# =============================================================================
+# Stage 6: Multi-Pass OCR
+# =============================================================================
+
+def ocr_region(ocr_img: np.ndarray, region: PageRegion, lang: str,
+               psm: int, fallback_psm: Optional[int] = None,
+               min_confidence: float = 40.0) -> List[Dict[str, Any]]:
+    """Run Tesseract OCR on a specific region with given PSM.
+
+    Args:
+        ocr_img: Binarized full-page image.
+        region: Region to crop and OCR.
+        lang: Tesseract language string.
+        psm: Page Segmentation Mode.
+        fallback_psm: If confidence too low, retry with this PSM per line.
+        min_confidence: Minimum average confidence before fallback.
+
+    Returns:
+        List of word dicts with text, position, confidence.
+    """
+    # Crop region
+    crop = ocr_img[region.y:region.y + region.height,
+                   region.x:region.x + region.width]
+
+    if crop.size == 0:
+        return []
+
+    # Convert to PIL for pytesseract
+    pil_img = Image.fromarray(crop)
+
+    # Run Tesseract with specified PSM
+    config = f'--psm {psm} --oem 3'
+    try:
+        data = pytesseract.image_to_data(pil_img, lang=lang, config=config,
+                                         output_type=pytesseract.Output.DICT)
+    except Exception as e:
+        logger.warning(f"Tesseract failed for region {region.type}: {e}")
+        return []
+
+    words = []
+    for i in range(len(data['text'])):
+        text = data['text'][i].strip()
+        conf = int(data['conf'][i])
+        if not text or conf < 10:
+            continue
+        words.append({
+            'text': text,
+            'left': data['left'][i] + region.x,  # Absolute coords
+            'top': data['top'][i] + region.y,
+            'width': data['width'][i],
+            'height': data['height'][i],
+            'conf': conf,
+            'region_type': region.type,
+        })
+
+    # Check average confidence
+    if words and fallback_psm is not None:
+        avg_conf = sum(w['conf'] for w in words) / len(words)
+        if avg_conf < min_confidence:
+            logger.info(f"Region {region.type}: avg confidence {avg_conf:.0f}% < {min_confidence}%, "
+                        f"trying fallback PSM {fallback_psm}")
+            words = _ocr_region_line_by_line(ocr_img, region, lang, fallback_psm)
+
+    return words
+
+
+def _ocr_region_line_by_line(ocr_img: np.ndarray, region: PageRegion,
+                              lang: str, psm: int) -> List[Dict[str, Any]]:
+    """OCR a region line by line (fallback for low-confidence regions).
+
+    Splits the region into horizontal strips based on text density,
+    then OCRs each strip individually with the given PSM.
+    """
+    crop = ocr_img[region.y:region.y + region.height,
+                   region.x:region.x + region.width]
+
+    if crop.size == 0:
+        return []
+
+    # Find text lines via horizontal projection
+    inv = cv2.bitwise_not(crop)
+    h_proj = np.sum(inv, axis=1)
+    threshold = np.max(h_proj) * 0.05 if np.max(h_proj) > 0 else 0
+
+    # Find line boundaries
+    lines = []
+    in_text = False
+    line_start = 0
+    for y in range(len(h_proj)):
+        if h_proj[y] > threshold and not in_text:
+            line_start = y
+            in_text = True
+        elif h_proj[y] <= threshold and in_text:
+            if y - line_start > 5:  # Minimum line height
+                lines.append((line_start, y))
+            in_text = False
+    if in_text and len(h_proj) - line_start > 5:
+        lines.append((line_start, len(h_proj)))
+
+    all_words = []
+    config = f'--psm {psm} --oem 3'
+
+    for line_y_start, line_y_end in lines:
+        # Add small padding
+        pad = 3
+        y1 = max(0, line_y_start - pad)
+        y2 = min(crop.shape[0], line_y_end + pad)
+        line_crop = crop[y1:y2, :]
+
+        if line_crop.size == 0:
+            continue
+
+        pil_img = Image.fromarray(line_crop)
+        try:
+            data = pytesseract.image_to_data(pil_img, lang=lang, config=config,
+                                             output_type=pytesseract.Output.DICT)
+        except Exception:
+            continue
+
+        for i in range(len(data['text'])):
+            text = data['text'][i].strip()
+            conf = int(data['conf'][i])
+            if not text or conf < 10:
+                continue
+            all_words.append({
+                'text': text,
+                'left': data['left'][i] + region.x,
+                'top': data['top'][i] + region.y + y1,
+                'width': data['width'][i],
+                'height': data['height'][i],
+                'conf': conf,
+                'region_type': region.type,
+            })
+
+    return all_words
+
+
+def run_multi_pass_ocr(ocr_img: np.ndarray,
+                       regions: List[PageRegion],
+                       lang: str = "eng+deu") -> Dict[str, List[Dict]]:
+    """Run OCR on each detected region with optimized settings.
+
+    Args:
+        ocr_img: Binarized full-page image.
+        regions: Detected page regions.
+        lang: Default language.
+
+    Returns:
+        Dict mapping region type to list of word dicts.
+    """
+    results: Dict[str, List[Dict]] = {}
+
+    for region in regions:
+        if region.type == 'header' or region.type == 'footer':
+            continue  # Skip non-content regions
+
+        if region.type == 'column_en':
+            words = ocr_region(ocr_img, region, lang='eng', psm=4)
+        elif region.type == 'column_de':
+            words = ocr_region(ocr_img, region, lang='deu', psm=4)
+        elif region.type == 'column_example':
+            words = ocr_region(ocr_img, region, lang=lang, psm=6,
+                              fallback_psm=7, min_confidence=40.0)
+        else:
+            words = ocr_region(ocr_img, region, lang=lang, psm=6)
+
+        results[region.type] = words
+        logger.info(f"OCR {region.type}: {len(words)} words")
+
+    return results
+
+
+# =============================================================================
+# Stage 7: Line Alignment → Vocabulary Entries
+# =============================================================================
+
+def _group_words_into_lines(words: List[Dict], y_tolerance_px: int = 20) -> List[List[Dict]]:
+    """Group words by Y position into lines, sorted by X within each line."""
+    if not words:
+        return []
+
+    sorted_words = sorted(words, key=lambda w: (w['top'], w['left']))
+    lines: List[List[Dict]] = []
+    current_line: List[Dict] = [sorted_words[0]]
+    current_y = sorted_words[0]['top']
+
+    for word in sorted_words[1:]:
+        if abs(word['top'] - current_y) <= y_tolerance_px:
+            current_line.append(word)
+        else:
+            current_line.sort(key=lambda w: w['left'])
+            lines.append(current_line)
+            current_line = [word]
+            current_y = word['top']
+
+    if current_line:
+        current_line.sort(key=lambda w: w['left'])
+        lines.append(current_line)
+
+    return lines
+
+
+def match_lines_to_vocab(ocr_results: Dict[str, List[Dict]],
+                          regions: List[PageRegion],
+                          y_tolerance_px: int = 25) -> List[VocabRow]:
+    """Align OCR results from different columns into vocabulary rows.
+
+    Uses Y-coordinate matching to pair English words, German translations,
+    and example sentences that appear on the same line.
+
+    Args:
+        ocr_results: Dict mapping region type to word lists.
+        regions: Detected regions (for reference).
+        y_tolerance_px: Max Y-distance to consider words on the same row.
+
+    Returns:
+        List of VocabRow objects.
+    """
+    # Group words into lines per column
+    en_lines = _group_words_into_lines(ocr_results.get('column_en', []), y_tolerance_px)
+    de_lines = _group_words_into_lines(ocr_results.get('column_de', []), y_tolerance_px)
+    ex_lines = _group_words_into_lines(ocr_results.get('column_example', []), y_tolerance_px)
+
+    def line_y_center(line: List[Dict]) -> float:
+        return sum(w['top'] + w['height'] / 2 for w in line) / len(line)
+
+    def line_text(line: List[Dict]) -> str:
+        return ' '.join(w['text'] for w in line)
+
+    def line_confidence(line: List[Dict]) -> float:
+        return sum(w['conf'] for w in line) / len(line) if line else 0
+
+    # Build EN entries as the primary reference
+    vocab_rows: List[VocabRow] = []
+
+    for en_line in en_lines:
+        en_y = line_y_center(en_line)
+        en_text = line_text(en_line)
+        en_conf = line_confidence(en_line)
+
+        # Skip very short or likely header content
+        if len(en_text.strip()) < 2:
+            continue
+
+        # Find matching DE line
+        de_text = ""
+        de_conf = 0.0
+        best_de_dist = float('inf')
+        best_de_idx = -1
+        for idx, de_line in enumerate(de_lines):
+            dist = abs(line_y_center(de_line) - en_y)
+            if dist < y_tolerance_px and dist < best_de_dist:
+                best_de_dist = dist
+                best_de_idx = idx
+
+        if best_de_idx >= 0:
+            de_text = line_text(de_lines[best_de_idx])
+            de_conf = line_confidence(de_lines[best_de_idx])
+
+        # Find matching example line
+        ex_text = ""
+        ex_conf = 0.0
+        best_ex_dist = float('inf')
+        best_ex_idx = -1
+        for idx, ex_line in enumerate(ex_lines):
+            dist = abs(line_y_center(ex_line) - en_y)
+            if dist < y_tolerance_px and dist < best_ex_dist:
+                best_ex_dist = dist
+                best_ex_idx = idx
+
+        if best_ex_idx >= 0:
+            ex_text = line_text(ex_lines[best_ex_idx])
+            ex_conf = line_confidence(ex_lines[best_ex_idx])
+
+        avg_conf = en_conf
+        conf_count = 1
+        if de_conf > 0:
+            avg_conf += de_conf
+            conf_count += 1
+        if ex_conf > 0:
+            avg_conf += ex_conf
+            conf_count += 1
+
+        vocab_rows.append(VocabRow(
+            english=en_text.strip(),
+            german=de_text.strip(),
+            example=ex_text.strip(),
+            confidence=avg_conf / conf_count,
+            y_position=int(en_y),
+        ))
+
+    # Handle multi-line wrapping in example column:
+    # If an example line has no matching EN/DE, append to previous entry
+    matched_ex_ys = set()
+    for row in vocab_rows:
+        if row.example:
+            matched_ex_ys.add(row.y_position)
+
+    for ex_line in ex_lines:
+        ex_y = line_y_center(ex_line)
+        # Check if already matched
+        already_matched = any(abs(ex_y - y) < y_tolerance_px for y in matched_ex_ys)
+        if already_matched:
+            continue
+
+        # Find nearest previous vocab row
+        best_row = None
+        best_dist = float('inf')
+        for row in vocab_rows:
+            dist = ex_y - row.y_position
+            if 0 < dist < y_tolerance_px * 3 and dist < best_dist:
+                best_dist = dist
+                best_row = row
+
+        if best_row:
+            continuation = line_text(ex_line).strip()
+            if continuation:
+                best_row.example = (best_row.example + " " + continuation).strip()
+
+    # Sort by Y position
+    vocab_rows.sort(key=lambda r: r.y_position)
+
+    return vocab_rows
+
+
+# =============================================================================
+# Stage 8: Optional LLM Post-Correction
+# =============================================================================
+
+async def llm_post_correct(img: np.ndarray, vocab_rows: List[VocabRow],
+                           confidence_threshold: float = 50.0,
+                           enabled: bool = False) -> List[VocabRow]:
+    """Optionally send low-confidence regions to Qwen-VL for correction.
+
+    Default: disabled. Enable per parameter.
+
+    Args:
+        img: Original BGR image.
+        vocab_rows: Current vocabulary rows.
+        confidence_threshold: Rows below this get LLM correction.
+        enabled: Whether to actually run LLM correction.
+
+    Returns:
+        Corrected vocabulary rows.
+    """
+    if not enabled:
+        return vocab_rows
+
+    # TODO: Implement Qwen-VL correction for low-confidence entries
+    # For each row with confidence < threshold:
+    #   1. Crop the relevant region from img
+    #   2. Send crop + OCR text to Qwen-VL
+    #   3. Replace text if LLM provides a confident correction
+    logger.info(f"LLM post-correction skipped (not yet implemented)")
+    return vocab_rows
+
+
+# =============================================================================
+# Orchestrator
+# =============================================================================
+
+async def run_cv_pipeline(
+    pdf_data: Optional[bytes] = None,
+    image_data: Optional[bytes] = None,
+    page_number: int = 0,
+    zoom: float = 3.0,
+    enable_dewarp: bool = True,
+    enable_llm_correction: bool = False,
+    lang: str = "eng+deu",
+) -> PipelineResult:
+    """Run the complete CV document reconstruction pipeline.
+
+    Args:
+        pdf_data: Raw PDF bytes (mutually exclusive with image_data).
+        image_data: Raw image bytes (mutually exclusive with pdf_data).
+        page_number: 0-indexed page number (for PDF).
+        zoom: PDF rendering zoom factor.
+        enable_dewarp: Whether to run dewarp stage.
+        enable_llm_correction: Whether to run LLM post-correction.
+        lang: Tesseract language string.
+
+    Returns:
+        PipelineResult with vocabulary and timing info.
+    """
+    if not CV_PIPELINE_AVAILABLE:
+        return PipelineResult(error="CV pipeline not available (OpenCV or Tesseract missing)")
+
+    result = PipelineResult()
+    total_start = time.time()
+
+    try:
+        # Stage 1: Render
+        t = time.time()
+        if pdf_data:
+            img = render_pdf_high_res(pdf_data, page_number, zoom)
+        elif image_data:
+            img = render_image_high_res(image_data)
+        else:
+            return PipelineResult(error="No input data (pdf_data or image_data required)")
+        result.stages['render'] = round(time.time() - t, 2)
+        result.image_width = img.shape[1]
+        result.image_height = img.shape[0]
+        logger.info(f"Stage 1 (render): {img.shape[1]}x{img.shape[0]} in {result.stages['render']}s")
+
+        # Stage 2: Deskew
+        t = time.time()
+        img, angle = deskew_image(img)
+        result.stages['deskew'] = round(time.time() - t, 2)
+        logger.info(f"Stage 2 (deskew): {angle:.2f}° in {result.stages['deskew']}s")
+
+        # Stage 3: Dewarp
+        if enable_dewarp:
+            t = time.time()
+            img = dewarp_image(img)
+            result.stages['dewarp'] = round(time.time() - t, 2)
+
+        # Stage 4: Dual image preparation
+        t = time.time()
+        ocr_img = create_ocr_image(img)
+        layout_img = create_layout_image(img)
+        result.stages['image_prep'] = round(time.time() - t, 2)
+
+        # Stage 5: Layout analysis
+        t = time.time()
+        regions = analyze_layout(layout_img, ocr_img)
+        result.stages['layout'] = round(time.time() - t, 2)
+        result.columns_detected = len([r for r in regions if r.type.startswith('column')])
+        logger.info(f"Stage 5 (layout): {result.columns_detected} columns in {result.stages['layout']}s")
+
+        # Stage 6: Multi-pass OCR
+        t = time.time()
+        ocr_results = run_multi_pass_ocr(ocr_img, regions, lang)
+        result.stages['ocr'] = round(time.time() - t, 2)
+        total_words = sum(len(w) for w in ocr_results.values())
+        result.word_count = total_words
+        logger.info(f"Stage 6 (OCR): {total_words} words in {result.stages['ocr']}s")
+
+        # Stage 7: Line alignment
+        t = time.time()
+        vocab_rows = match_lines_to_vocab(ocr_results, regions)
+        result.stages['alignment'] = round(time.time() - t, 2)
+
+        # Stage 8: Optional LLM correction
+        if enable_llm_correction:
+            t = time.time()
+            vocab_rows = await llm_post_correct(img, vocab_rows)
+            result.stages['llm_correction'] = round(time.time() - t, 2)
+
+        # Convert to output format
+        result.vocabulary = [
+            {
+                "english": row.english,
+                "german": row.german,
+                "example": row.example,
+                "confidence": round(row.confidence, 1),
+            }
+            for row in vocab_rows
+            if row.english or row.german  # Skip empty rows
+        ]
+
+        result.duration_seconds = round(time.time() - total_start, 2)
+        logger.info(f"CV Pipeline complete: {len(result.vocabulary)} entries in {result.duration_seconds}s")
+
+    except Exception as e:
+        logger.error(f"CV Pipeline error: {e}")
+        import traceback
+        logger.debug(traceback.format_exc())
+        result.error = str(e)
+        result.duration_seconds = round(time.time() - total_start, 2)
+
+    return result
diff --git a/klausur-service/backend/tests/test_cv_vocab_pipeline.py b/klausur-service/backend/tests/test_cv_vocab_pipeline.py
new file mode 100644
index 0000000..a1c77f1
--- /dev/null
+++ b/klausur-service/backend/tests/test_cv_vocab_pipeline.py
@@ -0,0 +1,569 @@
+"""
+Unit Tests for CV Vocab Pipeline (cv_vocab_pipeline.py)
+
+Tests cover:
+- Data classes (PageRegion, VocabRow, PipelineResult)
+- Stage 2: Deskew image
+- Stage 3: Dewarp (pass-through)
+- Stage 4: Image preparation (OCR + Layout images)
+- Stage 5: Layout analysis (content bounds, projection profiles, column detection)
+- Stage 6: Multi-pass OCR region handling
+- Stage 7: Line grouping and vocabulary matching
+- Orchestrator (run_cv_pipeline)
+
+DSGVO Note: All tests run locally with synthetic data. No external API calls.
+"""
+
+import pytest
+import numpy as np
+from unittest.mock import AsyncMock, MagicMock, patch, PropertyMock
+from dataclasses import asdict
+
+# Import module under test
+from cv_vocab_pipeline import (
+    PageRegion,
+    VocabRow,
+    PipelineResult,
+    deskew_image,
+    dewarp_image,
+    create_ocr_image,
+    create_layout_image,
+    _find_content_bounds,
+    analyze_layout,
+    _group_words_into_lines,
+    match_lines_to_vocab,
+    run_cv_pipeline,
+    CV2_AVAILABLE,
+    TESSERACT_AVAILABLE,
+    CV_PIPELINE_AVAILABLE,
+)
+
+
+# =============================================
+# FIXTURES
+# =============================================
+
+@pytest.fixture
+def white_image():
+    """Create a simple 300x200 white BGR image."""
+    return np.ones((200, 300, 3), dtype=np.uint8) * 255
+
+
+@pytest.fixture
+def text_like_image():
+    """Create a 600x400 image with dark text-like regions simulating 3 columns."""
+    img = np.ones((400, 600, 3), dtype=np.uint8) * 255
+
+    # Column 1 (EN): x=20..170
+    for y in range(50, 350, 30):
+        img[y:y+15, 30:160, :] = 30  # Dark text lines
+
+    # Gap between col1 and col2: x=170..210 (white)
+
+    # Column 2 (DE): x=210..370
+    for y in range(50, 350, 30):
+        img[y:y+15, 220:360, :] = 30
+
+    # Gap between col2 and col3: x=370..410 (white)
+
+    # Column 3 (Example): x=410..580
+    for y in range(50, 350, 30):
+        img[y:y+15, 420:570, :] = 30
+
+    return img
+
+
+@pytest.fixture
+def binary_image():
+    """Create a binary (single-channel) image for OCR tests."""
+    # White background (255) with some black text-like areas
+    img = np.ones((400, 600), dtype=np.uint8) * 255
+    # Add text-like dark bands
+    for y in range(50, 350, 30):
+        img[y:y+15, 30:570] = 0
+    return img
+
+
+@pytest.fixture
+def sample_words_column_en():
+    """Sample OCR word dicts for English column."""
+    return [
+        {'text': 'achieve', 'left': 30, 'top': 50, 'width': 80, 'height': 15, 'conf': 90, 'region_type': 'column_en'},
+        {'text': 'improve', 'left': 30, 'top': 80, 'width': 80, 'height': 15, 'conf': 85, 'region_type': 'column_en'},
+        {'text': 'success', 'left': 30, 'top': 110, 'width': 80, 'height': 15, 'conf': 92, 'region_type': 'column_en'},
+    ]
+
+
+@pytest.fixture
+def sample_words_column_de():
+    """Sample OCR word dicts for German column."""
+    return [
+        {'text': 'erreichen', 'left': 220, 'top': 52, 'width': 100, 'height': 15, 'conf': 88, 'region_type': 'column_de'},
+        {'text': 'verbessern', 'left': 220, 'top': 82, 'width': 100, 'height': 15, 'conf': 80, 'region_type': 'column_de'},
+        {'text': 'Erfolg', 'left': 220, 'top': 112, 'width': 100, 'height': 15, 'conf': 95, 'region_type': 'column_de'},
+    ]
+
+
+@pytest.fixture
+def sample_words_column_ex():
+    """Sample OCR word dicts for Example column."""
+    return [
+        {'text': 'She', 'left': 420, 'top': 50, 'width': 30, 'height': 15, 'conf': 85, 'region_type': 'column_example'},
+        {'text': 'achieved', 'left': 455, 'top': 50, 'width': 70, 'height': 15, 'conf': 80, 'region_type': 'column_example'},
+        {'text': 'her', 'left': 530, 'top': 50, 'width': 30, 'height': 15, 'conf': 90, 'region_type': 'column_example'},
+        {'text': 'goals.', 'left': 420, 'top': 52, 'width': 50, 'height': 15, 'conf': 75, 'region_type': 'column_example'},
+    ]
+
+
+@pytest.fixture
+def sample_regions():
+    """Sample 3-column PageRegion layout."""
+    return [
+        PageRegion(type='column_en', x=0, y=50, width=190, height=300),
+        PageRegion(type='column_de', x=210, y=50, width=160, height=300),
+        PageRegion(type='column_example', x=410, y=50, width=190, height=300),
+    ]
+
+
+# =============================================
+# DATA CLASS TESTS
+# =============================================
+
+class TestDataClasses:
+    """Test data classes for correct defaults and fields."""
+
+    def test_page_region_creation(self):
+        region = PageRegion(type='column_en', x=10, y=20, width=100, height=200)
+        assert region.type == 'column_en'
+        assert region.x == 10
+        assert region.y == 20
+        assert region.width == 100
+        assert region.height == 200
+
+    def test_vocab_row_defaults(self):
+        row = VocabRow()
+        assert row.english == ""
+        assert row.german == ""
+        assert row.example == ""
+        assert row.confidence == 0.0
+        assert row.y_position == 0
+
+    def test_vocab_row_with_values(self):
+        row = VocabRow(english="test", german="Test", example="A test.", confidence=85.5, y_position=100)
+        assert row.english == "test"
+        assert row.german == "Test"
+        assert row.confidence == 85.5
+
+    def test_pipeline_result_defaults(self):
+        result = PipelineResult()
+        assert result.vocabulary == []
+        assert result.word_count == 0
+        assert result.columns_detected == 0
+        assert result.duration_seconds == 0.0
+        assert result.stages == {}
+        assert result.error is None
+
+    def test_pipeline_result_error(self):
+        result = PipelineResult(error="Something went wrong")
+        assert result.error == "Something went wrong"
+
+
+# =============================================
+# STAGE 2: DESKEW TESTS
+# =============================================
+
+@pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+class TestDeskew:
+    """Test deskew (rotation correction) stage."""
+
+    def test_deskew_straight_image(self, white_image):
+        """A perfectly straight image should not be rotated."""
+        corrected, angle = deskew_image(white_image)
+        assert abs(angle) < 0.1
+        assert corrected.shape == white_image.shape
+
+    def test_deskew_returns_tuple(self, white_image):
+        """deskew_image must return (image, angle) tuple."""
+        result = deskew_image(white_image)
+        assert isinstance(result, tuple)
+        assert len(result) == 2
+        assert isinstance(result[0], np.ndarray)
+        assert isinstance(result[1], float)
+
+    def test_deskew_preserves_shape(self, text_like_image):
+        """Output image should have same shape as input."""
+        corrected, _ = deskew_image(text_like_image)
+        assert corrected.shape == text_like_image.shape
+
+
+# =============================================
+# STAGE 3: DEWARP TESTS
+# =============================================
+
+@pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+class TestDewarp:
+    """Test dewarp (pass-through) stage."""
+
+    def test_dewarp_passthrough(self, white_image):
+        """Current dewarp should return the same image (pass-through)."""
+        result = dewarp_image(white_image)
+        np.testing.assert_array_equal(result, white_image)
+
+    def test_dewarp_preserves_shape(self, text_like_image):
+        result = dewarp_image(text_like_image)
+        assert result.shape == text_like_image.shape
+
+
+# =============================================
+# STAGE 4: IMAGE PREPARATION TESTS
+# =============================================
+
+@pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+class TestImagePreparation:
+    """Test OCR and layout image creation."""
+
+    def test_create_ocr_image_returns_grayscale(self, text_like_image):
+        """OCR image should be single-channel (binarized)."""
+        ocr_img = create_ocr_image(text_like_image)
+        assert len(ocr_img.shape) == 2  # Single channel
+        assert ocr_img.dtype == np.uint8
+
+    def test_create_ocr_image_is_binary(self, text_like_image):
+        """OCR image should contain only 0 and 255 values."""
+        ocr_img = create_ocr_image(text_like_image)
+        unique_vals = np.unique(ocr_img)
+        assert all(v in [0, 255] for v in unique_vals)
+
+    def test_create_layout_image_returns_grayscale(self, text_like_image):
+        """Layout image should be single-channel (CLAHE enhanced)."""
+        layout_img = create_layout_image(text_like_image)
+        assert len(layout_img.shape) == 2
+        assert layout_img.dtype == np.uint8
+
+    def test_create_layout_image_enhanced_contrast(self, text_like_image):
+        """Layout image should have different histogram than simple grayscale."""
+        import cv2
+        gray = cv2.cvtColor(text_like_image, cv2.COLOR_BGR2GRAY)
+        layout_img = create_layout_image(text_like_image)
+        # CLAHE should change the histogram
+        assert layout_img.shape == gray.shape
+
+
+# =============================================
+# STAGE 5: LAYOUT ANALYSIS TESTS
+# =============================================
+
+@pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+class TestContentBounds:
+    """Test _find_content_bounds helper."""
+
+    def test_empty_image(self):
+        """Fully white (inverted = black) image should return full bounds."""
+        inv = np.zeros((200, 300), dtype=np.uint8)
+        left, right, top, bottom = _find_content_bounds(inv)
+        # With no content, bounds should span the image
+        assert left >= 0
+        assert right <= 300
+        assert top >= 0
+        assert bottom <= 200
+
+    def test_centered_content(self):
+        """Content in center should give tight bounds."""
+        inv = np.zeros((400, 600), dtype=np.uint8)
+        # Add content block in center
+        inv[100:300, 50:550] = 255
+        left, right, top, bottom = _find_content_bounds(inv)
+        assert left <= 52   # ~50 with 2px margin
+        assert right >= 548  # ~550 with 2px margin
+        assert top <= 102
+        assert bottom >= 298
+
+
+@pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+class TestLayoutAnalysis:
+    """Test analyze_layout for column detection."""
+
+    def test_returns_list_of_regions(self, text_like_image):
+        """analyze_layout should return a list of PageRegion."""
+        ocr_img = create_ocr_image(text_like_image)
+        layout_img = create_layout_image(text_like_image)
+        regions = analyze_layout(layout_img, ocr_img)
+        assert isinstance(regions, list)
+        assert all(isinstance(r, PageRegion) for r in regions)
+
+    def test_detects_columns(self, text_like_image):
+        """With clear 3-column image, should detect at least 1 column."""
+        ocr_img = create_ocr_image(text_like_image)
+        layout_img = create_layout_image(text_like_image)
+        regions = analyze_layout(layout_img, ocr_img)
+        column_regions = [r for r in regions if r.type.startswith('column')]
+        assert len(column_regions) >= 1
+
+    def test_single_column_fallback(self):
+        """Image with no clear columns should fall back to single column."""
+        # Uniform text across full width
+        img = np.ones((400, 600, 3), dtype=np.uint8) * 255
+        for y in range(50, 350, 20):
+            img[y:y+10, 20:580, :] = 30  # Full-width text
+        ocr_img = create_ocr_image(img)
+        layout_img = create_layout_image(img)
+        regions = analyze_layout(layout_img, ocr_img)
+        column_regions = [r for r in regions if r.type.startswith('column')]
+        # Should at least return 1 column (full page fallback)
+        assert len(column_regions) >= 1
+
+    def test_region_types_are_valid(self, text_like_image):
+        """All region types should be from the expected set."""
+        ocr_img = create_ocr_image(text_like_image)
+        layout_img = create_layout_image(text_like_image)
+        regions = analyze_layout(layout_img, ocr_img)
+        valid_types = {'column_en', 'column_de', 'column_example', 'header', 'footer'}
+        for r in regions:
+            assert r.type in valid_types, f"Unexpected region type: {r.type}"
+
+
+# =============================================
+# STAGE 7: LINE GROUPING TESTS
+# =============================================
+
+class TestLineGrouping:
+    """Test _group_words_into_lines function."""
+
+    def test_empty_input(self):
+        """Empty word list should return empty lines."""
+        assert _group_words_into_lines([]) == []
+
+    def test_single_word(self):
+        """Single word should return one line with one word."""
+        words = [{'text': 'hello', 'left': 10, 'top': 50, 'width': 50, 'height': 15, 'conf': 90}]
+        lines = _group_words_into_lines(words)
+        assert len(lines) == 1
+        assert len(lines[0]) == 1
+        assert lines[0][0]['text'] == 'hello'
+
+    def test_words_on_same_line(self):
+        """Words close in Y should be grouped into one line."""
+        words = [
+            {'text': 'hello', 'left': 10, 'top': 50, 'width': 50, 'height': 15, 'conf': 90},
+            {'text': 'world', 'left': 70, 'top': 52, 'width': 50, 'height': 15, 'conf': 85},
+        ]
+        lines = _group_words_into_lines(words, y_tolerance_px=10)
+        assert len(lines) == 1
+        assert len(lines[0]) == 2
+
+    def test_words_on_different_lines(self):
+        """Words far apart in Y should be on different lines."""
+        words = [
+            {'text': 'line1', 'left': 10, 'top': 50, 'width': 50, 'height': 15, 'conf': 90},
+            {'text': 'line2', 'left': 10, 'top': 100, 'width': 50, 'height': 15, 'conf': 85},
+            {'text': 'line3', 'left': 10, 'top': 150, 'width': 50, 'height': 15, 'conf': 88},
+        ]
+        lines = _group_words_into_lines(words, y_tolerance_px=20)
+        assert len(lines) == 3
+
+    def test_words_sorted_by_x_within_line(self):
+        """Words within a line should be sorted by X position."""
+        words = [
+            {'text': 'world', 'left': 100, 'top': 50, 'width': 50, 'height': 15, 'conf': 85},
+            {'text': 'hello', 'left': 10, 'top': 52, 'width': 50, 'height': 15, 'conf': 90},
+        ]
+        lines = _group_words_into_lines(words, y_tolerance_px=10)
+        assert len(lines) == 1
+        assert lines[0][0]['text'] == 'hello'
+        assert lines[0][1]['text'] == 'world'
+
+
+# =============================================
+# STAGE 7: VOCABULARY MATCHING TESTS
+# =============================================
+
+class TestVocabMatching:
+    """Test match_lines_to_vocab function."""
+
+    def test_empty_results(self, sample_regions):
+        """Empty OCR results should return empty vocab."""
+        vocab = match_lines_to_vocab({}, sample_regions)
+        assert vocab == []
+
+    def test_en_only(self, sample_words_column_en, sample_regions):
+        """Only EN words should create entries with empty DE/example."""
+        ocr_results = {'column_en': sample_words_column_en}
+        vocab = match_lines_to_vocab(ocr_results, sample_regions)
+        assert len(vocab) == 3
+        for row in vocab:
+            assert row.english != ""
+            assert row.german == ""
+
+    def test_en_de_matching(self, sample_words_column_en, sample_words_column_de, sample_regions):
+        """EN and DE words on same Y should be matched."""
+        ocr_results = {
+            'column_en': sample_words_column_en,
+            'column_de': sample_words_column_de,
+        }
+        vocab = match_lines_to_vocab(ocr_results, sample_regions, y_tolerance_px=25)
+        assert len(vocab) == 3
+        # First entry should match achieve <-> erreichen
+        assert vocab[0].english == 'achieve'
+        assert vocab[0].german == 'erreichen'
+
+    def test_full_3_column_matching(self, sample_words_column_en, sample_words_column_de,
+                                      sample_words_column_ex, sample_regions):
+        """All 3 columns should be matched by Y coordinate."""
+        ocr_results = {
+            'column_en': sample_words_column_en,
+            'column_de': sample_words_column_de,
+            'column_example': sample_words_column_ex,
+        }
+        vocab = match_lines_to_vocab(ocr_results, sample_regions, y_tolerance_px=25)
+        assert len(vocab) >= 1
+        # First entry should have example text
+        assert vocab[0].english == 'achieve'
+        assert vocab[0].example != ""
+
+    def test_sorted_by_y_position(self, sample_words_column_en, sample_regions):
+        """Result should be sorted by Y position."""
+        ocr_results = {'column_en': sample_words_column_en}
+        vocab = match_lines_to_vocab(ocr_results, sample_regions)
+        positions = [row.y_position for row in vocab]
+        assert positions == sorted(positions)
+
+    def test_skips_short_entries(self, sample_regions):
+        """Very short text (< 2 chars) should be skipped."""
+        words = [
+            {'text': 'a', 'left': 30, 'top': 50, 'width': 10, 'height': 15, 'conf': 90, 'region_type': 'column_en'},
+            {'text': 'valid', 'left': 30, 'top': 80, 'width': 50, 'height': 15, 'conf': 90, 'region_type': 'column_en'},
+        ]
+        ocr_results = {'column_en': words}
+        vocab = match_lines_to_vocab(ocr_results, sample_regions)
+        assert len(vocab) == 1
+        assert vocab[0].english == 'valid'
+
+    def test_confidence_calculation(self, sample_words_column_en, sample_words_column_de, sample_regions):
+        """Confidence should be the average of matched columns."""
+        ocr_results = {
+            'column_en': sample_words_column_en,
+            'column_de': sample_words_column_de,
+        }
+        vocab = match_lines_to_vocab(ocr_results, sample_regions, y_tolerance_px=25)
+        # First entry: EN conf=90, DE conf=88 → avg=89
+        assert vocab[0].confidence > 0
+        assert vocab[0].confidence == pytest.approx(89.0, abs=1.0)
+
+
+# =============================================
+# ORCHESTRATOR TESTS
+# =============================================
+
+class TestOrchestrator:
+    """Test run_cv_pipeline orchestrator."""
+
+    @pytest.mark.asyncio
+    async def test_no_input_returns_error(self):
+        """Pipeline without input should return error."""
+        result = await run_cv_pipeline()
+        assert result.error is not None
+        assert "No input data" in result.error
+
+    @pytest.mark.asyncio
+    async def test_pipeline_unavailable(self):
+        """When CV_PIPELINE_AVAILABLE is False, should return error."""
+        with patch('cv_vocab_pipeline.CV_PIPELINE_AVAILABLE', False):
+            result = await run_cv_pipeline(pdf_data=b"fake")
+            assert result.error is not None
+            assert "not available" in result.error
+
+    @pytest.mark.asyncio
+    @pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+    async def test_pipeline_with_image_data(self):
+        """Pipeline with a real synthetic image should run without errors."""
+        import cv2
+        # Create a simple test image (white with some text-like black bars)
+        img = np.ones((200, 300, 3), dtype=np.uint8) * 255
+        for y in range(30, 170, 25):
+            img[y:y+12, 20:280, :] = 30
+        _, img_bytes = cv2.imencode('.png', img)
+        image_data = img_bytes.tobytes()
+
+        with patch('cv_vocab_pipeline.pytesseract') as mock_tess:
+            # Mock Tesseract to return empty results
+            mock_tess.image_to_data.return_value = {
+                'text': [], 'conf': [], 'left': [], 'top': [],
+                'width': [], 'height': [],
+            }
+            mock_tess.Output.DICT = 'dict'
+
+            result = await run_cv_pipeline(image_data=image_data)
+            assert result.error is None
+            assert result.image_width == 300
+            assert result.image_height == 200
+            assert 'render' in result.stages
+            assert 'deskew' in result.stages
+
+    @pytest.mark.asyncio
+    @pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+    async def test_pipeline_records_timing(self):
+        """Pipeline should record timing for each stage."""
+        import cv2
+        img = np.ones((100, 150, 3), dtype=np.uint8) * 255
+        _, img_bytes = cv2.imencode('.png', img)
+
+        with patch('cv_vocab_pipeline.pytesseract') as mock_tess:
+            mock_tess.image_to_data.return_value = {
+                'text': [], 'conf': [], 'left': [], 'top': [],
+                'width': [], 'height': [],
+            }
+            mock_tess.Output.DICT = 'dict'
+
+            result = await run_cv_pipeline(image_data=img_bytes.tobytes())
+            assert result.duration_seconds >= 0
+            assert all(v >= 0 for v in result.stages.values())
+
+    @pytest.mark.asyncio
+    async def test_pipeline_result_format(self):
+        """PipelineResult vocabulary should be list of dicts with expected keys."""
+        result = PipelineResult()
+        result.vocabulary = [
+            {"english": "test", "german": "Test", "example": "A test.", "confidence": 90.0}
+        ]
+        assert len(result.vocabulary) == 1
+        entry = result.vocabulary[0]
+        assert "english" in entry
+        assert "german" in entry
+        assert "example" in entry
+        assert "confidence" in entry
+
+
+# =============================================
+# INTEGRATION-STYLE TESTS (with mocked Tesseract)
+# =============================================
+
+@pytest.mark.skipif(not CV2_AVAILABLE, reason="OpenCV not available")
+class TestStageIntegration:
+    """Test multiple stages together (still unit-test level with mocked OCR)."""
+
+    def test_image_prep_to_layout(self, text_like_image):
+        """Stages 4→5: image prep feeds layout analysis correctly."""
+        ocr_img = create_ocr_image(text_like_image)
+        layout_img = create_layout_image(text_like_image)
+
+        assert ocr_img.shape[:2] == text_like_image.shape[:2]
+        assert layout_img.shape[:2] == text_like_image.shape[:2]
+
+        regions = analyze_layout(layout_img, ocr_img)
+        assert len(regions) >= 1
+
+    def test_deskew_to_image_prep(self, text_like_image):
+        """Stages 2→4: deskew output can be processed by image prep."""
+        corrected, angle = deskew_image(text_like_image)
+        ocr_img = create_ocr_image(corrected)
+        layout_img = create_layout_image(corrected)
+        assert ocr_img.shape[:2] == corrected.shape[:2]
+        assert layout_img.shape[:2] == corrected.shape[:2]
+
+
+# =============================================
+# RUN TESTS
+# =============================================
+
+if __name__ == "__main__":
+    pytest.main([__file__, "-v"])
diff --git a/klausur-service/backend/vocab_worksheet_api.py b/klausur-service/backend/vocab_worksheet_api.py
index 1ff13ef..f0ce3fe 100644
--- a/klausur-service/backend/vocab_worksheet_api.py
+++ b/klausur-service/backend/vocab_worksheet_api.py
@@ -42,6 +42,93 @@ except ImportError:
     MINIO_AVAILABLE = False
     logger.warning("MinIO storage not available, using local storage")
 
+# Try to import Tesseract extractor
+try:
+    from tesseract_vocab_extractor import (
+        extract_bounding_boxes, run_tesseract_pipeline,
+        match_positions_to_vocab, TESSERACT_AVAILABLE,
+    )
+except ImportError:
+    TESSERACT_AVAILABLE = False
+    logger.warning("Tesseract extractor not available")
+
+# Try to import CV Pipeline
+try:
+    from cv_vocab_pipeline import run_cv_pipeline, CV_PIPELINE_AVAILABLE
+except ImportError:
+    CV_PIPELINE_AVAILABLE = False
+    logger.warning("CV vocab pipeline not available")
+
+# Try to import Grid Detection Service
+try:
+    from services.grid_detection_service import GridDetectionService
+    GRID_SERVICE_AVAILABLE = True
+except ImportError:
+    GRID_SERVICE_AVAILABLE = False
+    logger.warning("Grid Detection Service not available")
+
+# Database integration (used by main.py lifespan)
+try:
+    from vocab_session_store import (
+        DATABASE_URL, get_pool, init_vocab_tables,
+        list_sessions_db, get_session_db,
+    )
+except ImportError:
+    DATABASE_URL = os.getenv("DATABASE_URL", "postgresql://breakpilot:breakpilot@postgres:5432/breakpilot_db")
+    get_pool = None
+    init_vocab_tables = None
+    list_sessions_db = None
+    get_session_db = None
+
+_db_pool = None
+
+
+def set_db_pool(pool):
+    """Set the database connection pool (called from main.py lifespan)."""
+    global _db_pool
+    _db_pool = pool
+
+
+async def _init_vocab_table():
+    """Initialize vocab tables in database."""
+    if init_vocab_tables:
+        try:
+            await init_vocab_tables()
+            logger.info("vocab_session_cache table ready")
+        except Exception as e:
+            logger.warning(f"Failed to init vocab tables: {e}")
+    else:
+        logger.info("vocab_session_cache table ready")
+
+
+async def _load_all_sessions():
+    """Load all vocab sessions from database into memory cache."""
+    if not list_sessions_db:
+        logger.info("Loaded 0 vocab sessions from database")
+        return
+
+    try:
+        sessions = await list_sessions_db(limit=500)
+        count = 0
+        for s in sessions:
+            sid = s.get("id") or s.get("session_id")
+            if sid and sid not in _sessions:
+                _sessions[sid] = {
+                    "id": sid,
+                    "name": s.get("name", ""),
+                    "description": s.get("description", ""),
+                    "status": s.get("status", "created"),
+                    "vocabulary_count": s.get("vocabulary_count", 0),
+                    "source_language": s.get("source_language", "en"),
+                    "target_language": s.get("target_language", "de"),
+                    "created_at": str(s.get("created_at", "")),
+                }
+                count += 1
+        logger.info(f"Loaded {count} vocab sessions from database")
+    except Exception as e:
+        logger.warning(f"Failed to load sessions from database: {e}")
+
+
 router = APIRouter(prefix="/api/v1/vocab", tags=["Vocabulary Worksheets"])
 
 # Local storage path
@@ -786,7 +873,7 @@ async def upload_image(
     # Convert PDF to image if needed
     if is_pdf:
         logger.info("Converting PDF to image...")
-        content = await convert_pdf_to_image(content)
+        content = await convert_pdf_page_to_image(content, page_number=0)
         logger.info(f"PDF converted, image size: {len(content)} bytes")
 
     # Save image
@@ -1066,8 +1153,12 @@ async def upload_pdf_get_info(
 
 
 @router.get("/sessions/{session_id}/pdf-thumbnail/{page_number}")
-async def get_pdf_thumbnail(session_id: str, page_number: int):
-    """Get a thumbnail image of a specific PDF page."""
+async def get_pdf_thumbnail(session_id: str, page_number: int, hires: bool = Query(False)):
+    """Get a thumbnail image of a specific PDF page.
+
+    Args:
+        hires: If True, return full-resolution image (zoom=2.0) instead of thumbnail (zoom=0.5).
+    """
     if session_id not in _sessions:
         raise HTTPException(status_code=404, detail="Session not found")
 
@@ -1077,7 +1168,7 @@ async def get_pdf_thumbnail(session_id: str, page_number: int):
     if not pdf_data:
         raise HTTPException(status_code=400, detail="No PDF uploaded for this session")
 
-    thumbnail = await convert_pdf_page_to_image(pdf_data, page_number, thumbnail=True)
+    thumbnail = await convert_pdf_page_to_image(pdf_data, page_number, thumbnail=not hires)
 
     return StreamingResponse(
         io.BytesIO(thumbnail),
@@ -1085,6 +1176,45 @@ async def get_pdf_thumbnail(session_id: str, page_number: int):
     )
 
 
+@router.get("/sessions/{session_id}/pdf-page-image/{page_number}")
+async def get_pdf_page_image(session_id: str, page_number: int, zoom: float = Query(2.0, ge=0.5, le=4.0)):
+    """PDF page as PNG at arbitrary resolution (for editor view).
+
+    Args:
+        zoom: Zoom factor (0.5=72DPI, 1.0=144DPI, 2.0=288DPI, 4.0=576DPI).
+    """
+    if session_id not in _sessions:
+        raise HTTPException(status_code=404, detail="Session not found")
+
+    session = _sessions[session_id]
+    pdf_data = session.get("pdf_data")
+
+    if not pdf_data:
+        raise HTTPException(status_code=400, detail="No PDF uploaded for this session")
+
+    page_count = session.get("pdf_page_count", 1)
+    if page_number < 0 or page_number >= page_count:
+        raise HTTPException(status_code=400, detail=f"Invalid page number. PDF has {page_count} pages (0-indexed).")
+
+    try:
+        import fitz
+        pdf_document = fitz.open(stream=pdf_data, filetype="pdf")
+        page = pdf_document[page_number]
+        mat = fitz.Matrix(zoom, zoom)
+        pix = page.get_pixmap(matrix=mat)
+        png_data = pix.tobytes("png")
+        pdf_document.close()
+        logger.info(f"PDF page {page_number} rendered at zoom={zoom}: {len(png_data)} bytes")
+    except Exception as e:
+        logger.error(f"PDF page image failed: {e}")
+        raise HTTPException(status_code=500, detail=f"PDF rendering failed: {str(e)}")
+
+    return StreamingResponse(
+        io.BytesIO(png_data),
+        media_type="image/png",
+    )
+
+
 @router.post("/sessions/{session_id}/process-single-page/{page_number}")
 async def process_single_page(
     session_id: str,
@@ -1436,9 +1566,122 @@ async def compare_ocr_methods(session_id: str, page_number: int):
         }
         all_vocab_sets["vision_llm"] = set()
 
-    # --- Method: Local LLM (same as vision but noted separately if available) ---
-    # For now, we treat vision_llm as the primary method.
-    # Tesseract method can be added here if tesseract_vocab_extractor is available.
+    # --- Method: Tesseract OCR (bounding boxes + vocab extraction) ---
+    if TESSERACT_AVAILABLE:
+        try:
+            start = time.time()
+            tess_result = await run_tesseract_pipeline(image_data, lang="eng+deu")
+            duration = time.time() - start
+
+            tess_vocab = tess_result.get("vocabulary", [])
+            tess_words = tess_result.get("words", [])
+
+            # Store Tesseract words in session for later use (grid analysis, position matching)
+            session["tesseract_words"] = tess_words
+            session["tesseract_image_width"] = tess_result.get("image_width", 0)
+            session["tesseract_image_height"] = tess_result.get("image_height", 0)
+            session[f"tesseract_page_{page_number}"] = tess_result
+
+            vocab_list_tess = []
+            for v in tess_vocab:
+                vocab_list_tess.append({
+                    "english": v.get("english", ""),
+                    "german": v.get("german", ""),
+                    "example": v.get("example", ""),
+                })
+
+            methods_results["tesseract"] = {
+                "name": "Tesseract OCR",
+                "model": "tesseract-ocr (eng+deu)",
+                "duration_seconds": round(duration, 1),
+                "vocabulary_count": len(vocab_list_tess),
+                "vocabulary": vocab_list_tess,
+                "confidence": 0.7 if tess_vocab else 0,
+                "success": len(vocab_list_tess) > 0,
+                "error": tess_result.get("error"),
+                "word_count": tess_result.get("word_count", 0),
+                "columns_detected": len(tess_result.get("columns", [])),
+            }
+            all_vocab_sets["tesseract"] = {
+                (v["english"].lower().strip(), v["german"].lower().strip())
+                for v in vocab_list_tess if v["english"] and v["german"]
+            }
+
+            # Fuzzy-match: attach Tesseract bounding boxes to Vision LLM results
+            if "vision_llm" in methods_results and methods_results["vision_llm"]["success"]:
+                llm_vocab_with_bbox = match_positions_to_vocab(
+                    tess_words,
+                    methods_results["vision_llm"]["vocabulary"],
+                    tess_result.get("image_width", 1),
+                    tess_result.get("image_height", 1),
+                )
+                methods_results["vision_llm"]["vocabulary"] = llm_vocab_with_bbox
+
+        except Exception as e:
+            logger.error(f"Tesseract failed: {e}")
+            import traceback
+            logger.debug(traceback.format_exc())
+            methods_results["tesseract"] = {
+                "name": "Tesseract OCR",
+                "model": "tesseract-ocr",
+                "duration_seconds": 0,
+                "vocabulary_count": 0,
+                "vocabulary": [],
+                "confidence": 0,
+                "success": False,
+                "error": str(e),
+            }
+            all_vocab_sets["tesseract"] = set()
+
+    # --- Method: CV Pipeline (Document Reconstruction) ---
+    if CV_PIPELINE_AVAILABLE:
+        try:
+            start = time.time()
+            cv_result = await run_cv_pipeline(pdf_data=pdf_data, page_number=page_number)
+            duration = time.time() - start
+
+            cv_vocab = cv_result.vocabulary if not cv_result.error else []
+            vocab_list_cv = []
+            for v in cv_vocab:
+                vocab_list_cv.append({
+                    "english": v.get("english", ""),
+                    "german": v.get("german", ""),
+                    "example": v.get("example", ""),
+                })
+
+            methods_results["cv_pipeline"] = {
+                "name": "CV Pipeline (Document Reconstruction)",
+                "model": "opencv + tesseract (multi-pass)",
+                "duration_seconds": round(duration, 1),
+                "vocabulary_count": len(vocab_list_cv),
+                "vocabulary": vocab_list_cv,
+                "confidence": 0.8 if cv_vocab else 0,
+                "success": len(vocab_list_cv) > 0,
+                "error": cv_result.error,
+                "word_count": cv_result.word_count,
+                "columns_detected": cv_result.columns_detected,
+                "stages": cv_result.stages,
+            }
+            all_vocab_sets["cv_pipeline"] = {
+                (v["english"].lower().strip(), v["german"].lower().strip())
+                for v in vocab_list_cv if v["english"] and v["german"]
+            }
+
+        except Exception as e:
+            logger.error(f"CV Pipeline failed: {e}")
+            import traceback
+            logger.debug(traceback.format_exc())
+            methods_results["cv_pipeline"] = {
+                "name": "CV Pipeline (Document Reconstruction)",
+                "model": "opencv + tesseract (multi-pass)",
+                "duration_seconds": 0,
+                "vocabulary_count": 0,
+                "vocabulary": [],
+                "confidence": 0,
+                "success": False,
+                "error": str(e),
+            }
+            all_vocab_sets["cv_pipeline"] = set()
 
     # --- Build comparison ---
     all_unique = set()
@@ -1461,11 +1704,6 @@ async def compare_ocr_methods(session_id: str, page_number: int):
     # Find best method
     best_method = max(all_vocab_sets, key=lambda m: len(all_vocab_sets[m])) if all_vocab_sets else "vision_llm"
 
-    # Save vocabulary from best method in session for grid analysis (no second Ollama call needed)
-    best_vocab_list = methods_results.get(best_method, {}).get("vocabulary", [])
-    session["comparison_vocabulary"] = best_vocab_list
-    session["comparison_page"] = page_number
-
     return {
         "session_id": session_id,
         "page_number": page_number,
@@ -1484,67 +1722,208 @@ async def compare_ocr_methods(session_id: str, page_number: int):
 
 
 @router.post("/sessions/{session_id}/analyze-grid/{page_number}")
-async def analyze_grid(session_id: str, page_number: int):
+async def analyze_grid(session_id: str, page_number: int, use_tesseract: bool = Query(True)):
     """
-    Build grid structure from comparison results (no Ollama call needed).
+    Analyze the grid/table structure of a vocabulary page.
 
-    Uses vocabulary stored in session by compare-ocr to compute
-    the grid layout instantly.
+    Hybrid approach:
+    1. If Tesseract bounding boxes are available (from compare-ocr), use them for
+       real spatial positions via GridDetectionService.
+    2. Otherwise fall back to Vision LLM for grid structure detection.
 
     page_number is 0-indexed.
     Returns GridData structure expected by the frontend GridOverlay component.
     """
-    logger.info(f"Grid analysis for session {session_id}, page {page_number}")
+    import httpx
+    import time
+
+    logger.info(f"Grid analysis for session {session_id}, page {page_number} (use_tesseract={use_tesseract})")
 
     if session_id not in _sessions:
         raise HTTPException(status_code=404, detail="Session not found")
 
     session = _sessions[session_id]
+    pdf_data = session.get("pdf_data")
 
-    # Read vocabulary from session (saved by compare-ocr)
-    vocab_list = session.get("comparison_vocabulary")
-    if not vocab_list:
-        return {"success": False, "error": "Bitte zuerst Vergleich starten, bevor die Grid-Analyse ausgefuehrt wird."}
+    if not pdf_data:
+        raise HTTPException(status_code=400, detail="No PDF uploaded for this session")
+
+    page_count = session.get("pdf_page_count", 1)
+    if page_number < 0 or page_number >= page_count:
+        raise HTTPException(status_code=400, detail=f"Invalid page number.")
+
+    # Convert page to image
+    image_data = await convert_pdf_page_to_image(pdf_data, page_number, thumbnail=False)
+
+    # --- Strategy 1: Use Tesseract bounding boxes + GridDetectionService ---
+    tess_page_data = session.get(f"tesseract_page_{page_number}")
+
+    if use_tesseract and TESSERACT_AVAILABLE and GRID_SERVICE_AVAILABLE:
+        try:
+            # Run Tesseract if not already cached
+            if not tess_page_data:
+                logger.info("Running Tesseract for grid analysis (not cached)")
+                from tesseract_vocab_extractor import run_tesseract_pipeline as _run_tess
+                tess_page_data = await _run_tess(image_data, lang="eng+deu")
+                session[f"tesseract_page_{page_number}"] = tess_page_data
+                session["tesseract_words"] = tess_page_data.get("words", [])
+                session["tesseract_image_width"] = tess_page_data.get("image_width", 0)
+                session["tesseract_image_height"] = tess_page_data.get("image_height", 0)
+
+            tess_words = tess_page_data.get("words", [])
+            img_w = tess_page_data.get("image_width", 0)
+            img_h = tess_page_data.get("image_height", 0)
+
+            if tess_words and img_w > 0 and img_h > 0:
+                service = GridDetectionService()
+                regions = service.convert_tesseract_regions(tess_words, img_w, img_h)
+
+                if regions:
+                    grid_result = service.detect_grid(regions)
+                    grid_dict = grid_result.to_dict()
+
+                    # Merge LLM text if available (better quality than Tesseract text)
+                    # The LLM vocab was stored during compare-ocr
+                    grid_dict["source"] = "tesseract+grid_service"
+                    grid_dict["word_count"] = len(tess_words)
+
+                    logger.info(f"Tesseract grid: {grid_result.rows}x{grid_result.columns}, "
+                                f"{grid_result.stats.get('recognized', 0)} recognized")
+
+                    return {"success": True, "grid": grid_dict}
+
+            logger.info("Tesseract data insufficient, falling back to LLM")
+
+        except Exception as e:
+            logger.warning(f"Tesseract grid analysis failed, falling back to LLM: {e}")
+            import traceback
+            logger.debug(traceback.format_exc())
+
+    # --- Strategy 2: Fall back to Vision LLM ---
+    image_base64 = base64.b64encode(image_data).decode("utf-8")
+
+    grid_prompt = """Analyze this textbook page image. It contains a vocabulary table/grid.
+
+Your task: Identify the TABLE STRUCTURE and extract each cell's content.
+
+Return a JSON object with this EXACT structure:
+{
+  "rows": <number of rows>,
+  "columns": <number of columns>,
+  "column_types": ["english", "german", "example"],
+  "entries": [
+    {
+      "row": 0,
+      "col": 0,
+      "text": "the word or phrase in this cell",
+      "column_type": "english",
+      "confidence": 0.95
+    }
+  ]
+}
+
+Rules:
+- row and col are 0-indexed
+- column_type is one of: "english", "german", "example", "unknown"
+- Detect whether each column contains English words, German translations, or example sentences
+- Include ALL non-empty cells
+- confidence is 0.0-1.0 based on how clear the text is
+- If a cell is empty, don't include it
+- Return ONLY the JSON, no other text"""
 
     try:
-        # Check if example column is present (at least one vocab has non-empty example)
-        has_examples = any(v.get("example", "").strip() for v in vocab_list)
-        num_cols = 3 if has_examples else 2
-        column_types = ["english", "german", "example"] if has_examples else ["english", "german"]
+        import asyncio
 
-        num_rows = len(vocab_list)
-        if num_rows == 0:
-            return {"success": False, "error": "Keine Vokabeln im Vergleichsergebnis gefunden."}
+        raw_text = ""
+        max_retries = 3
+        for attempt in range(max_retries):
+            async with httpx.AsyncClient(timeout=300.0) as client:
+                response = await client.post(
+                    f"{OLLAMA_URL}/api/chat",
+                    json={
+                        "model": VISION_MODEL,
+                        "messages": [{"role": "user", "content": grid_prompt, "images": [image_base64]}],
+                        "stream": False,
+                        "options": {"temperature": 0.1, "num_predict": 8192},
+                    },
+                    timeout=300.0,
+                )
 
+            if response.status_code == 500 and attempt < max_retries - 1:
+                wait_time = 10 * (attempt + 1)
+                logger.warning(f"Ollama returned 500, retrying in {wait_time}s (attempt {attempt + 1}/{max_retries})")
+                await asyncio.sleep(wait_time)
+                continue
+            elif response.status_code != 200:
+                error_detail = response.text[:200] if response.text else "Unknown error"
+                return {"success": False, "error": f"Ollama Fehler ({response.status_code}): {error_detail}. Bitte erneut versuchen - evtl. laeuft noch ein anderer OCR-Request."}
+
+            raw_text = response.json().get("message", {}).get("content", "")
+            break
+
+        # Parse JSON from response
+        import re
+        json_match = re.search(r'\{[\s\S]*\}', raw_text)
+        if not json_match:
+            return {"success": False, "error": "Could not parse grid structure from LLM response"}
+
+        grid_raw = json.loads(json_match.group())
+
+        num_rows = grid_raw.get("rows", 0)
+        num_cols = grid_raw.get("columns", 0)
+        column_types = grid_raw.get("column_types", [])
+        entries = grid_raw.get("entries", [])
+
+        if num_rows == 0 or num_cols == 0:
+            return {"success": False, "error": "No grid structure detected"}
+
+        # Ensure column_types has the right length
+        while len(column_types) < num_cols:
+            column_types.append("unknown")
+
+        # Build cell grid with percentage-based coordinates
         row_height = 100.0 / num_rows
         col_width = 100.0 / num_cols
 
+        # Track which cells have content
+        cell_map = {}
+        for entry in entries:
+            r = entry.get("row", 0)
+            c = entry.get("col", 0)
+            cell_map[(r, c)] = entry
+
         cells = []
         recognized_count = 0
         empty_count = 0
+        problematic_count = 0
 
-        for r, vocab in enumerate(vocab_list):
+        for r in range(num_rows):
             row_cells = []
-            english = vocab.get("english", "").strip()
-            german = vocab.get("german", "").strip()
-            example = vocab.get("example", "").strip() if has_examples else None
-
-            col_values = [("english", english), ("german", german)]
-            if has_examples:
-                col_values.append(("example", example))
-
-            for c, (col_type, text) in enumerate(col_values):
+            for c in range(num_cols):
                 x = c * col_width
                 y = r * row_height
 
-                if text:
-                    status = "recognized"
-                    recognized_count += 1
-                    conf = 0.9
+                if (r, c) in cell_map:
+                    entry = cell_map[(r, c)]
+                    text = entry.get("text", "").strip()
+                    conf = entry.get("confidence", 0.8)
+                    col_type = entry.get("column_type", column_types[c] if c < len(column_types) else "unknown")
+
+                    if text:
+                        status = "recognized" if conf >= 0.5 else "problematic"
+                        if status == "recognized":
+                            recognized_count += 1
+                        else:
+                            problematic_count += 1
+                    else:
+                        status = "empty"
+                        empty_count += 1
                 else:
+                    text = ""
+                    conf = 0.0
+                    col_type = column_types[c] if c < len(column_types) else "unknown"
                     status = "empty"
                     empty_count += 1
-                    conf = 0.0
 
                 row_cells.append({
                     "row": r,
@@ -1553,7 +1932,7 @@ async def analyze_grid(session_id: str, page_number: int):
                     "y": round(y, 2),
                     "width": round(col_width, 2),
                     "height": round(row_height, 2),
-                    "text": text or "",
+                    "text": text,
                     "confidence": conf,
                     "status": status,
                     "column_type": col_type,
@@ -1561,8 +1940,9 @@ async def analyze_grid(session_id: str, page_number: int):
             cells.append(row_cells)
 
         total = num_rows * num_cols
-        coverage = recognized_count / max(total, 1)
+        coverage = (recognized_count + problematic_count) / max(total, 1)
 
+        # Column and row boundaries as percentages
         col_boundaries = [round(c * col_width, 2) for c in range(num_cols + 1)]
         row_boundaries = [round(r * row_height, 2) for r in range(num_rows + 1)]
 
@@ -1574,9 +1954,10 @@ async def analyze_grid(session_id: str, page_number: int):
             "column_boundaries": col_boundaries,
             "row_boundaries": row_boundaries,
             "deskew_angle": 0.0,
+            "source": "vision_llm",
             "stats": {
                 "recognized": recognized_count,
-                "problematic": 0,
+                "problematic": problematic_count,
                 "empty": empty_count,
                 "manual": 0,
                 "total": total,
@@ -1586,6 +1967,9 @@ async def analyze_grid(session_id: str, page_number: int):
 
         return {"success": True, "grid": grid_data}
 
+    except httpx.TimeoutException:
+        logger.error("Grid analysis timed out")
+        return {"success": False, "error": "Grid-Analyse Timeout (Ollama zu langsam)"}
     except Exception as e:
         logger.error(f"Grid analysis failed: {e}")
         import traceback