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 ersetzt eine Formel nur, wenn das gerenderte LaTeX genauso aussieht wie das Bild. Bei Zweifeln fragt es dich in einer Review-Seite im Browser. Ohne deine Zustimmung bleibt die Formel ein Bild.

---

1. Einrichtung (einmalig)

sudo apt install texlive-latex-extra texlive-fonts-extra texlive-science pandoc
cd ~/Python_Programs/formula_img2latex
pip install -r requirements.txt
python3 formula_img2latex.py --version

Lokales Bildmodell starten

Die Formelerkennung macht ein Vision-Sprachmodell. Lokal läuft es mit llama.cpp auf einer Grafikkarte:

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

Der Server belegt etwa 20 GB auf GPU 1. Beenden mit Strg+C.

Cloud-Stufe (optional)

Formeln, die lokal nicht sicher erkannt werden, kann ein Cloud-Modell über OpenRouter versuchen. Dafür muss OPENROUTER_API_KEY gesetzt sein. Ein Buch mit 2000 Formeln kostet mit dem Standardmodell google/gemini-2.5-flash deutlich unter 1 $. Ohne Cloud: --no-cloud.

---

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

Am Ende steht eine Übersicht, zum Beispiel:

  auto_accepted               412     ← sicher, wird ersetzt
  needs_review                380     ← bitte im Browser ansehen
  rejected_keep_image          95     ← passt nicht, bleibt Bild
  not_formula                 117     ← Abbildung/Symbol

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, darunter eventuell weitere Kandidaten zum Anklicken.

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.

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 local           # lokal erkennen
python3 formula_img2latex.py verify    AUSGABE                          # prüfen und entscheiden
python3 formula_img2latex.py recognize AUSGABE --engine cloud --only-unresolved
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 so viel im Review? Das Programm ersetzt nur, was es beweisen kann. Häufige Gründe: Das Bild ist sehr klein (Ziffern unter 8 Pixeln). Das Buch wurde mit einem anderen Satzsystem gesetzt. Oder die Erkennung schreibt eine Formel typografisch anders (\vec statt langem Pfeil). Im Review genügt dann meist ein Blick auf das Overlay.

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

Werden Buchinhalte ins Internet geschickt? Nur mit der Cloud-Stufe, und nur die einzelnen Formelbilder samt eines kurzen Textausschnitts davor. Mit --no-cloud bleibt alles lokal.