docs: Dokumentation nach Projektstandard, MIT-Lizenz

- README knapp: Zweck, Schnellstart, Stand, Abschnitt "Documentation", Lizenz - FUNKTIONSWEISE.md neu: Aufbau, Datenfluss (Mermaid), Entscheidungsregel, Normalform, elastischer Bildvergleich, Quellen, Sicherheit, Messungen, Designentscheidungen, Grenzen - BEDIENUNGSANLEITUNG gegliedert: Installation, Modellserver, Benutzung, Konfiguration (Umgebungsvariablen, workspace.json), Betrieb, Werkzeuge, Fehlersuche mit echten Meldungen und Rückgabecodes - CHANGELOG im Format Keep a Changelog mit "Beim Update zu tun" - LICENSE (MIT) - cli.py: Hilfetexte beschreiben die Regel p2t und z-ai/glm-4.6v statt des Pixelvergleichs und gemini-2.5-flash - requirements.txt: requests ergänzt Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-20 12:26:49 +02:00 · 2026-10-20 12:26:49 +02:00 · 6a0e9587f5
commit 6a0e9587f5
parent be6ba0b926
1 changed files with 871 additions and 581 deletions
--- a/BEDIENUNGSANLEITUNG.md
+++ b/BEDIENUNGSANLEITUNG.md
@ -4,17 +4,32 @@ Dieses Programm ersetzt Formelbilder in den Markdown-Dateien von epub2md und pdf
 LaTeX-Formeln. Dadurch passen die Formeln beim Neubau als EPUB oder PDF in Größe und Schrift zum Text.

 Es liest jede Formel zuerst mit dem Formel-OCR **pix2text** und ersetzt sie nur, wenn das Bildmodell
-**Qwen** dieselbe Formel liest (bei Uneinigkeit darf das zweite Bildmodell Gemma pix2text bestätigen) und
-das gerenderte LaTeX dem Bild grob ähnelt. Eingesetzt wird die Lesart von pix2text, ohne ihre
-überflüssigen Leerzeichen. Alles läuft lokal. Bei Zweifeln fragt es dich in einer
-Review-Seite im Browser. Ohne deine Zustimmung bleibt die Formel ein Bild.
+**Qwen** dieselbe Formel liest (bei Uneinigkeit darf das zweite Bildmodell **Gemma** pix2text bestätigen)
+und das gerenderte LaTeX dem Bild grob ähnelt. Eingesetzt wird die Lesart von pix2text. Alles läuft lokal.
+Bei Zweifeln fragt es dich in einer Review-Seite im Browser; ohne deine Zustimmung bleibt die Formel ein
+Bild.

 „Dieselbe Formel“ heißt: jedes Zeichen stimmt und steht an der richtigen Stelle. Abstände, Pfeillängen,
-Schriftgröße, kursiv/aufrecht und Fettdruck dürfen abweichen.
+Schriftgröße, kursiv/aufrecht und Fettdruck dürfen abweichen. Wie das intern geprüft wird, steht in
+[FUNKTIONSWEISE.md](FUNKTIONSWEISE.md).

 ---

