macOS Vision 本地 OCR

macOS Vision Lokale OCR

Dieses Skill führt dich durch die Umwandlung von vom Benutzer bereitgestellten Bildern/PDFs in Text: Es verwendet die systemeigene Vision-Engine von macOS (macocr Befehl) zur lokalen Erkennung, ohne Daten hochzuladen.

Umgebungsprüfung (muss zuerst ausgeführt werden)

Führe vor jedem OCR-Aufruf die folgenden Prüfungen durch. Wenn eine davon nicht erfüllt ist, brich ab und antworte entsprechend:

[ "$(uname -s)" = "Darwin" ] && echo OK-macOS
command -v macocr || ls "$HOME/.local/bin/macocr"

• uname ist nicht Darwin: Dieses Tool funktioniert nur unter macOS. Versuche nicht es zu installieren oder zu kompilieren. Teile dem Benutzer mit, dass dieses Skill nur unter macOS verfügbar ist, und empfehle eine andere OCR-Lösung.
• macocr existiert nicht: Führe den Benutzer durch die Installation mit ./install.sh im Skill-Verzeichnis (Kompilierung benötigt Xcode Command Line Tools; auf Apple Silicon ohne Kompilierungsumgebung wird automatisch auf das mitgelieferte vorkompilierte Binary zurückgegriffen). Nach der Installation führe sh scripts/selftest.sh für einen End-to-End-Selbsttest durch. Danach kann fortgefahren werden.

Nach abgeschlossener Installation und Selbsttest muss dieser Schritt nicht pro Sitzung wiederholt werden.

Standardablauf für Aufgaben

Bearbeite die OCR-Anfrage des Benutzers schrittweise, ohne Schritte zu überspringen:

1. Eingabetyp bestätigen. Handelt es sich um ein Bild (png/jpg/jpeg/heic/tiff), gehe direkt zu Schritt 3. Handelt es sich um ein gescanntes PDF (ohne Textschicht), gehe zu Schritt 2 für die Bildkonvertierung.

2. PDF in Bild umwandeln (nur für gescannte PDFs nötig). Verwende das systemeigene sips für die Rasterung, beginnend mit 144 dpi:

   sips -s format png -s dpiHeight 144 -s dpiWidth 144 eingabe.pdf --out /tmp/p1.png
   

   Hinweis: sips verarbeitet nur einzelne Seiten. Bei mehrseitigen PDFs muss jede Seite einzeln angegeben werden, oder wenn pymupdf verfügbar ist, verwende eine 4-fache Matrix-Rasterung (bessere Ergebnisse bei kleinem Schriftgrad, siehe "Verwendung mit gescannten PDFs").

3. Erkennung ausführen. Der Standardbefehl deckt die meisten Szenarien ab:

   macocr <Bildpfad>            # Mehrere Bilder können nacheinander aufgelistet werden, Ausgabe getrennt durch ===
   

   Füge je nach Szenario Parameter hinzu (siehe Parametertabelle unten). Die Erkennung gibt reinen Text aus, bereits visuell zeilenweise sortiert.

4. Ergebnis ausliefern. Zeige dem Benutzer den erkannten Text direkt an. Bei tabellarischen oder zahlenreichen Ergebnissen muss der Benutzer darauf hingewiesen werden, wichtige Zahlen doppelt zu prüfen (siehe "Besondere Hinweise zu Tabellendaten").

Parameterübersicht

Parameter	Verwendung
--fast	Deaktiviert Sprachkorrektur. Empfohlen für Tabellen und Zahlen, um zu verhindern, dass Zahlen in merkwürdige Werte "korrigiert" werden
--lang zh-Hans+en-US	Standard für gemischt Chinesisch/Englisch. Nur Englisch auf en-US setzen für Geschwindigkeit; Traditionell Chinesisch mit zh-Hant
--rect x,y,w,h	Erkennt nur einen rechteckigen Bereich (Ursprung oben links, in Pixeln). Verwende dies, um in großen Bildern nur eine bestimmte Tabelle zu extrahieren
--upscale N	Vergrößert unscharfe kleine Bilder (Breite < 1000px bei weitergeleiteten Bildern, alten Scans) zuerst mit Lanczos um Faktor N (1.0–4.0). Nur wenn die normale Erkennungsrate schlecht ist, schrittweise 2 → 3 versuchen. Bei klaren, großen Bildern führt blindes Hochskalieren zu verschmierten Strichen
--orientation up|left|right|180	Dreht das Bild manuell bei schrägen Fotos oder gedrehten Bildern. Vision korrigiert nicht automatisch anhand von EXIF, daher bei seitlich aufgenommenen Fotos zwingend erforderlich
--list-langs	Listet die vom System unterstützten Erkennungssprachen auf (für Installations-Selbsttest, Ausgabe sollte zh-Hans enthalten)

Vorgehen bei niedriger Erkennungsrate

Probiere die Schritte in aufsteigender Kostenordnung, ohne sofort komplexe Methoden zu verwenden:

1. Originalbild besorgen: Bei extrem niedriger Erkennungsrate von weitergeleiteten Bildern bitte den Benutzer um die Originaldatei
2. --rect Zielbereich eingrenzen, um Störungen zu reduzieren
3. --upscale 2 (bei unscharfen kleinen Bildern)
4. --fast (bei Tabellen/Zahlen)
5. Bildvorverarbeitung (Zuschneiden + Graustufen + Automatischer Kontrast + Schärfen + Binarisierung), Beispiel unten:

