# 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) ```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 ``` ### 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. ### pix2text (Formel-OCR) pix2text läuft ohne Server im Programm selbst, auf der ersten sichtbaren Grafikkarte (sonst auf der CPU, dann ~5× langsamer). 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 ``` 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`). 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 ```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, siehe oben): ```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 zusätzlich die Original-PDF angeben. Dann schneidet das Programm jede Formel scharf aus dem PDF: ```bash 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 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, beim Gehrke-Brückenkurs 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 ``` 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, 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. „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 ```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}$,`). 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: ```bash 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 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 ```bash 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` ```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 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: 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 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//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.