piccreate/doc/README.md

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):

Lösung (cfg/punkteloesung.cfg, Font ausgangsschrift_verbunden, ohne Hintergrund):

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.

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, …). Der Installationspfad steht dort fest auf ~/develop/python/piccreate.

cd bin
. ./setenv.sh

Bilder erzeugen

./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)

[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

./svgconvert.sh -c punkteraetsel --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 aus cfg/ (Endung .cfg optional)
--format	Sektion/Format, z. B. png oder jpgs (Standard jpg)
-i	CSV aus in/ 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
-s	Ordner mit den SVGs (Standard $PICCREATE_OUT)
-y	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 <Kundennummer>.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.

./setup-venv.sh

Von Hand geht es so:

python3 -m venv .venv          # Ubuntu: vorher sudo apt install python3-venv
.venv/bin/pip install -r requirements.txt

Browser unter Ubuntu/Debian:

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):

sudo pacman -S chromium
export PICCREATE_BROWSER=/usr/bin/chromium   # oder Option -b /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:

./webscan.sh -c webscan -i kunden

Option	Bedeutung
-c	Konfiguration (Standard webscan)
-i	Eingabedatei aus in/ oder mit Pfad
-o	Ausgabeverzeichnis (Standard $PICCREATE_OUT)
--format	jpg oder png (überschreibt die Konfiguration)
-j	Anzahl gleichzeitig geladener Seiten (Standard 4)
-t	Wartezeit pro Seite in Sekunden (Standard 20)
-f	vorhandene Bilder überschreiben
-b	Pfad zu einem eigenen Chromium
-v	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/<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:

[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, …):

./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 (-f, -t bzw. -i [-e]) und schreiben nach $PICCREATE_OUT (oder -o <ordner>). Das Ergebnis (Glyph-SVGs und <name>.cfg) wird anschließend nach fonts/<name>/ ü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:

cd bin
piccreate.bat -c punkteraetsel -i test
svgconvert.bat -c punkteraetsel --format png -p

Die .bat-Dateien nehmen das Python aus .venv, falls vorhanden, sonst den Python Launcher py oder python aus dem PATH.