# 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 (für `piccreate.py`, `svgconvert.py` und `glyphextract.py` keine weiteren Pakete nötig) - ImageMagick (`magick`, ältere Versionen `convert`) für die Umwandlung SVG → JPG/PNG mit `svgconvert.py` - nur für Webseiten-Vorschauen (`webscan`): Playwright, siehe unten Alles läuft unter Linux und Windows, siehe [Windows](#windows). ## Verzeichnisse | Verzeichnis | Inhalt | |----------------|-----------------------------------------------------------| | `bin/` | Startskripte: `.sh` für Linux, `.bat` für Windows | | `libs/` | Python-Programme `piccreate.py`, `svgconvert.py`, `webscan.py`, `glyphextract.py` | | `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`, …). Das Projektverzeichnis ermittelt `setenv.sh` selbst (das Verzeichnis über `bin/`), die Skripte in `bin/` lassen sich deshalb von überall aufrufen. Nur wer die Variablen in der eigenen Shell braucht, lädt `setenv.sh` selbst (bash oder zsh): ```sh cd bin . ./setenv.sh ``` ## Gemeinsame Optionen Alle Programme benutzen für dieselbe Aufgabe denselben Schalter: | Option | Bedeutung | piccreate | svgconvert | webscan | glyphextract | |---------------------|----------------------------------------------------|:-:|:-:|:-:|:-:| | `-c`, `--config` | Konfiguration aus `cfg/` (Endung `.cfg` optional) | ✓ | ✓ | ✓ | | | `-i`, `--infile` | Eingabe (CSV, URL-Liste, Glyph oder Font) | ✓ | ✓ | ✓ | ✓ | | `-o`, `--outdir` | Ordner für die erzeugten Bilder (Standard `$PICCREATE_OUT`) | ✓ | ✓ | ✓ | ✓ | | `--section` | Sektion der Konfiguration mit den Bildmaßen | | ✓ | ✓ | | | `--format` | Bildformat `jpg` oder `png` (überschreibt die Konfiguration) | | ✓ | ✓ | | | `-f`, `--force` | vorhandene Bilder überschreiben | | ✓ | ✓ | | | `-j`, `--jobs` | Anzahl paralleler Jobs | | ✓ | ✓ | | | `-t`, `--test` | Testbilder erzeugen | | ✓ | | | | `-y`, `--dry` | Probelauf, keine Dateien schreiben | ✓ | ✓ | | | | `-v`, `--verbose` | ausführliche Ausgabe | | ✓ | ✓ | | | `-h`, `--help` | Hilfe | ✓ | ✓ | ✓ | ✓ | | `--version` | Versionsnummer | ✓ | ✓ | ✓ | ✓ | Ältere Namen funktionieren weiter: `--cfg` für `--config` und bei svgconvert `--svgfolder` für `--outdir`. ## Bilder erzeugen ```sh ./piccreate -c punkteraetsel -i test ``` | Option | Bedeutung | |-----------------------------|-----------| | `-c`, `--config ` | 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 `.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 ./svgconvert.sh -c punkteraetsel -p ``` Wandelt alle SVGs in `$PICCREATE_OUT` (oder `-o `) parallel mit ImageMagick um; die Bilder landen im selben Ordner. Breite, Höhe, Format und Auflösung kommen aus der Sektion `--section` der Konfiguration (Standard `[png]`, für große JPGs z. B. `--section jpgs`). | Option | Bedeutung | |--------------------------------|-----------| | `-c`, `--config ` | Konfiguration aus `cfg/` (Endung `.cfg` optional) | | `-o`, `--outdir ` | Ordner mit den SVGs, auch für die Bilder (Standard `$PICCREATE_OUT`) | | `--section ` | Sektion mit den Bildmaßen (Standard `png`) | | `--format ` | Bildformat, überschreibt die Konfiguration | | `-i`, `--infile ` | CSV aus `in/` prüfen: fehlende Bilder melden, nur diese umwandeln | | `-j`, `--jobs ` | Anzahl paralleler Jobs (Standard 8) | | `-b`, `--background ` | Hintergrundfarbe, `none` für transparent | | `-f`, `--force` | vorhandene Bilder überschreiben | | `-p`, `--progress` | Fortschrittsbalken anzeigen | | `-v`, `--verbose` | ausführliche Ausgabe | | `-t`, `--test ` | `n` Test-SVGs erzeugen und umwandeln | | `-y`, `--dry` | Probelauf ohne Umwandlung | ## Vorschaubilder von Webseiten (webscan) `libs/webscan.py` lädt für jede Zeile einer Eingabedatei eine Webseite in einem Browser ohne Fenster und speichert den sichtbaren Bereich als Bild `.jpg`. Die Größe kommt aus der Sektion `[webscan]` der Konfiguration (in `cfg/webscan.cfg`: 800×500). Einmalig einrichten mit `bin/setup-venv.sh`: legt die Python-Umgebung `.venv` im Projektverzeichnis an, installiert `requirements.txt` und kümmert sich um den Browser (Ubuntu: Playwright-Chromium, Arch: Hinweis auf das Chromium der Distribution). Ist `.venv` schon vorhanden, wird nichts neu installiert. ```sh ./setup-venv.sh ``` Von Hand geht es so: ```sh python3 -m venv .venv # Ubuntu: vorher sudo apt install python3-venv .venv/bin/pip install -r requirements.txt ``` Browser unter Ubuntu/Debian: ```sh sudo .venv/bin/playwright install-deps chromium .venv/bin/playwright install chromium ``` Browser unter Arch Linux (Playwright unterstützt Arch nicht offiziell, daher besser das Chromium der Distribution): ```sh sudo pacman -S chromium export PICCREATE_BROWSER=/usr/bin/chromium # oder Option --browser /usr/bin/chromium ``` Fehlen Playwright oder der Browser, gibt `webscan.py` die passenden Befehle für die erkannte Distribution aus und bricht mit Exit-Code 2 ab. Eingabedatei, z. B. `in/kunden.csv` (Kopfzeile optional, `http://` wird bei Bedarf ergänzt): ``` Kennummer;URL 1001;www.example.org 1002;https://www.example.com/start ``` Aufruf: ```sh ./webscan.sh -c webscan -i kunden ``` | Option | Bedeutung | |-----------------------------|-----------| | `-c`, `--config ` | Konfiguration aus `cfg/` (Standard `webscan`) | | `-i`, `--infile ` | Eingabedatei aus `in/` oder mit Pfad | | `-o`, `--outdir ` | Ausgabeverzeichnis (Standard `$PICCREATE_OUT`) | | `--section ` | Sektion mit den Bildmaßen (Standard `webscan`) | | `--format ` | Bildformat, überschreibt die Konfiguration | | `-j`, `--jobs ` | Anzahl gleichzeitig geladener Seiten (Standard 4) | | `--timeout ` | Wartezeit pro Seite (Standard 20) | | `-f`, `--force` | vorhandene Bilder überschreiben | | `--browser ` | eigenes Chromium statt des Playwright-Browsers (Standard `$PICCREATE_BROWSER`) | | `-v`, `--verbose` | ausführliche Ausgabe | Seiten ohne URL oder mit Ladefehler werden übersprungen und am Ende aufgelistet; der Exit-Code ist dann 1. ## Fonts Ein Font liegt in `fonts//` und besteht aus - einer SVG-Vorlage pro Zeichen (z. B. `a.svg`), eingeschlossen in `…`; die Punktnummern sind Platzhalter `${x1}`, `${x2}`, … - der Datei `.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 + ausgangsschrift.cfg erzeugen ./fonttest.sh ausgangsschrift # Testbilder der einzelnen Glyphen erzeugen ./extract-glyph.sh -i ../in/ausgangsschrift/a.svg -e # nur ein Buchstabe ``` Alle drei rufen `libs/glyphextract.py` auf. Dort ist `-i` ein einzelner Buchstabe oder ein Font (Ordner in `in/` oder Pfad); mit `-e` werden die Glyphen für den Font extrahiert (bei einem Font zusätzlich `.cfg`), ohne `-e` entstehen Testbilder zum Prüfen in Inkscape: ```sh python3 glyphextract.py -i ausgangsschrift -e # = extract-font.sh python3 glyphextract.py -i ausgangsschrift # = fonttest.sh python3 glyphextract.py -i ../in/ausgangsschrift/a.svg -e ``` | Option | Bedeutung | |----------------------------------|-----------| | `-i`, `--infile ` | ein Buchstabe (`.svg`) oder ein Font (Ordner in `in/` oder Pfad) | | `-e`, `--extract` | Glyphen für den Font extrahieren, bei einem Font zusätzlich `.cfg`; ohne `-e` Testbilder | | `-o`, `--outdir ` | Ausgabeverzeichnis (Standard `$PICCREATE_OUT`) | Alle schreiben nach `$PICCREATE_OUT` (oder `-o `). Das Ergebnis (Glyph-SVGs und `.cfg`) wird anschließend nach `fonts//` übernommen. Werte wie `XSTEP` kann man danach in der `.cfg` noch von Hand anpassen. ## Windows Für jedes Shell-Skript in `bin/` gibt es eine `.bat`-Datei mit denselben Optionen: `piccreate.bat`, `svgconvert.bat`, `webscan.bat`, `extract-glyph.bat`, `extract-font.bat`, `fonttest.bat`, `setup-venv.bat`. `setenv.bat` setzt die Umgebung; das Projektverzeichnis ermittelt es selbst (das Verzeichnis über `bin\`), ein fester Pfad ist nicht nötig. Einrichten: 1. Python 3 installieren (https://www.python.org oder `winget install Python.Python.3.13`) 2. ImageMagick installieren (https://imagemagick.org), nur für `svgconvert` 3. nur für `webscan`: `bin\setup-venv.bat` ausführen (legt `.venv` an und installiert Playwright mit Chromium) Beispiel: ```bat cd bin piccreate.bat -c punkteraetsel -i test svgconvert.bat -c punkteraetsel -p ``` Die `.bat`-Dateien nehmen das Python aus `.venv`, falls vorhanden, sonst den Python Launcher `py` oder `python` aus dem `PATH`.