formula_img2latex/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung formula_img2latex

Dieses Programm ersetzt Formelbilder in den Markdown-Dateien von epub2md und pdf2md durch echte
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. 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. Wie das intern geprüft wird, steht in
[FUNKTIONSWEISE.md](FUNKTIONSWEISE.md).

---

## 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
cd ~/Python_Programs/formula_img2latex
pip install -r requirements.txt
python3 formula_img2latex.py --version
```

- **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. Einmalig:

```bash
pip install "pix2text[multilingual]"
pip install --no-deps pix2tex munch                            # nur für post_process (Leerzeichen)
pip uninstall -y onnxruntime && pip install onnxruntime-gpu   # für die GPU
```

`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.

### Modelle für die Bildmodelle

| 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/` |

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. Modellserver starten und beenden

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
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):

```bash
cd ~/Python_Programs/pdf2md
python3 pdf2md.py --formulas --epub buch.pdf Output/buch/buch.md
```

Das dauert bei 350 Seiten gut 10 Minuten (Corral: 9239 Formeln).

### Schritt 2: Formeln erkennen und prüfen

```bash
cd ~/Python_Programs/formula_img2latex
python3 formula_img2latex.py run ~/Python_Programs/epub2md/output/buch
```

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 ~/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
Stufe (die Stufen laufen teils gleichzeitig, daher ist die Summe größer als die Paketzeit):

```text
  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, zum Beispiel:

```text
  auto_accepted               942     ← Lesart bestätigt, wird ersetzt
  needs_review                478     ← bitte im Browser ansehen
  not_formula                  93     ← laut Modellen keine Formel
  pending                     539     ← Abbildungen/Symbole, nicht geprüft
```

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

```bash
python3 formula_img2latex.py review ~/Python_Programs/epub2md/output/buch
```

Der Browser öffnet `http://127.0.0.1:8765/`. Für jede Formel siehst du:

- **Original:** das Bild aus dem Buch.
- **Overlay:** Original und LaTeX übereinander. Mit dem Regler blendest du zwischen beiden. Springt etwas,
  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. „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 |
| Keine Formel | das Bild ist eine Abbildung oder ein Symbol |
| 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, `--port` ändert den Port,
`--no-browser` öffnet keinen Browser.

### Schritt 4: Formeln ins Markdown schreiben

```bash
python3 formula_img2latex.py apply ~/Python_Programs/epub2md/output/buch --dry-run   # nur zählen
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}$,`). In deutschen
Büchern werden Dezimalzahlen zu `3{,}6`; eine Gleichungsnummer steht als Text hinter der Formel.

**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
cd output/buch && P=~/Python_Programs/epub2md/pandoc
pandoc buch.md --toc --mathml --lua-filter $P/callouts.lua -o buch.epub

# pdf2md: EPUB mit allen Formeln als MathML
cd ~/Python_Programs/pdf2md && python3 pdf2md.py --from-md Output/buch/buch.md
```

### Rückgängig machen

```bash
python3 formula_img2latex.py revert ~/Python_Programs/epub2md/output/buch
```

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.

---

## 4. Einzelne Schritte und Optionen

```bash
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
python3 formula_img2latex.py verify    AUSGABE
python3 formula_img2latex.py status    AUSGABE                          # Zählung je Status (--json)
```

| 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 |

Alle Optionen: `python3 formula_img2latex.py BEFEHL --help`.

---

## 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: 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“?**
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`.

**Geht die blaue Hinterlegung mancher Formeln verloren?**
Ja. Das Bild hatte die Farbe eingebaut, LaTeX-Formeln haben keinen Hintergrund.