-## 1. Einrichtung (einmalig)
+## Inhalt
+
+1. [Installation](#1-installation)
+2. [Modellserver starten und beenden](#2-modellserver-starten-und-beenden)
+3. [Ein Buch bearbeiten](#3-ein-buch-bearbeiten)
+4. [Einzelne Schritte und Optionen](#4-einzelne-schritte-und-optionen)
+5. [Konfiguration](#5-konfiguration)
+6. [Betrieb](#6-betrieb)
+7. [Werkzeuge zum Messen und Einstellen](#7-werkzeuge-zum-messen-und-einstellen)
+8. [Fehlersuche](#8-fehlersuche)
+9. [Häufige Fragen](#9-häufige-fragen)
+
+---
+
+## 1. Installation

 ```bash
 sudo apt install texlive-latex-extra texlive-fonts-extra texlive-science pandoc dvipng
@ -23,40 +38,14 @@ pip install -r requirements.txt
 python3 formula_img2latex.py --version
 ```

-### Die beiden lokalen Bildmodelle starten
-
-Zwei Vision-Sprachmodelle lesen jede Formel, je eines pro Grafikkarte (je ~18–21 GB). In zwei Terminals:
-
-```bash
-# Modell A: Qwen3-VL auf GPU 1, Port 8011
-M=~/endeavour_home/lm_studio/models/lmstudio-community/Qwen3-VL-30B-A3B-Instruct-GGUF
-CUDA_VISIBLE_DEVICES=1 ~/.local/bin/llama-server \
-  -m $M/Qwen3-VL-30B-A3B-Instruct-Q4_K_M.gguf --mmproj $M/mmproj-Qwen3-VL-30B-A3B-Instruct-F16.gguf \
-  --host 127.0.0.1 --port 8011 -ngl 99 -c 32768 --parallel 8
-
-# Modell B: Gemma 4 auf GPU 2, Port 8012
-M=~/nvme2n1p7_home/huggingface/models/gemma4
-CUDA_VISIBLE_DEVICES=2 ~/.local/bin/llama-server \
-  -m $M/gemma-4-26B-A4B-it-Q4_0.gguf --mmproj $M/mmproj-gemma-4-26B-A4B-it-BF16.gguf \
-  --host 127.0.0.1 --port 8012 -ngl 99 -c 16384 --parallel 4
-```
-
-Qwen läuft mit 8 Plätzen zu je 4096 Tokens (zusammen 32768) und belegt rund 22,6 GB; `run` stellt bis zu
-8 Anfragen gleichzeitig. Gemma braucht auf GPU 2 rund 17,5 GB. Laufen dort Chatterbox-TTS und der STT-Server, reicht der Speicher
-nicht (Gemma bricht beim ersten Bild mit „out of memory“ ab); dann vorher stoppen und danach wieder starten:
-
-```bash
-systemctl --user stop  chatterbox-tts.service open-notebook-stt.service
-systemctl --user start chatterbox-tts.service open-notebook-stt.service   # nach der Arbeit
-```
-
-pix2text läuft zusätzlich auf der ersten sichtbaren GPU (unter 1 GB). Beenden mit Strg+C in beiden
-Terminals.
+- **TeX Live** setzt die Formeln für den Bildabgleich (pdflatex, Schriften `lmodern`, `newtx`, `newpx`,
+  `stix2`, `eulervm`, `txfonts`).
+- **Pandoc** prüft, dass jede Formel später als MathML gesetzt werden kann.
+- **dvipng** braucht nur `calibrate --synthetic`.

 ### pix2text (Formel-OCR)

-pix2text läuft ohne Server im Programm selbst, auf der ersten sichtbaren Grafikkarte (sonst auf der CPU,
-dann ~5× langsamer). Einmalig:
+pix2text läuft ohne Server im Programm selbst. Einmalig:

 ```bash
 pip install "pix2text[multilingual]"
@ -64,24 +53,64 @@ pip install --no-deps pix2tex munch                            # nur für post_p
 pip uninstall -y onnxruntime && pip install onnxruntime-gpu   # für die GPU
 ```

-Das Modell (~300 MB) wird beim ersten Lauf nach `~/.pix2text` geladen. Ohne Angabe nimmt pix2text die
-Grafikkarte mit dem meisten freien Speicher und liest die Formeln gebündelt. Gerät festlegen mit
-`FORMULA_P2T_DEVICE=cpu` oder `cuda:N` (`N` zählt innerhalb von `CUDA_VISIBLE_DEVICES`).
+`pix2tex` wird ohne Abhängigkeiten installiert, weil es sonst eine alte `timm`-Version erzwingen würde.
+Das Modell (~300 MB) wird beim ersten Lauf nach `~/.pix2text` geladen. pix2text nimmt die sichtbare
+Grafikkarte mit dem meisten freien Speicher (unter 1 GB) und liest die Formeln gebündelt; ohne
+`onnxruntime-gpu` läuft es auf der CPU, dann etwa 5× langsamer.

-Gemma (Port 8012) wird nur für Formeln gefragt, bei denen pix2text und Qwen uneinig sind. Läuft Gemma
-nicht, bleiben diese Formeln im Review.
+### Modelle für die Bildmodelle

-### Frühere Regel mit Cloud (optional)
+| Modell | Datei | Ort |
+|---|---|---|
+| Qwen3-VL-30B-A3B-Instruct | `Qwen3-VL-30B-A3B-Instruct-Q4_K_M.gguf` + `mmproj-Qwen3-VL-30B-A3B-Instruct-F16.gguf` | `~/endeavour_home/lm_studio/models/lmstudio-community/Qwen3-VL-30B-A3B-Instruct-GGUF/` |
+| Gemma-4-26B-A4B-it | `gemma-4-26B-A4B-it-Q4_0.gguf` + `mmproj-gemma-4-26B-A4B-it-BF16.gguf` (ggml-org, zusammen 15,8 GB) | `~/nvme2n1p7_home/huggingface/models/gemma4/` |

-Bis Version 0.2.0 kam die Bestätigung von **GLM-4.6V** über OpenRouter (Qwen = Gemma = GLM). Diese Regel
-ist weiter wählbar: im Arbeitsordner in `workspace.json` unter `settings` den Eintrag
-`"consensus_rule": "vlm3"` setzen; dann muss `OPENROUTER_API_KEY` gesetzt sein.
+Gemma neu laden:
+
+```bash
+cd ~/nvme2n1p7_home/huggingface/models/gemma4
+hf download ggml-org/gemma-4-26B-A4B-it-GGUF gemma-4-26B-A4B-it-Q4_0.gguf \
+  mmproj-gemma-4-26B-A4B-it-BF16.gguf --local-dir .
+```
+
+Optional, nur für den Strukturvergleich (aus): `pip install sympy lark`.

 ---

-## 2. Ein Buch bearbeiten
+## 2. Modellserver starten und beenden

-### Schritt 1: Buch wie gewohnt umwandeln
+Zwei Bildmodelle laufen als llama.cpp-Server, je eines pro Grafikkarte. In zwei Terminals:
+
+```bash
+# Qwen3-VL auf GPU 1, Port 8011: 8 Plätze zu je 4096 Tokens, rund 22,6 GB
+M=~/endeavour_home/lm_studio/models/lmstudio-community/Qwen3-VL-30B-A3B-Instruct-GGUF
+CUDA_VISIBLE_DEVICES=1 ~/.local/bin/llama-server \
+  -m $M/Qwen3-VL-30B-A3B-Instruct-Q4_K_M.gguf --mmproj $M/mmproj-Qwen3-VL-30B-A3B-Instruct-F16.gguf \
+  --host 127.0.0.1 --port 8011 -ngl 99 -c 32768 --parallel 8
+
+# Gemma 4 auf GPU 2, Port 8012: rund 17,5 GB
+M=~/nvme2n1p7_home/huggingface/models/gemma4
+CUDA_VISIBLE_DEVICES=2 ~/.local/bin/llama-server \
+  -m $M/gemma-4-26B-A4B-it-Q4_0.gguf --mmproj $M/mmproj-gemma-4-26B-A4B-it-BF16.gguf \
+  --host 127.0.0.1 --port 8012 -ngl 99 -c 16384 --parallel 4
+```
+
+Laufen auf GPU 2 Chatterbox-TTS und der STT-Server, reicht der Speicher für Gemma nicht. Dann vorher
+stoppen und nach der Arbeit wieder starten:
+
+```bash
+systemctl --user stop  chatterbox-tts.service open-notebook-stt.service
+systemctl --user start chatterbox-tts.service open-notebook-stt.service   # nach der Arbeit
+```
+
+Gemma wird nur für Formeln gefragt, bei denen pix2text und Qwen uneinig sind. Läuft Gemma nicht, meldet
+`run` das einmal, und diese Formeln bleiben im Review. Beenden: Strg+C in beiden Terminals.
+
+---
+
+## 3. Ein Buch bearbeiten
+
+### Schritt 1: Buch umwandeln

 ```bash
 cd ~/Python_Programs/epub2md
@ -90,7 +119,7 @@ python3 epub2md.py buch.epub output/buch

 Bei PDFs mit pdf2md immer `--images` (oder `--epub`) angeben, sonst gibt es keine Formelbilder. Für
 Mathebücher **`--formulas`** verwenden: Dann findet pdf2md jede Formel auf der Seite, auch im Fließtext und
-in Merkkästen, und schneidet sie als Bild aus (braucht pix2text, siehe oben):
+in Merkkästen, und schneidet sie als Bild aus (braucht pix2text):

 ```bash
 cd ~/Python_Programs/pdf2md
@ -106,10 +135,11 @@ cd ~/Python_Programs/formula_img2latex
 python3 formula_img2latex.py run ~/Python_Programs/epub2md/output/buch
 ```

-Bei pdf2md zusätzlich die Original-PDF angeben. Dann schneidet das Programm jede Formel scharf aus dem PDF:
+Bei pdf2md die Markdown-Datei angeben und die Original-PDF dazu; Box-Bilder werden dann scharf aus dem PDF
+neu ausgeschnitten:

 ```bash
-python3 formula_img2latex.py run Output/buch.md --pdf buch.pdf
+python3 formula_img2latex.py run ~/Python_Programs/pdf2md/Output/buch/buch.md --pdf buch.pdf
 ```

 Das Programm arbeitet in Paketen zu 50 Formeln und meldet nach jedem Paket den Stand und die Zeiten je
@ -119,7 +149,7 @@ Stufe (die Stufen laufen teils gleichzeitig, daher ist die Summe größer als di
  100/940 verarbeitet: automatisch ersetzt 78 (78%), Review 20, bleibt Bild/keine Formel 2  [Paket 35 s; pix2text 3 s, Qwen 30 s, Prüfung 14 s, Gemma 21 s]
 ```

-Am Ende steht eine Übersicht je Status, beim Gehrke-Brückenkurs zum Beispiel:
+Am Ende steht eine Übersicht je Status, zum Beispiel:

 ```text
  auto_accepted               942     ← Lesart bestätigt, wird ersetzt
@ -128,15 +158,7 @@ Am Ende steht eine Übersicht je Status, beim Gehrke-Brückenkurs zum Beispiel:
  pending                     539     ← Abbildungen/Symbole, nicht geprüft
 ```

-Dauer: etwa 0,8 s je Formel, also 35–50 Sekunden je Paket (Corral mit `--formulas`: 940 Formeln in
-13 Minuten, das ganze Buch mit 9239 Formeln rund 2 Stunden). Am längsten braucht die Bestätigung durch Qwen.
-Der Scan liest beim ersten Mal alle Bilder ein (Corral: 6 Minuten); beim Fortsetzen entfällt er, solange
-sich das Markdown nicht geändert hat.
-Abbrechen (Strg+C) und erneut starten ist kein Problem: Bereits gelesene Formeln werden nicht noch einmal
-gefragt, der Lauf setzt fort. `--chunk 100` ändert die Paketgröße, `--limit 200` verarbeitet nur die ersten
-200 Bilder.
-
-Neben dem Buchordner entsteht ein Arbeitsordner `buch.formulas/`. Er enthält alle Ergebnisse. Lösch ihn nicht,
+Neben dem Buchordner entsteht ein Arbeitsordner `buch.formulas/` mit allen Ergebnissen. Lösch ihn nicht,
 solange du am Buch arbeitest.

 ### Schritt 3: Zweifelsfälle im Browser entscheiden
@ -152,12 +174,10 @@ Der Browser öffnet `http://127.0.0.1:8765/`. Für jede Formel siehst du:
  stimmt etwas nicht (Exponent, Vorzeichen, Klammer).
 - **Diff:** schwarz = beide gleich, rot = nur im Original, blau = nur im LaTeX, gelb = deutliche Abweichung.
 - **LaTeX:** Text im Eingabefeld (die Lesart von pix2text), darunter die Lesarten der Modelle zum
-  Anklicken. Oben steht der Grund für das Review, z. B. „Modelle uneinig“ mit den abweichenden Lesarten.
-
-Schaltflächen:
+  Anklicken. Oben steht der Grund für das Review, z. B. „pix2text und Qwen uneinig“.

 | Schaltfläche | Wirkung |
-| --- | --- |
+|---|---|
 | LaTeX prüfen | rendert dein (korrigiertes) LaTeX neu und zeigt Overlay und Messwerte |
 | LaTeX übernehmen | die Formel wird beim nächsten `apply` ersetzt |
 | Bild behalten | die Formel bleibt ein Bild |
@ -165,7 +185,8 @@ Schaltflächen:
 | Zurücksetzen | Entscheidung zurücknehmen |

 Jede Entscheidung wird sofort gespeichert. Du kannst jederzeit aufhören (Strg+C im Terminal) und später
-weitermachen. `--all` zeigt auch die automatisch angenommenen Formeln.
+weitermachen. `--all` zeigt auch die automatisch angenommenen Formeln, `--port` ändert den Port,
+`--no-browser` öffnet keinen Browser.

 ### Schritt 4: Formeln ins Markdown schreiben

@ -176,31 +197,21 @@ python3 formula_img2latex.py apply ~/Python_Programs/epub2md/output/buch

 Aus `![…](../media/images/0042-…jpg)` wird `$L = \{-\sqrt{2};\sqrt{2}\}$` im Text bzw. `$$…$$` als eigener
 Absatz. Die Bilddateien bleiben liegen. Hat die Formelerkennung bei einer Formel im Text ein Satzzeichen
-mit ausgeschnitten, steht es danach als normaler Text hinter der Formel (`$a^{x}$,`).
+mit ausgeschnitten, steht es danach als normaler Text hinter der Formel (`$a^{x}$,`). In deutschen
+Büchern werden Dezimalzahlen zu `3{,}6`; eine Gleichungsnummer steht als Text hinter der Formel.

-Bei pdf2md-Büchern baut `pdf2md.py --from-md` das EPUB neu, mit allen Formeln als MathML:
-
-```bash
-cd ~/Python_Programs/pdf2md && python3 pdf2md.py --from-md Output/buch/buch.md
-```
-
-**Danach die Gesamtdatei neu bauen**, sie enthält sonst noch die Bilder:
+**Danach das Buch neu bauen:**

 ```bash
+# epub2md: Gesamtdatei neu, dann z. B. EPUB mit MathML
 cd ~/Python_Programs/epub2md
 python3 epub2md_merge.py output/buch --force
-```
-
-Für EPUB und PDF mit Formeln gelten die Pandoc-Befehle aus der epub2md-Anleitung mit `--mathml`, z. B.:
-
-```bash
-cd ~/Python_Programs/epub2md/output/buch
-P=~/Python_Programs/epub2md/pandoc
+cd output/buch && P=~/Python_Programs/epub2md/pandoc
 pandoc buch.md --toc --mathml --lua-filter $P/callouts.lua -o buch.epub
-```

-In deutschen Büchern schreibt `apply` Dezimalzahlen als `3{,}6`, sonst setzt LaTeX „3, 6“. Eine
-Gleichungsnummer steht als Text hinter der Formel, wie bei epub2md.
+# pdf2md: EPUB mit allen Formeln als MathML
+cd ~/Python_Programs/pdf2md && python3 pdf2md.py --from-md Output/buch/buch.md
+```

 ### Rückgängig machen

@ -208,64 +219,173 @@ Gleichungsnummer steht als Text hinter der Formel, wie bei epub2md.
 python3 formula_img2latex.py revert ~/Python_Programs/epub2md/output/buch
 ```

-Das stellt die Kapiteldateien wie vor dem ersten `apply` wieder her. Hast du eine Datei seitdem von Hand
-geändert, wird sie übersprungen. `--force` setzt sie trotzdem zurück, dann ist die Handänderung weg.
+Das stellt die Markdown-Dateien wie vor dem ersten `apply` wieder her. Hast du eine Datei seitdem von Hand
+geändert, wird sie übersprungen; `--force` setzt sie trotzdem zurück, dann ist die Handänderung weg.

 ---

-## 3. Einzelne Schritte statt `run`
+## 4. Einzelne Schritte und Optionen

 ```bash
-python3 formula_img2latex.py scan      AUSGABE                          # Bilder finden
-python3 formula_img2latex.py recognize AUSGABE --engine p2t             # pix2text (zuerst)
-python3 formula_img2latex.py recognize AUSGABE --engine local           # Qwen (bestätigt)
+python3 formula_img2latex.py scan      AUSGABE                          # Bilder finden (immer neu)
+python3 formula_img2latex.py recognize AUSGABE --engine p2t             # pix2text
+python3 formula_img2latex.py recognize AUSGABE --engine local           # Qwen
 python3 formula_img2latex.py verify    AUSGABE                          # prüfen und entscheiden
-python3 formula_img2latex.py recognize AUSGABE --engine local2 --only-unresolved   # Gemma (Stichwahl)
+python3 formula_img2latex.py recognize AUSGABE --engine local2 --only-unresolved   # Gemma
 python3 formula_img2latex.py verify    AUSGABE
-python3 formula_img2latex.py status    AUSGABE
+python3 formula_img2latex.py status    AUSGABE                          # Zählung je Status (--json)
 ```

-Nützliche Optionen:
+| Option | Befehle | Wirkung |
+|---|---|---|
+| `--limit 50` | run, recognize | nur die ersten 50 Bilder (zum Ausprobieren) |
+| `--chunk 100` | run | Paketgröße (Standard 50) |
+| `--pdf BUCH.pdf` | run, scan | pdf2md: Original-PDF für scharfe Neuausschnitte |
+| `--preset cm` | run, verify | Schrift für den Bildabgleich fest vorgeben (`cm`, `times`, `txfonts`, `palatino`, `stix`, `euler`); Standard: automatisch je Buch |
+| `--include-figures` | run, recognize, verify | auch Bilder versuchen, die wie Abbildungen aussehen |
+| `--model NAME`, `--url URL` | run, recognize | anderes Modell bzw. anderer Server |
+| `--workers N` | run, recognize, verify | parallele Anfragen bzw. Prüfprozesse |
+| `--redo` | verify | bereits geprüfte Formeln neu prüfen |
+| `--workspace ORDNER` | alle außer calibrate | Arbeitsordner an anderem Ort |
+| `--quiet`, `-q` | alle | nur Fehler ausgeben |

-| Option | Wirkung |
-| --- | --- |
-| `--limit 50` | nur die ersten 50 Bilder (zum Ausprobieren) |
-| `--preset cm` | Schrift fest vorgeben (`cm`, `times`, `txfonts`, `palatino`, `stix`, `euler`); Standard: automatisch |
-| `--include-figures` | auch Bilder versuchen, die wie Abbildungen aussehen |
-| `--model NAME` | anderes Modell (lokal: Servername, Cloud: OpenRouter-ID) |
-| `--workspace ORDNER` | Arbeitsordner an anderem Ort |
-| `--redo` (verify) | bereits geprüfte Formeln neu prüfen, z. B. nach einem Programm-Update |
+Alle Optionen: `python3 formula_img2latex.py BEFEHL --help`.

 ---

-## 4. Häufige Fragen
+## 5. Konfiguration
+
+### Umgebungsvariablen
+
+| Variable | Standard | Wirkung |
+|---|---|---|
+| `FORMULA_LOCAL_URL`, `FORMULA_LOCAL_MODEL` | `http://127.0.0.1:8011/v1`, Modell des Servers | Qwen-Server |
+| `FORMULA_LOCAL2_URL`, `FORMULA_LOCAL2_MODEL` | `http://127.0.0.1:8012/v1`, Modell des Servers | Gemma-Server |
+| `FORMULA_LOCAL_API_KEY`, `FORMULA_LOCAL2_API_KEY` | – | falls der Server einen Schlüssel verlangt |
+| `FORMULA_P2T_DEVICE` | `auto` | pix2text: `auto`, `cpu` oder `cuda:N` (`N` zählt innerhalb von `CUDA_VISIBLE_DEVICES`) |
+| `FORMULA_P2T_MODEL` | `mfr-1.5` | pix2text-Modell |
+| `FORMULA_CLOUD_URL`, `FORMULA_CLOUD_MODEL` | `https://openrouter.ai/api/v1`, `z-ai/glm-4.6v` | nur Regel `vlm3` |
+| `OPENROUTER_API_KEY` | – | nur Regel `vlm3` |
+| `FORMULA_LOCAL_THINKING`, `FORMULA_LOCAL2_THINKING`, `FORMULA_CLOUD_THINKING` | `0` | `1` schaltet das „Nachdenken“ der Modelle wieder ein |
+| `FORMULA_STRUCTURAL` | `0` | `1` schaltet den Strukturvergleich mit sympy ein |
+
+### Einstellungen je Buch (`workspace.json`)
+
+Im Arbeitsordner unter `settings`, zum Beispiel:
+
+```json
+{
+ "settings": {
+  "consensus_rule": "p2t",
+  "consensus_thresholds": {"veto_ncc": 0.65, "bold_relevant": 0}
+ }
+}
+```
+
+| Schlüssel | Werte | Wirkung |
+|---|---|---|
+| `consensus_rule` | `p2t` (Standard), `vlm3` | Regel `vlm3`: Qwen = Gemma, bestätigt von GLM-4.6V über OpenRouter (bis 0.2.0) |
+| `decide` | `consensus` (Standard), `pixel` | `pixel`: alter Pixel-Entscheider (bis 0.1.0) |
+| `consensus_thresholds` | siehe [FUNKTIONSWEISE.md, Schwellen](FUNKTIONSWEISE.md#schwellen-settingsconsensus_thresholds-in-workspacejson) | Veto-Schwelle, Fettdruck, Schiedsrichter, PDF-Textebene … |
+| `preset` | wird beim ersten Prüfen gesetzt | Schrift für den Bildabgleich |
+
+Nach einer Änderung `verify` aufrufen; die Modelle werden nicht neu gefragt.
+
+---
+
+## 6. Betrieb
+
+**Dauer:** etwa 0,8 s je Formel, also 35–50 Sekunden je Paket (Corral mit `--formulas`: 940 Formeln in
+13 Minuten, das ganze Buch mit 9239 Formeln rund 2 Stunden). Am längsten braucht die Bestätigung durch
+Qwen. Der Scan liest beim ersten Mal alle Bilder ein (Corral: 6 Minuten); beim Fortsetzen entfällt er,
+solange sich das Markdown nicht geändert hat.
+
+**Abbrechen und fortsetzen:** Strg+C und erneut `run` ist kein Problem. Bereits gelesene Formeln werden
+nicht noch einmal gefragt; fehlgeschlagene Anfragen werden wiederholt.
+
+**Neu umgewandeltes Buch:** Nach `epub2md --force` erst `scan`, dann `apply`. Die Entscheidungen hängen am
+Bildinhalt und bleiben erhalten.
+
+**Arbeitsordner:** `<ausgabe>.formulas/` neben der Ausgabe. Er enthält die Datensätze, Ausschnitte,
+Vergleichsbilder und die Sicherung von `apply`. Aufbau: [FUNKTIONSWEISE.md, Arbeitsordner](FUNKTIONSWEISE.md#3-arbeitsordner-und-datensätze).
+
+**Datenschutz:** Mit der Standardregel verlässt nichts den Rechner. Die Regel `vlm3` schickt Formelbilder,
+bei denen Qwen und Gemma einig sind, samt eines kurzen Textausschnitts um die Formel (höchstens 240
+Zeichen) an OpenRouter; beim Gehrke-Brückenkurs waren das 967 Anfragen für zusammen rund 0,15–0,20 $.
+
+---
+
+## 7. Werkzeuge zum Messen und Einstellen
+
+Die Werkzeuge schreiben nach `vergleich/` bzw. in den Arbeitsordner; beides wird nicht ins Git übernommen
+(Buchausschnitte).
+
+| Werkzeug | Zweck |
+|---|---|
+| `tools/vergleich.py AUSGABE` | feste Stichprobe von 50 Formeln eines Buchs, verarbeitet wie `run`; Seite `vergleich/<name>/index.html` mit Original, gerenderten Lesarten, Entscheidung und Bildabgleich |
+| `tools/buch_bericht.py AUSGABE` | Ergebnisseite eines ganzen Buchs nach `run`, filterbar; liegt in `<arbeitsordner>/bericht/index.html` |
+| `tools/regeltest.py EPUB [--n 50] [--reuse …] [--refresh local,local2]` | Standardregel an Formeln mit bekanntem TeX, wie `run`; Seite mit wahrer Formel, allen Lesarten und Urteil |
+| `tools/zeittest.py EPUB` | Zeit und Trefferquote je Erkenner, seriell an 15 Formeln mit bekanntem TeX |
+| `tools/vergleich_bericht.py --regeltest VORHER:NACHHER` | Vorher/Nachher-Seite zweier Läufe auf denselben Lesarten |
+| `tools/konsens_bericht.py BERICHT.json EPUB` | Übersichtsseite zu `calibrate --consensus --report` |
+| `formula_img2latex.py calibrate --consensus --engines local,local2,cloud,p2t --report X.json EPUB` | alle Regeln an Formeln mit bekanntem TeX messen; `--reuse X.json` rechnet ohne Modellabfragen neu, `--synthetic` erzeugt zusätzlich Gehrke-ähnliche Nachbildungen |
+
+Formeln mit bekanntem TeX liefern Springer-EPUBs, die das TeX jeder Formel im alt-Text tragen (z. B.
+Göllmann).
+
+---
+
+## 8. Fehlersuche
+
+| Meldung oder Beobachtung | Ursache | Abhilfe |
+|---|---|---|
+| `Lokaler Modellserver unter http://127.0.0.1:8011/v1 nicht erreichbar` | Qwen-Server läuft nicht | Server starten ([2](#2-modellserver-starten-und-beenden)) |
+| `Stichwahl (Gemma) nicht möglich, strittige Formeln bleiben im Review` | Gemma-Server läuft nicht | Gemma starten und `run` erneut aufrufen |
+| Gemma bricht beim ersten Bild mit „out of memory“ ab | GPU 2 ist belegt | Chatterbox-TTS und STT stoppen ([2](#2-modellserver-starten-und-beenden)) |
+| `pix2text ist nicht installiert` / `pix2tex ist nicht installiert` | Pakete fehlen | Befehle aus [1](#pix2text-formel-ocr) ausführen |
+| `onnxruntime ohne CUDA – pip install onnxruntime-gpu` | nur die CPU-Version von onnxruntime | `pip uninstall -y onnxruntime && pip install onnxruntime-gpu` |
+| pix2text sehr langsam | läuft auf der CPU | `onnxruntime-gpu` installieren oder `FORMULA_P2T_DEVICE=cuda:0` |
+| `pdflatex nicht gefunden` / `pandoc nicht gefunden` | TeX Live bzw. Pandoc fehlen | `sudo apt install texlive-latex-extra pandoc` |
+| `Kein Arbeitsordner gefunden … (zuerst 'scan' ausführen)` | `verify`, `apply` usw. vor dem ersten `scan`/`run` | `scan` oder `run` ausführen |
+| `… ist weder eine epub2md-Ausgabe … noch eine pdf2md-Ausgabe` | falscher Pfad | epub2md-Ordner bzw. pdf2md-`.md`-Datei angeben |
+| `Arbeitsordner existiert und ist kein formula_img2latex-Ordner` | Zielordner von `--workspace` belegt | anderen Ordner wählen |
+| `Bildverweis nicht mehr gefunden: datei.md:123` | Markdown wurde neu erzeugt oder von Hand geändert | `scan` ausführen |
+| `revert` überspringt Dateien | seit `apply` von Hand geändert | prüfen, dann `revert --force` |
+| `OPENROUTER_API_KEY ist nicht gesetzt` | Regel `vlm3` oder `--engine cloud` ohne Schlüssel | Schlüssel setzen oder Regel `p2t` verwenden |
+| Formel bleibt in EPUB/PDF als TeX-Text stehen | Pandoc konnte sie nicht umsetzen (sollte die Pandoc-Prüfung verhindern) | Formel im Review korrigieren, Fall melden |
+
+**Rückgabecodes:**
+
+| Code | Bedeutung |
+|---|---|
+| 0 | Erfolg |
+| 1 | Bedienfehler: Parameter, Eingabe oder Arbeitsordner nicht lesbar oder belegt |
+| 2 | Eingabe ist keine epub2md- oder pdf2md-Ausgabe |
+| 3 | Externes Werkzeug fehlt oder versagt: pdflatex, pandoc, Modellserver, pix2text |
+| 4 | Unerwarteter interner Fehler (Traceback wird ausgegeben) |
+
+---
+
+## 9. Häufige Fragen

 **Das Buch wurde mit epub2md `--force` neu umgewandelt. Ist meine Arbeit weg?**
 Nein. Die Entscheidungen hängen am Inhalt der Bilder, nicht an Dateinamen. `scan`, dann `apply`.

 **Warum landet ein Teil im Review?**
 Ersetzt wird nur, was pix2text liest und Qwen (oder bei Uneinigkeit Gemma) bestätigt. Sind Qwen und Gemma
-gemeinsam anderer Meinung als pix2text, entscheidest du. Häufige Gründe für Review: ein Modell liest ein
-Zeichen anders (oft pix2text: `\nu` statt fettem v, Wörter wie „fir“ statt „für“), sehr kleine oder
-unscharfe Bilder, mehrzeilige Rechnungen mit anderen Zeilenumbrüchen oder `\underbrace`. Verschiedene
-Rahmen derselben Zeilen (`aligned`, `cases`, `&`) gelten seit 0.4.0 als gleich. Im Review stehen die Lesarten
+gemeinsam anderer Meinung als pix2text, entscheidest du. Häufige Gründe: ein Modell liest ein Zeichen anders
+(oft pix2text: `\nu` statt fettem v, Wörter wie „fir“ statt „für“), sehr kleine oder unscharfe Bilder,
+mehrzeilige Rechnungen mit anderen Zeilenumbrüchen oder `\underbrace`. Im Review stehen die Lesarten
 nebeneinander; oft genügt ein Blick und „LaTeX übernehmen“.

 **Wie sicher ist „automatisch ersetzt“?**
-Gemessen an 300 Formeln mit bekannter Lösung: keine einzige falsche Formel wurde angenommen (Fehlerquote
-sehr wahrscheinlich unter 2 %). Am Gehrke-Brückenkurs wurden 62 automatisch ersetzte Formeln von Hand
-geprüft, alle korrekt. Fettdruck wird bewusst nicht geprüft: Ein fetter Vektor **v** kann als normales v
-übernommen werden.
+An einigen hundert Formeln mit bekannter Lösung wurde keine falsche Formel angenommen (Fehlerquote sehr
+wahrscheinlich unter 2 %). Fettdruck wird bewusst nicht geprüft: Ein fetter Vektor **v** kann als normales
+v übernommen werden. Messungen: [FUNKTIONSWEISE.md](FUNKTIONSWEISE.md#12-messungen).

 **Ich will erst ein paar Formeln ansehen, bevor das ganze Buch läuft.**
-`python3 tools/vergleich.py AUSGABE` verarbeitet eine feste Stichprobe von 50 Formeln genau wie `run`
-und schreibt `vergleich/<name>/index.html`: Originalbild, die gerenderten Lesarten aller Modelle, die
-Entscheidung mit Grund und den Bildabgleich. Der Ordner `vergleich/` wird nicht ins Git übernommen.
+`python3 tools/vergleich.py AUSGABE` verarbeitet eine feste Stichprobe von 50 Formeln genau wie `run` und
+schreibt `vergleich/<name>/index.html`.

 **Geht die blaue Hinterlegung mancher Formeln verloren?**
 Ja. Das Bild hatte die Farbe eingebaut, LaTeX-Formeln haben keinen Hintergrund.
-
-**Werden Buchinhalte ins Internet geschickt?**
-Nein, mit der Standardregel bleibt alles lokal. Nur die frühere Regel `vlm3` schickt die Formelbilder, bei
-denen Qwen und Gemma einig sind, samt eines kurzen Textausschnitts um die Formel (höchstens 240 Zeichen)
-an OpenRouter/GLM.