# 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`, …). 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
./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.

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

```sh
./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:

```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 (`-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:

```bat
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`.