feat(scan): whiten receipt backgrounds and embed OCR in PDFs

agents/fedeo-device-agent/scripts/build-installer.mjs

@@ -14,7 +14,7 @@ async function filesUnder(directory) {
 const packageJson = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'))
 const paths = [
   ...(await filesUnder('dist')).filter(file => file.endsWith('.js')),
-  'scripts/scan_document.py', 'scripts/opencv_postprocess.py', 'scripts/setup-opencv.sh',
+  'scripts/scan_document.py', 'scripts/scan_background.py', 'scripts/opencv_postprocess.py', 'scripts/setup-opencv.sh',
   'requirements-opencv.txt',
 ]
 const files = Object.fromEntries(await Promise.all(paths.map(async file => [file, (await readFile(path.join(root, file))).toString('base64')])))

agents/fedeo-device-agent/scripts/install-linux.sh

@@ -25,17 +25,22 @@ FEDEO_SETUP_UNIT="fedeo-device-agent-$FEDEO_SETUP_ID.service"
 FEDEO_SETUP_UNITS="${XDG_CONFIG_HOME:-$HOME/.config}/systemd/user"
 
 echo 'FEDEO Scan-Agent wird für diesen Benutzer eingerichtet.'
-if ! command -v node >/dev/null || ! command -v scanimage >/dev/null || ! python3 -c 'import PIL' >/dev/null 2>&1; then
+fedeo_processing_ready() {
+  python3 -c 'import PIL, cv2, numpy' >/dev/null 2>&1 &&
+    tesseract --list-langs 2>/dev/null | grep -qx deu &&
+    tesseract --list-langs 2>/dev/null | grep -qx eng
+}
+if ! command -v node >/dev/null || ! command -v scanimage >/dev/null || ! fedeo_processing_ready; then
   if ! command -v apt-get >/dev/null; then
-    echo 'Bitte Node.js >= 20, SANE (scanimage), Python 3 und Pillow installieren und das Skript erneut starten.' >&2
+    echo 'Bitte Node.js >= 20, SANE, Python/Pillow/OpenCV sowie Tesseract mit Deutsch/Englisch installieren und das Skript erneut starten.' >&2
     exit 1
   fi
   echo 'Fehlende Systempakete werden über apt installiert (sudo benötigt).'
   sudo apt-get update
-  sudo apt-get install -y nodejs sane-utils python3-pil
+  sudo apt-get install -y nodejs sane-utils python3-pil python3-opencv tesseract-ocr tesseract-ocr-deu tesseract-ocr-eng
 fi
 node -e 'if (Number(process.versions.node.split(".")[0]) < 20) { console.error("Node.js >= 20 wird benötigt. Bitte Node.js aktualisieren und die Installation erneut starten."); process.exit(1) }'
-python3 -c 'import PIL'
+fedeo_processing_ready || { echo 'Die benötigte Bildverarbeitung oder die OCR-Sprachpakete fehlen weiterhin.' >&2; exit 1; }
 
 FEDEO_SETUP_NODE="$(command -v node)"
 FEDEO_SETUP_HAS_SYSTEMD=false

agents/fedeo-device-agent/scripts/scan_background.py

@@ -0,0 +1,74 @@
+"""Conservative paper masking. Keep the canvas and every pixel inside the paper."""
+from pathlib import Path
+
+import cv2
+import numpy as np
+
+
+def whiten_background(image):
+    height, width = image.shape[:2]
+    scale = min(1.0, 1000.0 / max(height, width))
+    small = cv2.resize(image, None, fx=scale, fy=scale, interpolation=cv2.INTER_AREA)
+    gray = cv2.cvtColor(small, cv2.COLOR_BGR2GRAY)
+    border = np.concatenate((gray[0], gray[-1], gray[:, 0], gray[:, -1]))
+    background = float(np.median(border))
+    # White surroundings already need no correction. Never search inside a
+    # white document for an isolated text box or logo to keep instead.
+    if background >= 235 or np.percentile(border, 75) - np.percentile(border, 25) > 55:
+        return image
+
+    threshold, _ = cv2.threshold(gray, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+    mask = np.uint8(gray > max(threshold, background + 20)) * 255
+    mask = cv2.morphologyEx(mask, cv2.MORPH_CLOSE, np.ones((5, 5), np.uint8))
+    contours, _ = cv2.findContours(mask, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
+    candidates = []
+    area = gray.size
+    for contour in contours:
+        contour_area = cv2.contourArea(contour)
+        if not 0.015 * area < contour_area < 0.985 * area:
+            continue
+        perimeter = cv2.arcLength(contour, True)
+        polygon = cv2.approxPolyDP(contour, 0.018 * perimeter, True)
+        if len(polygon) != 4 or not cv2.isContourConvex(polygon):
+            continue
+        # Use the quadrilateral only to recognize a sheet, then keep its full
+        # contour hull so rounded or slightly uneven edges cannot lose content.
+        polygon = cv2.convexHull(contour)
+        paper = np.zeros_like(gray)
+        cv2.fillPoly(paper, [polygon], 255)
+        inside = cv2.erode(paper, np.ones((7, 7), np.uint8)) > 0
+        ring = (cv2.dilate(paper, np.ones((9, 9), np.uint8)) > 0) & (paper == 0)
+        if inside.sum() < 100 or ring.sum() < 50:
+            continue
+        paper_light = float(np.median(gray[inside]))
+        # A paper edge must separate a mostly light sheet from darker scanner
+        # backing all around it. Ambiguous photos/pages are left untouched.
+        if paper_light < background + 30 or np.mean(gray[ring] < paper_light - 20) < 0.85:
+            continue
+        candidates.append(polygon)
+
+    if not candidates:
+        return image
+    keep_small = np.zeros_like(gray)
+    cv2.fillPoly(keep_small, candidates, 255)
+    # Do not erase another significant object that we could not classify.
+    outside = (keep_small == 0)
+    if np.mean(gray[outside] > background + 30) > 0.04:
+        return image
+    keep = np.zeros((height, width), dtype=np.uint8)
+    polygons = [np.rint(polygon / scale).astype(np.int32) for polygon in candidates]
+    cv2.fillPoly(keep, polygons, 255)
+    # Rounding/downsampling uncertainty grows with the original scan DPI.
+    padding = max(2, int(np.ceil(2 / scale)))
+    keep = cv2.dilate(keep, np.ones((2 * padding + 1, 2 * padding + 1), np.uint8))
+    result = image.copy()
+    result[keep == 0] = 255
+    return result
+
+
+def clean_scan_background(input_path: Path, output_path: Path):
+    image = cv2.imread(str(input_path), cv2.IMREAD_COLOR)
+    if image is None:
+        raise RuntimeError("Scan-Bild konnte nicht gelesen werden")
+    if not cv2.imwrite(str(output_path), whiten_background(image)):
+        raise RuntimeError("Bereinigtes Scan-Bild konnte nicht gespeichert werden")

agents/fedeo-device-agent/scripts/scan_document.py

@@ -1,21 +1,56 @@
 #!/usr/bin/env python3
-"""Assemble ordered scanner pages; OpenCV is optional, PDF creation is not."""
+"""Prepare ordered scanner pages and publish an optionally searchable PDF atomically."""
 import argparse
 import json
+import math
 from pathlib import Path
+import re
+import signal
+import subprocess
+import tempfile
 
-from PIL import Image
+from PIL import Image, PdfParser
 
 
-def create_document(inputs, output, resolution, use_postprocess=False, profile="document", strict=False):
+def run_ocr_command(arguments):
+    process = subprocess.Popen(arguments, stdout=subprocess.PIPE, stderr=subprocess.PIPE, text=True)
+    try:
+        stdout, stderr = process.communicate()
+    except BaseException:
+        process.kill()
+        process.wait()
+        raise
+    if process.returncode != 0:
+        raise RuntimeError("OCR fehlgeschlagen: " + stderr.strip())
+    return stdout
+
+
+def check_ocr(language):
+    if not re.fullmatch(r"[a-zA-Z0-9_]+(?:\+[a-zA-Z0-9_]+)*", language):
+        raise ValueError("Ungültige OCR-Sprache")
+    try:
+        languages = run_ocr_command(["tesseract", "--list-langs"]).splitlines()
+    except FileNotFoundError as error:
+        raise RuntimeError("Tesseract fehlt. Bitte tesseract-ocr und die Sprachpakete tesseract-ocr-deu/tesseract-ocr-eng installieren.") from error
+    missing = set(language.split("+")) - {line.strip() for line in languages}
+    if missing:
+        raise RuntimeError("OCR-Sprachpakete fehlen: " + ", ".join(sorted(missing)))
+
+
+def create_document(inputs, output, resolution, use_postprocess=False, profile="document", strict=False,
+                    ocr=False, ocr_language="deu+eng", background_cleanup=False):
     if not inputs:
         raise ValueError("Keine Seiten vorhanden")
+    if not math.isfinite(resolution) or resolution <= 0:
+        raise ValueError("Ungültige Scan-Auflösung")
     output = Path(output)
     file_format = {".pdf": "PDF", ".png": "PNG", ".tiff": "TIFF"}.get(output.suffix.lower())
     if not file_format:
         raise ValueError("Unbekanntes Ausgabeformat")
-    if file_format != "PDF" and len(inputs) != 1:
-        raise ValueError("Mehrseitige Scans benötigen PDF als Ausgabeformat")
+    if (len(inputs) != 1 or ocr) and file_format != "PDF":
+        raise ValueError("Mehrseitige Scans und OCR benötigen PDF als Ausgabeformat")
+    if ocr:
+        check_ocr(ocr_language)
 
     warnings = []
     processor = None
@@ -27,47 +62,92 @@ def create_document(inputs, output, resolution, use_postprocess=False, profile="
             if strict:
                 raise
             warnings.append("OpenCV fehlt; alle Seiten wurden ohne Bildkorrektur übernommen.")
+    if background_cleanup:
+        from scan_background import clean_scan_background
 
     partial = output.with_name(output.name + ".partial")
     try:
-        for index, input_path in enumerate(inputs):
-            input_path = Path(input_path)
-            image_path = input_path
-            corrected = input_path.with_name(input_path.stem + ".corrected.png")
-            if processor:
-                try:
-                    processor(input_path, corrected, profile)
-                    image_path = corrected
-                except Exception:
-                    if strict:
-                        raise
-                    warnings.append(f"Seite {index + 1}: Bildkorrektur fehlgeschlagen; Rohscan übernommen.")
+        with tempfile.TemporaryDirectory(prefix="prepared-", dir=output.parent) as directory:
+            prepared = []
+            for index, input_path in enumerate(inputs):
+                image_path = Path(input_path)
+                corrected = Path(directory) / f"corrected-{index:06}.png"
+                if processor:
+                    try:
+                        processor(image_path, corrected, profile)
+                        image_path = corrected
+                    except Exception:
+                        if strict:
+                            raise
+                        warnings.append(f"Seite {index + 1}: Bildkorrektur fehlgeschlagen; Rohscan übernommen.")
+                if background_cleanup:
+                    cleaned = Path(directory) / f"cleaned-{index:06}.png"
+                    clean_scan_background(image_path, cleaned)
+                    image_path = cleaned
 
-            # Only one decoded page is kept in memory, even for large duplex stacks.
-            with Image.open(image_path) as image:
-                with image.convert("RGB") as rgb:
-                    if file_format == "PDF":
-                        rgb.save(partial, "PDF", resolution=resolution, quality=90, append=index > 0)
-                    else:
-                        rgb.save(partial, file_format, dpi=(resolution, resolution))
-            corrected.unlink(missing_ok=True)
-        partial.replace(output)
+                # Only one decoded page is kept in memory, even for duplex stacks.
+                with Image.open(image_path) as image:
+                    with image.convert("RGB") as rgb:
+                        if ocr:
+                            page = Path(directory).resolve() / f"page-{index:06}.png"
+                            rgb.save(page, "PNG", dpi=(resolution, resolution))
+                            prepared.append(page)
+                        elif file_format == "PDF":
+                            rgb.save(partial, "PDF", resolution=resolution, quality=90, append=index > 0)
+                        else:
+                            rgb.save(partial, file_format, dpi=(resolution, resolution))
+                corrected.unlink(missing_ok=True)
+                if background_cleanup:
+                    cleaned.unlink(missing_ok=True)
+            if ocr:
+                page_list = Path(directory) / "pages.txt"
+                if any("\n" in str(page) or "\r" in str(page) for page in prepared):
+                    raise ValueError("Das Scan-Arbeitsverzeichnis darf keinen Zeilenumbruch enthalten")
+                page_list.write_text("\n".join(map(str, prepared)) + "\n", encoding="utf8")
+                prefix = Path(directory) / "searchable"
+                run_ocr_command(["tesseract", str(page_list), str(prefix), "-l", ocr_language,
+                                 "--dpi", str(round(resolution)), "pdf"])
+                searchable = prefix.with_suffix(".pdf")
+                with PdfParser.PdfParser(filename=str(searchable)) as pdf:
+                    if len(pdf.pages) != len(inputs):
+                        raise RuntimeError("OCR-PDF ist unvollständig; Rohscans bleiben erhalten")
+                searchable.replace(partial)
+            partial.replace(output)
     finally:
         partial.unlink(missing_ok=True)
-
     return {"pageCount": len(inputs), "warnings": warnings}
 
 
+def interrupted(*_):
+    raise SystemExit("Scan-Verarbeitung abgebrochen")
+
+
 def main():
+    # Let finally blocks stop Tesseract and remove incomplete PDFs on agent timeout.
+    signal.signal(signal.SIGTERM, interrupted)
     parser = argparse.ArgumentParser(description="Scan-Seiten zu einer Datei zusammenführen")
-    parser.add_argument("--inputs", nargs="+", required=True)
-    parser.add_argument("--output", required=True)
-    parser.add_argument("--resolution", type=float, required=True)
+    parser.add_argument("--inputs", nargs="+")
+    parser.add_argument("--output")
+    parser.add_argument("--resolution", type=float, default=300)
     parser.add_argument("--profile", choices=["document", "receipt", "raw"], default="document")
     parser.add_argument("--postprocess", action="store_true")
     parser.add_argument("--strict", action="store_true")
+    parser.add_argument("--background-cleanup", action="store_true")
+    parser.add_argument("--ocr", action="store_true")
+    parser.add_argument("--ocr-language", default="deu+eng")
+    parser.add_argument("--check-runtime", action="store_true")
     args = parser.parse_args()
-    print(json.dumps(create_document(args.inputs, args.output, args.resolution, args.postprocess, args.profile, args.strict)))
+    if args.check_runtime:
+        if args.background_cleanup or (args.postprocess and args.strict):
+            import cv2, numpy
+        if args.ocr:
+            check_ocr(args.ocr_language)
+        print(json.dumps({"ready": True}))
+        return
+    if not args.inputs or not args.output:
+        parser.error("--inputs und --output sind erforderlich")
+    print(json.dumps(create_document(args.inputs, args.output, args.resolution, args.postprocess, args.profile,
+                                    args.strict, args.ocr, args.ocr_language, args.background_cleanup)))
 
 
 if __name__ == "__main__":