Entwickler-CLI: famulus-pipeline

Tippfamulus-pipeline in einem Satz

famulus-pipeline führt die vollständige Mac-Backstage-Pipeline auf einem gespeicherten Master aus, legt nach jeder Stufe ein Zwischenbild ab und druckt den Geometrie-, Tonwert- und OCR-Bericht — damit jede Entscheidung der Pipeline nachvollziehbar und prüfbar ist.

Die grafische Backstage-Oberfläche verbirgt alle Verarbeitungsdetails hinter einer schlichten Benutzeroberfläche. famulus-pipeline kehrt das um: Es ist das Diagnosewerkzeug, das jeden Zwischenzustand sichtbar macht. Es verwendet denselben PDAIBackendPipeline-Code wie die Backstage-App — das Ergebnis ist identisch, nur der Ausgabeweg ist ein Verzeichnis auf dem Dateisystem statt ein Live-Dokumentordner.

1 Vorbereitung

famulus-pipeline ist das famulus-pipeline-Target im Xcode-Projekt. Es wird als macOS Command-Line-Tool gebaut:

xcodebuild -scheme famulus-pipeline -configuration Debug

Das erzeugte Binary liegt unter build/Debug/famulus-pipeline. Es kann beliebige .heic-Master verarbeiten — auch solche, die mit einer älteren App-Version aufgenommen wurden.

2 Grundlegende Verwendung

famulus-pipeline <master.heic> [Optionen]

Ein typischer Diagnoselauf für eine Buchaufnahme:

famulus-pipeline \
  ~/Documents/Scans/Dokument_2026-09-03/masters/master_001.heic \
  --mode book \
  --orientation topOnRight \
  --out /tmp/famulus-debug

Nach dem Lauf enthält /tmp/famulus-debug/ die Stufenbilder und den vollständigen PDAI-Seitenordner.

3 Parameter-Referenz

Parameter Wertebereich Standard Funktion
--mode book, receipt book Dokumentmodus: Doppelseite oder Einzelblatt
--orientation topOnRight, topOnLeft, upright topOnRight Ausrichtung der Buchoberkante im Master
--out <dir> Verzeichnispfad /tmp/famulus-pipeline Ausgabeverzeichnis
Parameter Funktion
--no-flatfield Flat-Field-Korrektur überspringen
--no-enhancer CIDocumentEnhancer überspringen
--no-deskew Entzerrung überspringen
--no-tightcrop Textblock-Beschnitt überspringen
--no-ocr OCR-Schritt überspringen (nur Bild)
Parameter Typ Standard Funktion
--contrast <x> Float 1,15 Stärke der archivischen S-Kurve
--brightness <x> Float 0,0 Verschiebung des Papierziels (+0,1 = heller)
Parameter Funktion
--score Nur Schärfescore messen und ausgeben, Pipeline nicht ausführen
--measure-tilt Neigungsresiduum messen (Projektionsprofil), Pipeline nicht ausführen
--probe-receipt Belegrahmen-Erkennungsdiagnose: Quad-IoU, Winkelabweichung, Hull-Bereich

3.1 Belegdiagnose

# Belegrahmen und Hülle diagnostizieren
famulus-pipeline \
  ~/Documents/Scans/QUITTUNGEN/masters/master_005.heic \
  --mode receipt \
  --probe-receipt \
  --out /tmp/repro-receipt-debug

# Neigungsresiduum messen
famulus-pipeline master_001.heic --measure-tilt

4 Ausgabe: Stufenbilder

Das Ausgabeverzeichnis enthält nach dem Lauf für jede erkannte Seite:

Datei Inhalt
page_001.0-rectified.jpg Perspektivkorrigiertes, ausgerichtetes Bild (nach Schritt 1–3)
page_001.1-flatfield.jpg Nach Flat-Field-Division
page_001.2-levels.jpg Nach Tonwert-Normierung und S-Kurve
page_001.3-enhancer.jpg Nach CIDocumentEnhancer
page_001.4-sharpen.jpg Finales Bild nach Schärfung
page_001/page_001.jpg Identisch mit 4-sharpen — die PDAI-Ablage-Kopie
page_001/page_001.json Vollständiges Seitenprotokoll (GeometryReport + ToneReport + OCRResult + Quality-Gate)

