Dokumentation in doc/ mit Beispielbildern

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

doc/README.md

@@ -0,0 +1,176 @@
+# piccreate
+
+`piccreate` erzeugt aus einer CSV-Datei mit Namen für jede Zeile ein eigenes
+SVG-Bild. Die Buchstaben stammen aus einem eigenen SVG-„Font“, dessen Glyphen
+nummerierte Punkte enthalten. So entstehen z. B. personalisierte
+**Punkt-zu-Punkt-Rätsel** und die passenden **Lösungsbilder**.
+
+Beispiel für die CSV-Zeile `001;Silke`:
+
+Rätsel (`cfg/punkteraetsel.cfg`, Font `ausgangsschrift`, Hintergrund `Karo.png`):
+
+![Punkterätsel für "Silke"](images/punkteraetsel.png)
+
+Lösung (`cfg/punkteloesung.cfg`, Font `ausgangsschrift_verbunden`, ohne Hintergrund):
+
+![Lösung für "Silke"](images/punkteloesung.png)
+
+Die Punkte werden über das ganze Wort fortlaufend nummeriert (1–32).
+
+## Voraussetzungen
+
+- Python 3 (keine weiteren Python-Pakete nötig)
+- ImageMagick (`convert`) für die Umwandlung SVG → JPG/PNG mit `svgconvert.py`
+- `bash`, `bc`, `sed`, `grep` für die Font-Werkzeuge in `bin/`
+
+## Verzeichnisse
+
+| Verzeichnis    | Inhalt                                                    |
+|----------------|-----------------------------------------------------------|
+| `bin/`         | Shell-Skripte (Aufruf, Umgebung, Font-Extraktion)         |
+| `libs/`        | Python-Programme `piccreate.py`, `svgconvert.py`, Hilfen  |
+| `cfg/`         | Auftrags-Konfigurationen (`*.cfg`)                        |
+| `in/`          | Eingabedateien (`*.csv`) und Rohglyphen für neue Fonts    |
+| `out/`         | Ausgabe der erzeugten Bilder                              |
+| `fonts/`       | Fonts: ein Verzeichnis pro Font mit Glyph-SVGs + `.cfg`   |
+| `backgrounds/` | Hintergrundbilder                                         |
+
+## Umgebung
+
+Alle Pfade werden über Umgebungsvariablen gefunden, die `bin/setenv.sh` setzt
+(`PICCREATE`, `PICCREATE_CFG`, `PICCREATE_IN`, `PICCREATE_OUT`,
+`PICCREATE_FONTS`, `PICCREATE_BACKGROUNDS`, …). Der Installationspfad steht
+dort fest auf `~/develop/python/piccreate`.
+
+```sh
+cd bin
+. ./setenv.sh
+```
+
+## Bilder erzeugen
+
+```sh
+./piccreate -c punkteraetsel -i test
+```
+
+| Option            | Bedeutung                                                  |
+|-------------------|------------------------------------------------------------|
+| `-c`, `--cfg`     | Konfiguration aus `cfg/` (Endung `.cfg` optional)          |
+| `-i`, `--infile`  | CSV-Datei aus `in/` (Endung `.csv` optional)               |
+| `-o`, `--outdir`  | Ausgabeverzeichnis (Standard: `$PICCREATE_OUT`)            |
+| `-s`, `--startfrom` | Nummerierung bei jedem Wort / Großbuchstaben neu beginnen |
+| `-y`, `--dry`     | SVG nur auf der Konsole ausgeben, keine Dateien schreiben  |
+
+Für jede CSV-Zeile entsteht `<customerid>.svg` im Ausgabeverzeichnis.
+
+### Eingabedatei (CSV)
+
+UTF-8, Trennzeichen `;`, `,` oder Tab (wird automatisch erkannt), erste Zeile
+enthält die Spaltenüberschriften:
+
+```
+Kennummer;Name
+001;Silke
+002;Rau
+```
+
+## Konfiguration (`cfg/*.cfg`)
+
+```ini
+[globals]
+# Bildgröße in Pixel
+width=2776
+height=898
+# optional, Datei aus backgrounds/
+background=Karo.png
+# Textzeilen im Bild, durch Komma getrennt
+lines=PunkteName
+
+# interner Name = Spaltenüberschrift der CSV
+[translation]
+# Pflicht: ergibt den Dateinamen
+customerid=Kennummer
+name=Name
+
+# eine Sektion je Eintrag in "lines"
+[PunkteName]
+# Text, Platzhalter aus [translation]
+content=${name}
+fontname=ausgangsschrift
+# Startpunkt
+x=-10
+y=0
+# Fläche für die Zeile, optional (sonst aus [globals])
+width=2640
+height=850
+# Abstand zwischen den Buchstaben
+glyph_space=20
+# Punkte fortlaufend nummerieren
+counter_replace=True
+# left | center | right
+align=center
+# top | center | bottom
+yalign=center
+# Wort auf Bildgröße skalieren
+autoscale=True
+```
+
+Statt `autoscale` kann auch fest mit `scale` bzw. `xscale`/`yscale` skaliert
+werden. Fehlen in einer Zeilen-Sektion `width`/`height`, gelten die Werte aus
+`[globals]`.
+
+Die Sektionen `[jpgs]`, `[png]` usw. beschreiben die Rastergrafiken für
+`svgconvert.py` (`width`, `height`, `format`, `density`).
+
+## SVG in JPG/PNG umwandeln
+
+```sh
+cd libs
+python3 svgconvert.py -c punkteraetsel.cfg --format png -p
+```
+
+Wandelt alle SVGs in `$PICCREATE_OUT` (oder `-s <ordner>`) parallel mit
+ImageMagick um. `--format` wählt die Sektion aus der Konfiguration.
+
+| Option          | Bedeutung                                              |
+|-----------------|--------------------------------------------------------|
+| `-c`            | Konfiguration (mit Endung `.cfg`)                      |
+| `--format`      | Sektion/Format, z. B. `png` oder `jpgs` (Standard `jpg`) |
+| `-i`            | CSV prüfen: fehlende Bilder melden, nur diese umwandeln |
+| `-j`            | Anzahl paralleler Jobs (Standard 8)                    |
+| `-b`            | Hintergrundfarbe, `none` für transparent               |
+| `-f`            | vorhandene Bilder überschreiben                        |
+| `-p` / `-v`     | Fortschrittsbalken / ausführliche Ausgabe              |
+| `-y`            | Probelauf ohne Umwandlung                              |
+
+## Fonts
+
+Ein Font liegt in `fonts/<name>/` und besteht aus
+
+- einer SVG-Vorlage pro Zeichen (z. B. `a.svg`), eingeschlossen in
+  `<g transform="translate(${posx},${posy})">…</g>`; die Punktnummern sind
+  Platzhalter `${x1}`, `${x2}`, …
+- der Datei `<name>.cfg` mit einer Sektion pro Zeichen:
+
+```ini
+[a]
+# Breite des Zeichens
+XSTEP=50.071972
+# Höhe des Zeichens
+YMAX=139.04482
+# Anzahl der Platzhalter x1..xn
+NPATTERN=11
+# Vorlagendatei
+FONTNAME=a.svg
+```
+
+Neue Fonts entstehen aus in Inkscape gezeichneten Glyphen (Punkte als Kreise,
+Nummern als Text `x1`, `x2`, …):
+
+```sh
+./extract-font.sh ausgangsschrift   # Glyphen aus in/ausgangsschrift/ extrahieren
+./fonttest.sh ausgangsschrift       # Testbilder der einzelnen Glyphen erzeugen
+```
+
+Das Ergebnis (Glyph-SVGs und `.cfg`) wird anschließend nach `fonts/<name>/`
+übernommen.