Handschrift → PDF

Was macht Handschrift → PDF?

Erstellen Sie einen echten .ttf aus einer Handschriftprobe und render dann Text damit in ein PDF, das wie die eigene Handschrift des Schreibers aussieht. Alles läuft lokal; die Probe verlässt nie den Rechner.

Harte Wahrheit, die dem Benutzer gleich zu Beginn gesagt werden muss: Dies ist keine KI, die aus einem Foto 3.000 chinesische Glyphen erfindet. Ein Font kann nur die Zeichen enthalten, die tatsächlich auf der Probe geschrieben wurden. Also: Lateinischer Text benötigt ~60–100 geschriebene Zeichen; chinesischer Text benötigt jedes einzelne Zeichen des Dokuments (ein paar Hundert ist normal, Tausende ist unpraktisch). Fehlende Zeichen werden mit einem neutralen handschriftlichen Fallback gezeichnet und gemeldet – niemals stillschweigend erfunden.

0. Das Werkzeug finden

Das Skill-Verzeichnis ist der Ordner, der diese SKILL.md enthält. Rufen Sie die CLI über den Launcher auf:

• Windows: <skill>\bin\hwpdf.cmd <Befehl> ...
• macOS/Linux: <skill>/bin/hwpdf <Befehl> ...

Wenn der Launcher fehlt, installieren Sie ihn zuerst (<skill>\install.ps1 auf Windows, <skill>/install.sh anderswo) oder führen Sie python <skill>/scripts/hwpdf.py <Befehl> ... aus, wenn die Abhängigkeiten bereits vorhanden sind. hwpdf doctor muss status ok ausgeben, bevor etwas anderes gemacht wird; wenn nicht, führen Sie das Installationsprogramm aus und melden Sie den Abhängigkeitsfehler, anstatt Improvisationen zu starten.

1. Den Aufnahmeweg wählen

Situation	Ablauf
Standard: Benutzer möchte ein echtes Dokument in seiner Handschrift	A. Übungsblatt (beste Qualität, vollautomatische Zellenzuordnung)
Benutzer übergibt ein PDF, das bereits seine Handschrift zeigt	D. PDF-Übernahme – zuerst den eingebetteten Font versuchen, sonst Glyphen aus der Textebene ernten
Benutzer hat bereits ein Foto seiner Handschrift gesendet und möchte nicht mehr schreiben	B. Freiform-Foto (Agent beschriftet die ausgeschnittenen Glyphen)
Benutzer hat bereits eine eigene .ttf/.otf	C. Nur Font – überspringen Sie zu Schritt 4, dann ein Profil speichern

Fragen Sie nach dem Dokumenttext, bevor Sie etwas generieren: Das Übungsblatt benötigt nur die Zeichen, die das Dokument verwendet, ein kurzer Text bedeutet also ein kurzes Blatt.

Ablauf A — Übungsblatt (empfohlen)

1. Speichern Sie den Zieltext in einer UTF-8-Datei, z.B. hw/doc.txt, dann:

   hwpdf template --text-file hw/doc.txt -d hw
   

   Dies schreibt hw/template.pdf (und hw/template.json). 30 Zellen pro Seite, eine Seite pro 30 verschiedene Zeichen. Sagen Sie dem Benutzer genau dies:
   • Drucken Sie bei 100 % / Tatsächlicher Größe (niemals „Auf Seite skalieren“);
   • Zeichnen Sie jede hellgraue Glyphe mit einem dunklen Stift nach (0,5 mm oder dicker) – ein Kugelschreiber ist zu hell;
   • Lassen Sie die vier schwarzen Eckenquadrate sichtbar und unbezeichnet;
   • Fotografieren Sie jede Seite von oben bei gleichmäßigem Licht, füllen Sie den Rahmen und senden Sie die Dateien.