Die Stufenbilder beginnen mit dem verarbeiteten Seitenbild, nie mit dem Roh-Master. 0-rectified.jpg ist die Ausgabe nach Geometrie (Perspektivkorrektur, Rotation, GutterFinder-Seitentrennung).

Durch Vergleich von 0-rectified und 1-flatfield lässt sich prüfen, ob und wie stark die Ausleuchtung korrigiert wurde. 1-flatfield gegen 2-levels zeigt die Wirkung der Tonwert-Normierung. Wenn 2-levels bereits gut aussieht und 3-enhancer schlechter wird, kann --no-enhancer eingesetzt werden.

5 Ausgabe: Konsolen-Bericht

Der Lauf druckt einen strukturierten Bericht auf die Standardausgabe:

master  /path/to/master_001.heic
out     /tmp/famulus-debug
mode    Buch (2-Seiten Doppelseite)  flatfield=true enhancer=true deskew=true tightcrop=true ocr=true

page 1 (left):
  quad  [0.10,0.08] [0.92,0.06] [0.94,0.94] [0.08,0.95]  confidence=0.97  source=mac-segmentation
  gutter  50.2 %  (projection-minimum)
  deskew  0.25°
  crop  [4%, 3%, 92%, 94%]
  output  2680 × 3520 px
  ink=0.042  paper=0.931  median=0.871  flatfield=yes  enhancer=yes
  ocr  vision-documents  de-DE  confidence=0.947  blocks=24

page 2 (right):
  ...

elapsed  4.2 s

6 Schärfescore isoliert messen

Der --score-Modus führt keine Bildverarbeitung durch, sondern nur die Laplace-Varianz-Messung:

famulus-pipeline master_001.heic --score
# score  0.3412  (PASS, gate=0.080)  master_001.heic

Ein FAIL-Ergebnis bedeutet, dass die Aufnahme zu unscharf für eine Verwendung ist und neu gemacht werden sollte. Der Schwellenwert gate=0.080 entspricht dem hardGateThreshold in Sharpness.swift.

7 Diagnose-Leitfaden

Überbelichtetes, zu helles Bild

Ursache: Tinte-Anker liegt nicht bei 0,5. Perzentil, sondern höher; die Pipeline hat keine dunklen Pixel gemessen.

Prüfung: Wert inkPoint im Bericht. Wenn inkPoint > 0.15, ist der Satzspiegel zu hell oder das Messquadrat liegt im falschen Bereich. Mögliche Gründe: Das Dokument ist sehr blass (Bleistift, blasse Tinte), der Untergrund ist nicht schwarz und ragt in das Messquadrat.

Abhilfe: Schwarzen Untergrund sicherstellen; bei extrem blassem Dokument --contrast 1.5 probieren; mit --no-flatfield testen, ob die Flat-Field-Division den Kontrast fälschlicherweise reduziert.

Zu dunkles, zugeschnürtes Bild

Ursache: Das Messquadrat liegt im Falzbereich oder im schwarzen Untergrund. Wenn der Falz in das zentrale Messquadrat ragt, nimmt der Tintenanker einen zu dunklen Wert auf.

Prüfung: measureRect im Bericht. Wenn das Bild zu hoch oder zu niedrig ausgefüllt ist, kann der Falz ins Messquadrat reichen.

Abhilfe: Geometrie prüfen — möglicherweise ist der gutterFraction-Wert falsch und der Split liegt nicht am Bundsteg.

Schiefe Seite

Ursache: deskewDegrees-Wert ist ungleich null, aber der Algorithmus hat den falschen Maximalwinkel gefunden.

Prüfung: deskewDegrees im Bericht. Wenn der Wert > 3°, ist das für ein normales Buch ungewöhnlich.

Abhilfe: --no-deskew testen; wenn das Bild dann gerade ist, liegt ein Fehler im Deskew vor. Das Dokument möglicherweise erneut aufnehmen und dabei auf horizontale Ausrichtung achten.

OCR-Ergebnis leer oder unvollständig

Ursache 1: Kaltstart — das Vision-Modell war beim ersten Lauf noch nicht geladen. Lösung: Lauf wiederholen.

Ursache 2: --no-ocr ist gesetzt.

Ursache 3: Das Bild ist nach der Verarbeitungskette zu dunkel oder zu verrauscht für die Vision-Engine. Stufenbild 3-enhancer.jpg prüfen.