refactor: Crop nach Deskew/Dewarp verschieben + content-basierter Buchscan-Crop

Pipeline-Reihenfolge neu: Orientierung → Begradigung → Entzerrung → Zuschneiden → Spalten...
Crop arbeitet jetzt auf dem bereits geraden Bild, was bessere Ergebnisse liefert.

page_crop.py komplett ersetzt: Adaptive Threshold + 4-Kanten-Erkennung
(Buchruecken-Schatten links, Ink-Projektion fuer alle Raender) statt
Otsu + groesste Kontur.

Backend: Step-Nummern, Input-Bilder, Reprocess-Kaskade angepasst.
Frontend: PIPELINE_STEPS umgeordnet, Switch-Cases, Vorher-Bilder aktualisiert.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

klausur-service/backend/page_crop.py

@@ -1,14 +1,15 @@
 """
-Page Crop - Automatic scanner border removal and page format detection.
+Page Crop - Content-based crop for scanned pages and book scans.
 
-Detects the paper boundary in a scanned image and crops away scanner borders.
-Also identifies the paper format (A4, Letter, etc.) from the aspect ratio.
+Detects the content boundary by analysing ink density projections and
+(for book scans) the spine shadow gradient.  Works with both loose A4
+sheets on dark scanners AND book scans with white backgrounds.
 
 License: Apache 2.0
 """
 
 import logging
-from typing import Dict, Any, Tuple
+from typing import Dict, Any, Tuple, Optional
 
 import cv2
 import numpy as np
@@ -24,25 +25,30 @@ PAPER_FORMATS = {
     "A3": 420.0 / 297.0,       # 1.4141
 }
 
+# Minimum ink density (fraction of pixels) to count a row/column as "content"
+_INK_THRESHOLD = 0.003  # 0.3%
+
+# Minimum run length (fraction of dimension) to keep — shorter runs are noise
+_MIN_RUN_FRAC = 0.005  # 0.5%
+
 
 def detect_and_crop_page(
     img_bgr: np.ndarray,
-    min_border_fraction: float = 0.01,
+    margin_frac: float = 0.01,
 ) -> Tuple[np.ndarray, Dict[str, Any]]:
-    """Detect page boundary and crop scanner borders.
+    """Detect content boundary and crop scanner/book borders.
 
-    Algorithm:
-    1. Grayscale + GaussianBlur to smooth out text
-    2. Otsu threshold (page=bright, scanner border=dark)
-    3. Morphological close to fill gaps
-    4. Find largest contour = page
-    5. If contour covers >95% of image area -> no crop needed
-    6. Get bounding rect, add safety margin
-    7. Match aspect ratio to known paper formats
+    Algorithm (4-edge detection):
+    1. Adaptive threshold → binary (text=255, bg=0)
+    2. Left edge: spine-shadow detection via grayscale column means,
+       fallback to binary vertical projection
+    3. Right edge: binary vertical projection (last ink column)
+    4. Top/bottom edges: binary horizontal projection
+    5. Sanity checks, then crop with configurable margin
 
     Args:
-        img_bgr: Input BGR image
-        min_border_fraction: Minimum border fraction to trigger crop (default 1%)
+        img_bgr: Input BGR image (should already be deskewed/dewarped)
+        margin_frac: Extra margin around content (fraction of dimension, default 1%)
 
     Returns:
         Tuple of (cropped_image, result_dict)
@@ -62,41 +68,28 @@ def detect_and_crop_page(
         "border_fractions": {"top": 0.0, "bottom": 0.0, "left": 0.0, "right": 0.0},
     }
 
-    # 1. Grayscale + blur
     gray = cv2.cvtColor(img_bgr, cv2.COLOR_BGR2GRAY)
-    blurred = cv2.GaussianBlur(gray, (21, 21), 0)
 
