Michael StanglandClaude Opus 5.5
c5598f2304
- Tabellen für piccreate, svgconvert, webscan mit -x, --lang <wert> - neue Optionstabelle für glyphextract, --version in der Übersicht Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
329 lines
12 KiB
Markdown
329 lines
12 KiB
Markdown
# 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](#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 <datei>` | Konfiguration aus `cfg/` (Endung `.cfg` optional) |
|
||
| `-i`, `--infile <datei>` | CSV-Datei aus `in/` (Endung `.csv` optional) |
|
||
| `-o`, `--outdir <ordner>` | 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
|
||
./svgconvert.sh -c punkteraetsel -p
|
||
```
|
||
|
||
Wandelt alle SVGs in `$PICCREATE_OUT` (oder `-o <ordner>`) 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 <datei>` | Konfiguration aus `cfg/` (Endung `.cfg` optional) |
|
||
| `-o`, `--outdir <ordner>` | Ordner mit den SVGs, auch für die Bilder (Standard `$PICCREATE_OUT`) |
|
||
| `--section <name>` | Sektion mit den Bildmaßen (Standard `png`) |
|
||
| `--format <jpg\|png>` | Bildformat, überschreibt die Konfiguration |
|
||
| `-i`, `--infile <datei>` | CSV aus `in/` prüfen: fehlende Bilder melden, nur diese umwandeln |
|
||
| `-j`, `--jobs <n>` | Anzahl paralleler Jobs (Standard 8) |
|
||
| `-b`, `--background <farbe>` | Hintergrundfarbe, `none` für transparent |
|
||
| `-f`, `--force` | vorhandene Bilder überschreiben |
|
||
| `-p`, `--progress` | Fortschrittsbalken anzeigen |
|
||
| `-v`, `--verbose` | ausführliche Ausgabe |
|
||
| `-t`, `--test <n>` | `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
|
||
`<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.
|
||
|
||
```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 <datei>` | Konfiguration aus `cfg/` (Standard `webscan`) |
|
||
| `-i`, `--infile <datei>` | Eingabedatei aus `in/` oder mit Pfad |
|
||
| `-o`, `--outdir <ordner>` | Ausgabeverzeichnis (Standard `$PICCREATE_OUT`) |
|
||
| `--section <name>` | Sektion mit den Bildmaßen (Standard `webscan`) |
|
||
| `--format <jpg\|png>` | Bildformat, überschreibt die Konfiguration |
|
||
| `-j`, `--jobs <n>` | Anzahl gleichzeitig geladener Seiten (Standard 4) |
|
||
| `--timeout <sekunden>` | Wartezeit pro Seite (Standard 20) |
|
||
| `-f`, `--force` | vorhandene Bilder überschreiben |
|
||
| `--browser <pfad>` | 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/<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 + 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 `<name>.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 <datei\|font>` | ein Buchstabe (`.svg`) oder ein Font (Ordner in `in/` oder Pfad) |
|
||
| `-e`, `--extract` | Glyphen für den Font extrahieren, bei einem Font zusätzlich `<name>.cfg`; ohne `-e` Testbilder |
|
||
| `-o`, `--outdir <ordner>` | Ausgabeverzeichnis (Standard `$PICCREATE_OUT`) |
|
||
|
||
Alle 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:
|
||
|
||
```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`.
|