2. Scannen Sie die Fotos in Seitenreihenfolge:

   hwpdf scan hw/page1.jpg hw/page2.jpg -d hw
   

   Perspektive und kleine Drehungen werden anhand der Eckquadrate korrigiert. Ausgabe: hw/glyphs.json und hw/glyphs/*.png. Wenn eine Zelle als „fehlend“ zurückkommt, wurde die Glyphe nicht geschrieben oder war zu blass – geben Sie an, welche Zeichen das sind, und bieten Sie eine Neuaufnahme nur dieser Zellen an.
3. Bauen Sie den Font:

   hwpdf font -d hw --family "Alex Hand" -o hw/font.ttf
   

4. Überprüfen Sie die Abdeckung vor dem Rendern:

   hwpdf coverage --font hw/font.ttf --text-file hw/doc.txt
   

   Bei einem Exit-Code ungleich Null / einer Liste von missing haben diese Zeichen keine Glyphe. Beheben Sie das, indem Sie ein kleines zweites Blatt nur für diese Zeichen schreiben und es einfügen:

   hwpdf template --chars "<fehlende Zeichen>" -d hw2
   hwpdf scan hw2/page1.jpg -d hw --append
   hwpdf font -d hw -o hw/font.ttf
   

   Andernfalls akzeptieren Sie den neutralen Fallback und sagen Sie dies explizit.
5. Rendern:

   hwpdf render --font hw/font.ttf --text-file hw/doc.txt -o hw/letter.pdf --size 12 --paper ruled
   

6. Sehen Sie sich das Ergebnis an. Rendern Sie PDF-Seiten in PNG und inspizieren Sie sie mit der Bildverarbeitung:

   hwpdf preview --pdf hw/letter.pdf -d hw/preview --dpi 150
   

   Bewerten Sie: Sind die Striche zu dünn/dick, sind die Zeilen zu eng, kollidieren Zeichen oder laufen über die Ränder hinaus, sieht etwas offensichtlich falsch aus? Korrigieren Sie mit --size, --leading, --jitter, --weight (Font neu bauen), --paper none|ruled|grid.

Ablauf D — Der Benutzer übergibt ein PDF mit seiner Handschrift

Dies ist der schnellste Weg, wenn er funktioniert, weil das PDF die Formen bereits enthält.

1. Versuchen Sie das Programm für eingebettete Fonts (am besten: voller Glyphensatz, kein Neunzeichnen):

   hwpdf extract-font --pdf user.pdf -d hw
   

   Gute Ausgabe = eine .ttf/.otf in hw/fonts/ mit einer echten Zeichenbelegungstabelle (mapped > 20). Überspringen Sie das, wenn der Bericht „subset/cid“ sagt.
2. Andernfalls: Wenn das PDF eine Textebene hat (d.h. Sie können die Zeichen auswählen), ernten Sie die Glyphen aus der gerenderten Seite – die Textebene liefert die Beschriftung, das Raster liefert die Tinte:

   hwpdf pdf-specimen --pdf user.pdf -d hw            # füge --font-name "<Familie>" hinzu, um nur deren Font zu behalten
   hwpdf font -d hw --family "Alex Hand" -o hw/font.ttf
   

3. Andernfalls ist es ein Scan: hwpdf rasterize --pdf user.pdf -d hw/pages → Ablauf B mit den Seitenbildern, oder fordern Sie ein Übungsblatt an (Ablauf A).
4. Speichern Sie das Ergebnis als Profil (Schritt 5 unten), dann rendern.

Ablauf B — Freiform-Foto

1. hwpdf segment hw/photo.jpg -d hw → hw/contact.png (nummerierte Miniaturansichten) + hw/crops/.
2. Öffnen Sie hw/contact.png und lesen Sie die Nummern. Schreiben Sie hw/labels.json als {"0":"A","1":"b",...}, oder verwenden Sie hwpdf label -d hw --pair "0=A 1=B 2=''" ('' entfernt einen Klecks: Punkte, Schmierer, Seitenränder oder ein Fragment eines Buchstabens, der in zwei Strichen gezeichnet wurde).
3. hwpdf font -d hw --labels hw/labels.json -o hw/font.ttf, dann Schritte 4–6 oben.

Verbundenes/kursives Schreiben und mehrstrichige CJK-Zeichen machen diesen Ablauf fehleranfällig; wenn das Ergebnis schlecht aussieht, wechseln Sie zu Ablauf A und sagen Sie warum.

Ablauf C — Benutzer hat bereits einen Font

Überspringen Sie zu hwpdf coverage und hwpdf render mit --font <ihre Datei>, dann speichern Sie ein Profil.

Profile — der stabile, wiederverwendbare Weg

Ein Profil friert alles ein, was zur Reproduktion des Aussehens benötigt wird: die Font-Datei (kopiert in das Profil, mit SHA-256), ihre Voreinstellungen und einen bereit zum Einfügen Prompt.

hwpdf profile save --name alex --font hw/font.ttf --source "handschrift pdf vom benutzer"
hwpdf profile list
hwpdf render --profile alex --text-file letter.txt -o letter.pdf

• Profile leben in ~/.handwriting-pdf/profiles/<name>/ (profile.json, font.ttf, PROMPT.md); setzen Sie HWPDF_PROFILE_DIR, um das Verzeichnis zu verlegen.
• PROMPT.md wird für den Benutzer geschrieben: fügen Sie es in einen beliebigen Agenten auf einem beliebigen Rechner ein, und dieser verwendet denselben Font mit denselben Layout-Voreinstellungen.
• Am Aussehen iterieren? Nur eine Sache auf einmal ändern – rendern, preview, vergleichen, dann hwpdf profile save --name alex --font hw/font.ttf --size ... --paper ..., um es zur neuen Voreinstellung zu machen. font --weight 1 erstellt einen fetteren Strich; speichern Sie danach das Profil erneut, damit die Änderung dauerhaft ist.
• Ein Profil, das aus einem PDF erstellt wurde, deckt nur Zeichen ab, die in diesem PDF vorkommen. Überprüfen Sie das mit hwpdf coverage --font <Profil-Font> --text-file <neues Dokument>, bevor Sie ein vollständiges Dokument versprechen.

Synth — Zeichen, die der Benutzer nie geschrieben hat (experimentell)

Ein Dokument benötigt fast immer Zeichen, die der Benutzer nie geschrieben hat; im Chinesischen ist das die Norm, nicht die Ausnahme. Zwei Möglichkeiten, sie zu füllen, in der Reihenfolge ihrer Ehrlichkeit:

1. Neutraler Fallback (Standard, vorhersagbar): render --fallback auto wählt einen System-Handschrift-Font aus; die Seite mischt ihre Hand mit einer gedruckten oder neutralen Hand, und render meldet jedes so gezeichnete Zeichen.
2. Synth-Inferenz (hwpdf synth, noch experimentell): Erstellen Sie einen zweiten Font, der den gesamten Zeichensatz abdeckt, indem die messbaren Teile ihres Stils entlehnt werden – Neigung, Strichstärke, x-Höhe, Glyphenbreite – und diese auf ein System-Skelett-Glyphen gestempelt werden.

hwpdf synth doctor                              # Welche Engines sind nutzbar, was fehlt
hwpdf synth build --style hw/font.ttf --charset common3500 -o hw/synth.ttf
hwpdf synth specimen --font hw/synth.ttf --real hw/font.ttf -o hw/sheet.png   # zuerst überprüfen
hwpdf synth verify --font hw/synth.ttf --charset common3500                   # Abdeckung / fehlend
hwpdf synth eval --font hw/synth.ttf --real hw/font.ttf -o hw/report.md      # Zahlen für den Bericht
hwpdf profile save --name alex --font hw/font.ttf --synth-font hw/synth.ttf
hwpdf render --profile alex --text-file doc.txt -o out.pdf                    # Synth füllt die Lücken

Engines: stylefit (analytisch – kein Download, keine GPU, deterministisch; chinesische Glyphen behalten ein System-Sans-Skelett und übernehmen nur Neigung/Strichstärke des Benutzers) und stub (Test-Fixture, kein Stiltransfer). Die Diffusions-Engine diff-font benötigt Gewichte, deren Lizenzen ungeklärt sind (PLAN.md §8 S4) – synth doctor sagt das, anstatt es vorzutäuschen.

Sagen Sie, was es ist: Zeichen, die sie geschrieben haben, werden wortgetreu reproduziert; inferierte Zeichen sind „ihre Neigung und Strichstärke auf einem gedruckten Skelett“. Sagen Sie dem Benutzer nicht, dass die inferierte Hälfte „aussieht wie sie“. Überprüfen Sie meta.gate in <font>.json (rejected sollte 0 sein) und schauen Sie sich das Muster vor der Auslieferung an.

Regeln

1. Nur lokal. Laden Sie niemals die Probe, den Font oder die Ausgabe hoch; keine API-Aufrufe.
2. Nur die eigene Handschrift des Benutzers. Lehnen Sie es ab, die Handschrift, Unterschrift oder den Briefkopf einer dritten Person nachzuahmen, und lehnen Sie die Erstellung von Unterschriften / Verträgen / Zertifikaten / offiziellen Dokumenten ab – erklären Sie kurz (Fälschung, Betrug, Beweisregeln) und bieten Sie ein normales getipptes Dokument an.
3. Niemals Qualität vortäuschen. Wenn der Font 40 Glyphen hat, sagen Sie 40. Wenn der Fallback die Hälfte der Seite gezeichnet hat, sagen Sie es. Melden Sie die fehlenden Zeichen wörtlich.
4. Fordern Sie eine Neuaufnahme an, bevor Sie das Werkzeug beschuldigen: unscharfe, beschattete, beschnittene Eck- oder gitterlinienbedeckte Fotos sind die häufigste Fehlerursache.
5. Behalten Sie das Arbeitsverzeichnis (hw/) – der Benutzer kann später Zeichen hinzufügen und den Font neu bauen.

Befehlsreferenz

Befehl	Zweck
hwpdf doctor	Abhängigkeits- + Systemfont-Prüfung
hwpdf template --chars "abc" / --text-file doc.txt -d VERZ	Übungsblatt-PDF + Metadaten
hwpdf scan BILD... [-d VERZ] [--rotate 90] [--append]	fotografiertes Blatt → Glyphenmasken (append = fügt in vorhandene Arbeit ein)
hwpdf extract-font --pdf in.pdf -d VERZ	Eingebettete Fonts aus einem PDF extrahieren (bester Fall: volles TTF)
hwpdf pdf-specimen --pdf in.pdf -d VERZ [--font-name F]	beschriftete Glyphen aus der Textebene + Raster eines PDFs ernten
hwpdf rasterize --pdf in.pdf -d VERZ [--dpi 300]	gescanntes PDF → Seiten-PNGs
hwpdf segment BILD... [-d VERZ] [--thresh N] [--deskew]	Freiform-Foto → Blobs + Kontaktbogen
hwpdf label -d VERZ --order "ABC" / --pair "0=A 1=B"	Blobs Zeichen zuordnen
hwpdf font -d VERZ [--labels f] [--family NAME] [--weight -2..2] [--smooth 0..2] -o out.ttf	Font bauen
hwpdf coverage --font f --text-file doc.txt	Welche Zeichen fehlen
`hwpdf render --font f --text-file doc.txt -o out.pdf [--size 12] [--leading 1.8] [--paper ruled] [--jitter 1] [--ink "#1a1c24"] [--fallback auto	none
hwpdf render --profile NAME --text-file doc.txt -o out.pdf	PDF unter Verwendung des Fonts und der Voreinstellungen eines gespeicherten Profils
hwpdf profile save/list/show/remove ...	das wiederverwendbare Handschrift-Profil einfrieren / durchsuchen (schreibt PROMPT.md)
hwpdf preview --pdf out.pdf -d VERZ [--dpi 150]	PDF-Seiten → PNG zur visuellen Überprüfung
hwpdf synth doctor / build / specimen / verify / charsets	optionale Inferenz-Engine: Vollzeichensatz-Font aus einer geschriebenen Teilmenge (siehe Abschnitt Synth)
hwpdf selftest -d VERZ [--messy]	synthetischer Ende-zu-Ende-Smoke-Test

Grenzen (bei Bedarf nennen)

• Eine Glyphe pro Zeichen: keine verbundene Kursivschrift, keine natürliche Variation zwischen Vorkommen, keine Druck-/Tintentextur. Der Abstand wird durch Jitter simuliert, die Glyphenformen nicht.
• CJK: Der Font enthält nur geschriebene Zeichen. 30 Zellen pro Seite; ein 300-Zeichen-Brief benötigt ein 10-seitiges Übungsblatt. hwpdf synth build --charset common3500 ist die Abkürzung, aber inferierte CJK-Glyphen sind ein System-Sans-Skelett in der Neigung des Benutzers, nicht seine tatsächliche Pinselführung.
• Die PDF-Textebene ist echter Text (durchsuchbar/kopierbar) im generierten Font.
• Fotos müssen alle vier schwarzen Eckquadrate des Übungsblatts zeigen.

Details: references/workflow.md · references/troubleshooting.md