-    # 2. Otsu threshold
-    _, binary = cv2.threshold(blurred, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    # --- Binarise with adaptive threshold (works for white-on-white) ---
+    binary = cv2.adaptiveThreshold(
+        gray, 255, cv2.ADAPTIVE_THRESH_GAUSSIAN_C,
+        cv2.THRESH_BINARY_INV, blockSize=51, C=15,
+    )
 
-    # 3. Morphological close to fill text gaps
-    kernel = cv2.getStructuringElement(cv2.MORPH_RECT, (50, 50))
-    closed = cv2.morphologyEx(binary, cv2.MORPH_CLOSE, kernel)
+    # --- Left edge: spine-shadow detection ---
+    left_edge = _detect_left_edge_shadow(gray, binary, w, h)
 
-    # 4. Find contours
-    contours, _ = cv2.findContours(closed, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
-    if not contours:
-        logger.info("No contours found - returning original image")
-        return img_bgr, result
+    # --- Right edge: binary vertical projection ---
+    right_edge = _detect_right_edge(binary, w, h)
 
-    # Get the largest contour
-    largest = max(contours, key=cv2.contourArea)
-    contour_area = cv2.contourArea(largest)
+    # --- Top / bottom edges: binary horizontal projection ---
+    top_edge, bottom_edge = _detect_top_bottom_edges(binary, w, h)
 
-    # 5. If contour covers >95% of image, no crop needed
-    if contour_area > 0.95 * total_area:
-        logger.info("Page covers >95%% of image - no crop needed")
-        result["detected_format"], result["format_confidence"] = _detect_format(w, h)
-        return img_bgr, result
-
-    # 6. Get bounding rect
-    rx, ry, rw, rh = cv2.boundingRect(largest)
-
-    # Calculate border fractions
-    border_top = ry / h
-    border_bottom = (h - (ry + rh)) / h
-    border_left = rx / w
-    border_right = (w - (rx + rw)) / w
+    # Compute border fractions
+    border_top = top_edge / h
+    border_bottom = (h - bottom_edge) / h
+    border_left = left_edge / w
+    border_right = (w - right_edge) / w
 
     result["border_fractions"] = {
         "top": round(border_top, 4),
@@ -105,35 +98,34 @@ def detect_and_crop_page(
         "right": round(border_right, 4),
     }
 
-    # 7. Check if borders are significant enough to crop
-    if all(f < min_border_fraction for f in [border_top, border_bottom, border_left, border_right]):
-        logger.info("All borders < %.1f%% - no crop needed", min_border_fraction * 100)
+    # Sanity: only crop if at least one edge has > 2% border
+    min_border = 0.02
+    if all(f < min_border for f in [border_top, border_bottom, border_left, border_right]):
+        logger.info("All borders < %.0f%% — no crop needed", min_border * 100)
         result["detected_format"], result["format_confidence"] = _detect_format(w, h)
         return img_bgr, result
 
-    # 8. Add safety margin (0.5% of image dimensions)
-    margin_x = int(w * 0.005)
-    margin_y = int(h * 0.005)
+    # Add margin
+    margin_x = int(w * margin_frac)
+    margin_y = int(h * margin_frac)
 
-    crop_x = max(0, rx - margin_x)
-    crop_y = max(0, ry - margin_y)
-    crop_x2 = min(w, rx + rw + margin_x)
-    crop_y2 = min(h, ry + rh + margin_y)
+    crop_x = max(0, left_edge - margin_x)
+    crop_y = max(0, top_edge - margin_y)
+    crop_x2 = min(w, right_edge + margin_x)
+    crop_y2 = min(h, bottom_edge + margin_y)
 
     crop_w = crop_x2 - crop_x
     crop_h = crop_y2 - crop_y
 
-    # Sanity check: cropped area should be at least 50% of original
-    if crop_w * crop_h < 0.5 * total_area:
-        logger.warning("Cropped area too small (%.0f%%) - skipping crop",
+    # Sanity: cropped area must be >= 40% of original
+    if crop_w * crop_h < 0.40 * total_area:
+        logger.warning("Cropped area too small (%.0f%%) — skipping crop",
                        100.0 * crop_w * crop_h / total_area)
         result["detected_format"], result["format_confidence"] = _detect_format(w, h)
         return img_bgr, result
 
-    # 9. Crop
     cropped = img_bgr[crop_y:crop_y2, crop_x:crop_x2].copy()
 
-    # 10. Detect format from cropped dimensions
     detected_format, format_confidence = _detect_format(crop_w, crop_h)
 
     result["crop_applied"] = True
@@ -149,23 +141,140 @@ def detect_and_crop_page(
     result["format_confidence"] = format_confidence
     result["aspect_ratio"] = round(max(crop_w, crop_h) / max(min(crop_w, crop_h), 1), 4)
 
-    logger.info("Page cropped: %dx%d -> %dx%d, format=%s (%.0f%%), borders: T=%.1f%% B=%.1f%% L=%.1f%% R=%.1f%%",
-                w, h, crop_w, crop_h, detected_format, format_confidence * 100,
-                border_top * 100, border_bottom * 100, border_left * 100, border_right * 100)
+    logger.info(
+        "Page cropped: %dx%d -> %dx%d, format=%s (%.0f%%), "
+        "borders: T=%.1f%% B=%.1f%% L=%.1f%% R=%.1f%%",
+        w, h, crop_w, crop_h, detected_format, format_confidence * 100,
+        border_top * 100, border_bottom * 100,
+        border_left * 100, border_right * 100,
+    )
 
     return cropped, result
 
 
-def _detect_format(width: int, height: int) -> Tuple[str, float]:
-    """Detect paper format from dimensions by comparing aspect ratios.
+# ---------------------------------------------------------------------------
+# Edge detection helpers
+# ---------------------------------------------------------------------------
 
-    Returns:
-        (format_name, confidence) where confidence is 0.0-1.0
+def _detect_left_edge_shadow(
+    gray: np.ndarray,
+    binary: np.ndarray,
+    w: int,
+    h: int,
+) -> int:
+    """Detect left content edge, accounting for book-spine shadow.
+
+    Strategy: look at the left 25% of the image.
+    1. Compute column-mean brightness in grayscale.
+    2. Smooth with a boxcar kernel.
+    3. Find the transition from shadow (dark) to page (bright).
+    4. Fallback: use binary vertical projection if no shadow detected.
     """
+    search_w = max(1, w // 4)
+
+    # Column-mean brightness in the left quarter
+    col_means = np.mean(gray[:, :search_w], axis=0).astype(np.float64)
+
+    # Smooth with boxcar kernel (width = 1% of image width, min 5)
+    kernel_size = max(5, w // 100)
+    if kernel_size % 2 == 0:
+        kernel_size += 1
+    kernel = np.ones(kernel_size) / kernel_size
+    smoothed = np.convolve(col_means, kernel, mode="same")
+
+    # Determine brightness threshold: midpoint between darkest and brightest
+    val_min = float(np.min(smoothed))
+    val_max = float(np.max(smoothed))
+    shadow_range = val_max - val_min
+
+    # Only use shadow detection if there is a meaningful brightness gradient (> 20 levels)
+    if shadow_range > 20:
+        threshold = val_min + shadow_range * 0.6
+        # Find first column where brightness exceeds threshold
+        above = np.where(smoothed >= threshold)[0]
+        if len(above) > 0:
+            shadow_edge = int(above[0])
+            logger.debug("Left edge: shadow detected at x=%d (range=%.0f)", shadow_edge, shadow_range)
+            return shadow_edge
+
+    # Fallback: binary vertical projection
+    return _detect_edge_projection(binary, axis=0, from_start=True, dim=w)
+
+
+def _detect_right_edge(binary: np.ndarray, w: int, h: int) -> int:
+    """Detect right content edge via binary vertical projection."""
+    return _detect_edge_projection(binary, axis=0, from_start=False, dim=w)
+
+
+def _detect_top_bottom_edges(binary: np.ndarray, w: int, h: int) -> Tuple[int, int]:
+    """Detect top and bottom content edges via binary horizontal projection."""
+    top = _detect_edge_projection(binary, axis=1, from_start=True, dim=h)
+    bottom = _detect_edge_projection(binary, axis=1, from_start=False, dim=h)
+    return top, bottom
+
+
+def _detect_edge_projection(
+    binary: np.ndarray,
+    axis: int,
+    from_start: bool,
+    dim: int,
+) -> int:
+    """Find the first/last row or column with ink density above threshold.
+
+    axis=0 → project vertically (column densities) → returns x position
+    axis=1 → project horizontally (row densities) → returns y position
+
+    Filters out narrow noise runs shorter than _MIN_RUN_FRAC of the dimension.
+    """
+    # Compute density per row/column (mean of binary pixels / 255)
+    projection = np.mean(binary, axis=axis) / 255.0
+
+    # Create mask of "ink" positions
+    ink_mask = projection >= _INK_THRESHOLD
+
+    # Filter narrow runs (noise)
+    min_run = max(1, int(dim * _MIN_RUN_FRAC))
+    ink_mask = _filter_narrow_runs(ink_mask, min_run)
+
+    ink_positions = np.where(ink_mask)[0]
+    if len(ink_positions) == 0:
+        return 0 if from_start else dim
+
+    if from_start:
+        return int(ink_positions[0])
+    else:
+        return int(ink_positions[-1])
+
+
+def _filter_narrow_runs(mask: np.ndarray, min_run: int) -> np.ndarray:
+    """Remove True-runs shorter than min_run pixels."""
+    if min_run <= 1:
+        return mask
+
+    result = mask.copy()
+    n = len(result)
+    i = 0
+    while i < n:
+        if result[i]:
+            start = i
+            while i < n and result[i]:
+                i += 1
+            if i - start < min_run:
+                result[start:i] = False
+        else:
+            i += 1
+    return result
+
+
+# ---------------------------------------------------------------------------
+# Format detection (kept as optional metadata)
+# ---------------------------------------------------------------------------
+
+def _detect_format(width: int, height: int) -> Tuple[str, float]:
+    """Detect paper format from dimensions by comparing aspect ratios."""
     if width <= 0 or height <= 0:
         return "unknown", 0.0
 
-    # Use portrait aspect ratio (taller / shorter)
     aspect = max(width, height) / min(width, height)
 
     best_format = "unknown"
@@ -177,8 +286,6 @@ def _detect_format(width: int, height: int) -> Tuple[str, float]:
             best_diff = diff
             best_format = fmt
 
-    # Confidence: 1.0 if exact match, decreasing with deviation
-    # Threshold: if diff > 0.1, confidence drops below 0.5
     confidence = max(0.0, 1.0 - best_diff * 5.0)
 
     if confidence < 0.3: