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

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

---

1. Einrichtung (einmalig)

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

Die beiden lokalen Bildmodelle starten

Zwei Vision-Sprachmodelle lesen jede Formel, je eines pro Grafikkarte (je ~18–21 GB). In zwei Terminals:

# 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 16384 --parallel 4

# 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

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:

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.

pix2text (Formel-OCR)

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

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

Das Modell (~300 MB) wird beim ersten Lauf nach ~/.pix2text geladen. Gerät wählen mit FORMULA_P2T_DEVICE=cpu oder cuda:N (N zählt innerhalb von CUDA_VISIBLE_DEVICES).

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.

Frühere Regel mit Cloud (optional)

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.

---

2. Ein Buch bearbeiten

Schritt 1: Buch wie gewohnt umwandeln

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.

Schritt 2: Formeln erkennen und prüfen

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:

python3 formula_img2latex.py run Output/buch.md --pdf buch.pdf

Das Programm arbeitet in Paketen zu 50 Formeln und meldet nach jedem Paket den Stand:

  100/1505 verarbeitet: automatisch ersetzt 68 (68%), Review 28, bleibt Bild/keine Formel 4

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

  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

Dauer: Mit der früheren Regel (Version 0.2.0, mit GLM) etwa 5 Minuten je 50 Formeln, ein Buch mit 1500 Formelbildern also rund 2,5 Stunden. Mit der jetzigen Regel liest pix2text eine Formel in ~0,15 s und Qwen in ~0,8 s, Gemma nur bei Uneinigkeit; an 2 × 50 Testformeln dauerte das Lesen im Mittel 1,5–2,3 s je Formel (ohne Bildprüfung). Ein ganzes Buch ist damit noch nicht gemessen. 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, solange du am Buch arbeitest.

Schritt 3: Zweifelsfälle im Browser entscheiden

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. „Modelle uneinig“ mit den abweichenden Lesarten.

Schaltflächen:

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.

Schritt 4: Formeln ins Markdown schreiben

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.

Danach die Gesamtdatei neu bauen, sie enthält sonst noch die Bilder:

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

cd ~/Python_Programs/epub2md/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.

Rückgängig machen

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.

---

3. Einzelne Schritte statt run

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 verify    AUSGABE                          # prüfen und entscheiden
python3 formula_img2latex.py recognize AUSGABE --engine local2 --only-unresolved   # Gemma (Stichwahl)
python3 formula_img2latex.py verify    AUSGABE
python3 formula_img2latex.py status    AUSGABE

Nützliche Optionen:

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

---

4. 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: mehrzeilige Rechnungen mit Ausrichtung, \underbrace oder Zeilenumbrüchen (die Modelle schreiben sie unterschiedlich), sehr kleine oder unscharfe Bilder, oder ein Modell liest ein Zeichen anders. 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.

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.

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.