from PIL import Image, ImageOps, ImageEnhance
im = Image.open("src.JPG")
im.crop((x0, y0, x1, y1)).resize((w*2, h*2), Image.LANCZOS)   # Zuschneiden + Vergrößern
ImageOps.autocontrast(im.convert("L"))                         # Graustufen + Automatischer Kontrast
ImageEnhance.Sharpness(im).enhance(2.0)                        # Schärfen
im.convert("L").point(lambda p: 255 if p > 128 else 0)         # Binarisierung

Mehrere Versionen zur Abstimmung: Führe für dieselbe Tabelle 2–3 Vorverarbeitungen durch, nimm die übereinstimmenden Teile, prüfe abweichende Zahlen einzeln. Kreuzvalidierung: Wenn sich ganze Zeilen/Spalten aufsummieren lassen, ist das Ergebnis glaubwürdig; wenn nicht, ist eine Zahl falsch.

Warum sieht der Live-Text der Fotos-App genauer aus als die reine API?

Beide verwenden die gleiche Vision-Engine, der Unterschied liegt in der Vor- und Nachverarbeitung, nicht im Modell selbst:

1. Ausrichtung: Die Fotos-App korrigiert nach EXIF, bevor sie erkennt; die reine API verarbeitet standardmäßig als .up → mit --orientation nachhelfen
2. Auflösung: Die Fotos-App verwendet das Original in voller Auflösung; im Workflow laufen oft komprimierte Vorschaubilder um → immer die Originaldatei bevorzugen
3. Implizites Downsampling: NSImage gibt Bilder in "Punkten" aus, @2x/@3x Screenshots und manche HEIC verlieren die Hälfte der Pixel → dieses Tool iteriert über Repräsentationen, um die Bitmap mit der höchsten Auflösung zu verwenden
4. Vertikaler Text: Live-Text kann vertikalen Text verarbeiten; die reine API zerbricht ihn in kurze Fragmente → dieses Tool erkennt dies automatisch und führt eine Konfidenzabstimmung durch
5. Interaktionsvorteil (nicht vollständig replizierbar): Live-Text erlaubt punktuelles Auswählen, was subjektiv "weniger Fehler" bedeutet; die CLI gibt den gesamten Text auf einmal aus, sodass jeder Fehler auffällt

Fazit: Gleiche Engine, die Pipeline bestimmt die Obergrenze.

Besondere Hinweise zu Tabellendaten

OCR macht bei Tabellen am häufigsten Fehler: Dezimaltrennzeichen werden verschluckt (. → ,), benachbarte Spalten verschmelzen, Zeilen werden verwechselt. Wichtige Zahlen müssen doppelt geprüft werden: Wenn ein PDF-Original vorhanden ist, extrahiere die Textschicht zum Vergleich; bei nur einem Foto hilft die Abstimmung mehrerer Versionen + logische Zeilen-/Spaltenprüfung.

Wann dieses Tool nicht verwendet werden sollte

Szenario	Bessere Wahl
Das verwendete KI-Modell kann selbst Bilder lesen	Lass es direkt auf das Bild schauen, ohne OCR
Komplexe Layout-Wiederherstellung erforderlich (mehrspaltig, Formeln, Tabellenrahmen)	MinerU oder andere Layout-Parser (Daten gehen in die Cloud)
Stapelverarbeitung ganzer gescannter PDFs in Text, Cloud erlaubt	Batch-Schnittstellen von Cloud-OCR-Diensten

Regel: Lokal zuerst, keine Daten nach außen; erst bei höherer Genauigkeit in die Cloud gehen, und nur wenn die Datenweitergabe geklärt ist.

Validierung & Fehlerbehebung

• Selbsttest nach Installation: sh scripts/selftest.sh (End-to-End-Prüfung mit mitgelieferten Testbildern, Ausgabe PASS/FAIL)
• Sprachliste enthält kein zh-Hans: Systemsprachdaten unvollständig, sehr selten; prüfe, ob macOS-Version ≥ 13 ist
• Ausgabe leer oder komplett falsch: Zuerst prüfen, ob das Bild selbst lesbar ist (sips -g pixelWidth -g pixelHeight bild), dann schrittweise das "Vorgehen bei niedriger Erkennungsrate" durchgehen

Systemanforderungen

• macOS 13+ (automaticallyDetectsLanguage benötigt 13.0)
• Kompilierung benötigt Xcode Command Line Tools (xcode-select --install); oder verwende das mitgelieferte vorkompilierte Binary für Apple Silicon (scripts/macocr-arm64, ad-hoc signiert)

Dateibeschreibungen im Paket

Datei	Verwendung	Wann nötig
install.sh	Installiert macocr (Kompilierung bevorzugt, vorkompiliertes Binary als Fallback)	Wenn die Umgebungsprüfung ergibt, dass macocr nicht existiert
scripts/selftest.sh + scripts/selftest.png	End-to-End-Selbsttest (Skript + eigenes Testbild)	Nach Installation zur Validierung; bei "Erkennungsanomalien" zuerst ausführen, um sicherzustellen, dass das Tool selbst funktioniert
scripts/vision_ocr.swift	Quellcode (ca. 200 Zeilen, prüfbar)	Wenn eine eigene Kompilierung oder Prüfung erforderlich ist
scripts/macocr-arm64	Vorkompiliertes Binary für Apple Silicon	Auf Apple Silicon-Maschinen ohne swiftc; wird automatisch von install.sh verwendet