pixelcut 1.3.0__py3-none-any.whl

pixelcut-1.3.0.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.4
+Name: pixelcut
+Version: 1.3.0
+Summary: K&K pixelcut - cut a picture into parts without changing a single pixel
+License: MIT
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy<3,>=1.23
+Requires-Dist: opencv-python-headless<5,>=4.7
+Requires-Dist: Pillow<13,>=9.5
+Requires-Dist: scikit-image<1,>=0.20
+Requires-Dist: vtracer<1,>=0.6
+Provides-Extra: test
+Requires-Dist: pytest; extra == "test"
+Dynamic: license-file
+
+# K&K pixelcut
+
+![license](https://img.shields.io/badge/license-MIT-blue) ![python](https://img.shields.io/badge/python-3.9%2B-informational) ![lossless](https://img.shields.io/badge/pixels-unchanged-brightgreen) ![tests](https://github.com/CalyieX/pixelcut/actions/workflows/ci.yml/badge.svg)
+
+[![Unterstützen auf Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/kkwonderland)
+
+**English in short:** a small command-line tool that cuts an image into wedge-shaped parts (free angles, straight or **zig-zag** edges) **without altering a single pixel**, turns a white background into real transparency (exact colour-to-alpha), lifts a word or element out and re-places it, and writes **hit-area polygons** for touch menus. Parts put back together over white give the original back (max deviation <= 1/255, measured with `--verify` and `compare`). It does *not* generate or redraw images and does not upscale without inventing pixels. Works on drawings and photos. Details below (German).
+
+**Ein Bild in Teile zerlegen, ohne ein einziges Pixel zu verändern.**
+*Cut a picture into parts without changing a single pixel.*
+
+**Auf einen Blick**
+
+- **Exakt:** Teile über Weiß zusammengesetzt = das Original (höchstens 1/255 Abweichung, bei Fotos 0).
+- **Zacken statt Linie:** Keile um eine Mitte, freie Winkel, gerade Kante oder Zickzack.
+- **Echte Transparenz:** weißer Hintergrund wird sauber freigestellt, auch weiche Kanten.
+- **Trefferflächen:** `parts.json` mit Polygon pro Teil, fertig für Touch-Menüs.
+- **Messbar:** `compare` zeigt SSIM und Pixelabweichung, auch für Ergebnisse anderer Werkzeuge.
+
+Gebaut von K&K AI. Entstanden bei einer Handy-App: Ein Comic-Bild sollte zum Menü werden (Blase in vier Teile, Zacken statt Linie, das Wort in der Mitte als Knopf), und es durfte **nicht anders aussehen als das Original**.
+
+![Zerlegtes Zeichenbild](examples/split_preview.png)
+
+---
+
+## Die Idee in drei Sätzen
+
+Die meisten "Bild nachbauen"-Werkzeuge zeichnen neu, tracen oder skalieren hoch. Das Ergebnis sieht dann nur *ähnlich* aus.
+pixelcut macht das Gegenteil: Es behält die Original-Pixel und entscheidet nur, **zu welchem Teil jedes Pixel gehört**.
+Legt man die Teile wieder zusammen, kommt das Original zurück, Pixel für Pixel, und das Werkzeug misst das selbst nach (`--verify`, `compare`).
+
+**Bedingung:** Das gilt für 8-Bit-Bilder und mit `--gap 0 --edge 0`. Die Standardwerte (`--gap 2.6 --edge 3.2`) schneiden einen sichtbaren Spalt mit Tintenkante, damit man die Teile sieht. Dann weicht das Ergebnis gewollt ab; `--verify` zeigt beide Zahlen. Transparente Bilder werden über Weiß gelegt und 16-Bit-Bilder auf 8 Bit gebracht, beides mit Hinweis.
+
+---
+
+## Download (ohne Python)
+
+Fertige Programme für Windows, Linux (x64 und ARM) und Mac (Apple Silicon und Intel) gibt es unter [Releases](https://github.com/CalyieX/pixelcut/releases/latest). Jedes Programm wurde vor dem Hochladen auf seinem eigenen System mit einem Rundlauftest geprüft.
+
+```bash
+# Linux / Mac: einmal ausführbar machen, dann starten
+chmod +x pixelcut-linux-x64        # bzw. pixelcut-macos-arm64
+./pixelcut-linux-x64 --help
+
+# Windows (PowerShell)
+.\pixelcut-windows-x64.exe --help
+```
+
+Mac: Beim ersten Start meldet macOS evtl. „nicht verifizierter Entwickler“. Dann in den Systemeinstellungen unter „Datenschutz & Sicherheit“ auf „Trotzdem öffnen“ klicken, oder `xattr -d com.apple.quarantine pixelcut-macos-arm64` ausführen. Die Programme sind nicht signiert.
+
+---
+
+## Im Browser (iPhone, iPad, Android, jeder Rechner)
+
+**[calyiex.github.io/pixelcut](https://calyiex.github.io/pixelcut/)** – dieselbe Engine läuft direkt im Browser (Pyodide/WebAssembly), nichts wird hochgeladen, nichts muss installiert werden. Bild auswählen, Winkel eintragen, Teile als ZIP speichern; zum Zusammensetzen alle Teile samt `parts.json` wieder auswählen. Auf iPhone/iPad in Safari ab iOS 16; beim ersten Öffnen werden ca. 40 MB geladen, danach liegt es im Cache. Nicht dabei: `trace`, `upscale`, `compare`, `key` (nur `split`, `join`, `alpha`).
+
+Bei jedem Commit prüft das CI die Seite in **WebKit (die Engine von Safari/iPhone), Chromium und Firefox**: Bild teilen, wieder zusammensetzen, Abweichung muss 0 sein. Das ist die Safari-Engine auf einem Mac-Rechner, kein echtes iPhone.
+
+---
+
+## Installation
+
+```bash
+git clone https://github.com/CalyieX/pixelcut
+cd pixelcut
+pip install -r requirements.txt     # numpy, opencv, Pillow, scikit-image, vtracer
+python pixelcut.py -h
+```
+
+Alles ist in `requirements.txt` enthalten, auch `trace` (vtracer) und `compare` (SSIM). Für `upscale` lädt das Tool beim ersten Aufruf von selbst die offizielle Real-ESRGAN-Version (ca. 50 MB, einmalig nach `~/.cache/pixelcut`). Du musst nichts weiter einrichten. Läuft Real-ESRGAN auf dem Rechner nicht (ARM-Linux oder keine Vulkan-Grafikkarte), skaliert das Tool stattdessen mit Lanczos und sagt es dazu.
+
+Getestet bei jedem Commit auf GitHub Actions: Windows, Linux (x64 und ARM) und macOS (Apple Silicon und Intel), jeweils mit Python 3.9, 3.12 und 3.13. Das Badge oben zeigt den aktuellen Stand. Nur `upscale` mit Real-ESRGAN braucht eine Vulkan-fähige Grafikkarte und x86-64; sonst skaliert das Tool mit Lanczos und sagt das dazu.
+
+---
+
+## Was pixelcut kann
+
+### 1. `alpha`: weißen Hintergrund transparent machen, exakt
+
+```bash
+python pixelcut.py alpha bild.png bild_alpha.png --verify
+```
+
+Standard-Verfahren *Color-to-Alpha* gegen Weiß: Jeder Farbwert wird so in Farbe + Deckkraft zerlegt, dass das Bild **über Weiß wieder genau das Original** ergibt (gemessen: höchstens 0,5 von 255 Abweichung). Auch weiche Kanten und halbtransparente Ränder bleiben richtig. Kein Ausschneiden mit Zauberstab, keine Kantenreste.
+
+### 2. `split`: in Keile schneiden, mit Zacken und Trefferflächen
+
+```bash
+python pixelcut.py split bild.png out --angles 32,148,214,327 --tooth 18 --depth 9 --only-inside --verify
+```
+
+- **Keile um eine Mitte.** Die Mitte ist frei wählbar (`--centre x,y`) oder wird automatisch bestimmt (Schwerpunkt der nicht weißen Fläche).
+- **Freie Winkel.** `--angles` gibt die Trennlinien an (0 = rechts, 90 = unten). Sie dürfen **ungleich und schräg** sein, also keine Viertel, sondern zum Beispiel ein X, dessen Arme nicht gleich verteilt sind.
+- **Gerade oder Zacken.** `--depth 0` = gerade Linie. Mit `--depth` und `--tooth` wird aus der Linie ein Zickzack mit scharfen Zähnen.
+- **Spalt und Tintenkante.** `--gap` lässt einen schmalen Spalt zwischen den Teilen, `--edge` zeichnet eine dünne dunkle Kante an die Schnittkante (Comic-Look). Beides lässt sich auf 0 stellen.
+- **Nur die Hauptform schneiden.** `--only-inside` schneidet nur den größten zusammenhängenden Bereich. Wolken, Sterne und Punkte drumherum bleiben ganz und gehören jeweils einem einzigen Teil (dem, in dem die meiste Fläche liegt).
+- **Trefferflächen.** `parts.json` enthält pro Teil `polygon` (größte Außenkontur), `polygons` (alle getrennten Flächen mit ihren Löchern) und den dicksten Punkt (guter Platz für ein Symbol). Damit baut man Touch-Menüs, Klickflächen und Hotspots. Im Original-Projekt: Android `Path` + `Region`.
+- **Fotos.** `--opaque` lässt jedes Pixel deckend, damit helle Bildstellen nicht angetastet werden.
+
+Ausgabe: `part_0.png … part_N.png` (RGBA, gleiche Größe wie das Original, nur die Pixel des Teils sind sichtbar) und `parts.json`.
+
+### 3. `join`: Teile wieder zusammensetzen
+
+```bash
+python pixelcut.py join out nachbau.png
+```
+
+Legt alle `part_*.png` über Weiß aufeinander. Das ist der exakte "Nachbau". Mit `--gap 0 --edge 0` geschnitten, ergibt das Ergebnis das Original.
+
+### 4. `compare`: messen statt glauben
+
+```bash
+python pixelcut.py compare original.png nachbau.png
+# SSIM 1.0000   mean |diff| 0.000   max |diff| 0
+```
+
+Ähnlichkeit (SSIM, 1,0 = identisch), mittlere und größte Pixelabweichung. Nutzbar für jedes Bildpaar, auch für Ergebnisse anderer Werkzeuge.
+
+### 5. `key`: ein Element herausheben, verkleinern, in die Mitte setzen
+
+```bash
+python pixelcut.py key bild.png out --box 172,170,428,310 --scale 0.55
+```
+
+Hebt ein Element (zum Beispiel ein Wort) aus einer Fläche heraus, **mit den Original-Pixeln**, verkleinert es und setzt es in die Mitte. Die Lücke wird mit der Flächenfarbe gefüllt. Ausgabe: `base.png` (Bild ohne Element), `element.png` (Element auf transparentem Grund), `preview.png`.
+Voraussetzung: Der Rand der Box (`--box`) liegt auf **einfarbiger Fläche**, sonst stimmt die Füllfarbe nicht.
+
+### 6. `trace` und `upscale` (nur zum Vergleichen)
+
+```bash
+python pixelcut.py trace bild.png bild.svg --render bild_trace.png    # vtracer
+python pixelcut.py upscale bild.png gross.png    # holt Real-ESRGAN beim ersten Mal selbst
+```
+
+Zwei Fremdverfahren, damit man selbst messen kann, wie weit sie vom Original abweichen. Beide **ändern Pixel** und sind nicht mehr exakt.
+
+---
+
+## Was pixelcut NICHT kann
+
+Bitte vorher lesen, das spart Zeit.
+
+1. **Es erzeugt kein Bild aus dem Nichts.** Es braucht das Original. Es gibt keine Text-zu-Bild-Funktion, kein "male mir so etwas".
+2. **Es bildet ein Bild nicht ohne Vorlage nach.** Wer ein Bild "neu aufbauen" will, ohne dass es abweicht, braucht das Original als Quelle. Ein Bild, das nicht vom Original zu unterscheiden sein soll, **ist** das Original. Alles, was neu zeichnet (Hand, KI, Tracer), weicht ab. Die Zahlen unten zeigen, wie viel.
+3. **Es macht Bilder nicht größer, ohne Pixel zu erfinden.** Mehr Auflösung geht nur durch Rechnen. `upscale` nutzt dafür Real-ESRGAN, das neue Pixel erfindet. Das Ergebnis ist schärfer, aber nicht mehr exakt.
+4. **Keine Form-Erkennung, keine Objekte.** Es schneidet nach Geometrie (Winkel um eine Mitte), nicht nach Inhalt. Es erkennt keine Personen, Gegenstände oder Texte.
+5. **Keine freien Polygone oder Raster.** `split` schneidet Keile um **eine** Mitte. Für Raster gibt es gute fertige Werkzeuge (zum Beispiel `image-slicer`), für freie Formen Grafikprogramme.
+6. **`key` ist einfach gebaut.** Es erkennt das Element als "alles, was von der Hintergrundfarbe abweicht". Bei Verlauf, Muster oder Foto als Hintergrund liegt es daneben. Das Füllen der Lücke ist eine glatte Fläche (keine Textur, kein Inpainting).
+7. **`alpha` ist nur für weiße Hintergründe.** Andere Hintergrundfarben oder Fotos mit weißem Himmel werden nicht sauber freigestellt (bei Fotos `--opaque` benutzen).
+8. **Keine Animation, keine Videos, keine Vektorgrafik.** Nur Rastergrafik (PNG, JPEG usw.). Ausgabe ist PNG mit Alphakanal.
+9. **Bei Spalt und Tintenkante ist das Ergebnis nicht mehr bit-gleich.** Wer `--gap` und `--edge` benutzt, schneidet bewusst Pixel weg und malt eine Kante. Das ist ein Gestaltungswerkzeug. Exakt zusammensetzen geht mit `--gap 0 --edge 0`.
+10. **Kein Farbmanagement.** Es rechnet in sRGB-Werten, ICC-Profile werden ignoriert.
+11. **Keine Schnittstelle für Programme.** Nur die Kommandozeile (und die Python-Datei zum Einbinden), keine grafische Oberfläche.
+
+---
+
+## Messungen
+
+### Foto-Test
+
+Foto (Katze, CC0, 451 × 300): jeweils nachgebaut und mit `compare` gegen das Original gemessen.
+
+| Weg | SSIM | Mittlere Abweichung | Maximale Abweichung |
+|---|---|---|---|
+| **pixelcut** (`split` + `join`) | **1.0000** | **0.000** | **0** |
+| Bicubic 4x hoch und wieder runter | 0.9956 | 0.661 | 15 |
+| Real-ESRGAN 4x hoch und wieder runter | 0.9513 | 3.438 | 93 |
+| vtracer (als Vektor neu gezeichnet) | 0.8686 | 5.263 | 151 |
+
+![Vergleich](examples/photo_compare.png)
+
+Ausschnitt 3x vergrößert. Nur pixelcut ist vom Original nicht zu unterscheiden.
+
+### Zeichnung (Comic-Bild)
+
+| Verfahren | SSIM |
+|---|---|
+| [vtracer](https://github.com/visioncortex/vtracer) (Nachzeichnen, Standardwerte des Tools) | 0,96 |
+| Farbquantisierung + Konturen ([image-to-svg](https://github.com/oaustegard/claude-skills)) | 0,78 |
+| **pixelcut** (Original-Pixel) | ≈ 1,00 mit `--gap 0 --edge 0` (höchstens 0,5 von 255 bei der Zeichnung, 0,00 beim Foto) |
+
+---
+
+## Beispiele
+
+| Zeichnung (Demo) | Zerlegt, Teile über Weiß | Foto (CC0, scikit-image), zerlegt |
+|---|---|---|
+| ![demo](examples/demo.png) | ![split](examples/split_preview.png) | ![foto](examples/photo_split_preview.png) |
+
+`key` auf der Demo (Wort verkleinert und zentriert, Lücke gefüllt):
+
+![key](examples/key_preview.png)
+
+---
+
+## Tests
+
+```bash
+pip install -e ".[test]"
+pytest -q
+```
+
+145 Tests. Sie prüfen die gespeicherten Dateien: Rundlauf split + join ist exakt (Zeichnung, Foto, gerade und Zickzack), die Teile überlappen nicht, Polygone, Winkel, Mitte, Größe und dickster Punkt stimmen mit den Teilen überein, `compare`, `key` und `alpha` rechnen richtig, `join` verweigert fehlende oder falsch große Teile, `split` fasst fremde Dateien nicht an, und schlechte Eingaben ergeben eine klare Fehlerzeile. Eingebaute Fehler (Mutationen) werden gefangen.
+
+---
+
+## Wie es im Detail funktioniert
+
+- **Color-to-Alpha:** `alpha = 1 − min(R, G, B)`, Farbe = `(Pixel − (1 − alpha)) / alpha`. Über Weiß zusammengesetzt ergibt das wieder den Pixelwert.
+- **Keile:** Für jedes Pixel wird der Winkel zur Mitte berechnet. Der Keil ergibt sich aus den sortierten Trennwinkeln.
+- **Zacken:** Pro Trennlinie wird die Entfernung des Pixels von der Linie mit einer Dreieckswelle verglichen. Wer links der verschobenen Linie liegt, gehört zum einen Keil, wer rechts liegt, zum anderen. So haben beide Teile dieselbe Zackenkante ohne Lücke (außer dem gewollten Spalt).
+- **Trefferflächen:** Aus der Maske jedes Teils wird die Außenkontur gezogen und vereinfacht. Der dickste Punkt kommt aus der Distanztransformation.
+- **Key:** Hintergrundfarbe = Median des Box-Rands. Alles, was weiter als `--threshold` davon entfernt ist, gehört zum Element. Löcher darin werden gefüllt, die Lücke danach weich mit der Flächenfarbe überblendet.
+
+---
+
+## Lizenz
+
+MIT. Das Foto stammt aus `skimage.data` (CC0). Die Demo-Grafik ist selbst erzeugt (`make_demo.py`).
+
+Mit Claude Code von K&K AI gebaut.
+
+---
+
+Gefällt dir pixelcut? Ein Kaffee hilft, es weiterzubauen: [ko-fi.com/kkwonderland](https://ko-fi.com/kkwonderland)

pixelcut-1.3.0.dist-info/RECORD

@@ -0,0 +1,7 @@
+pixelcut.py,sha256=rOXHQNp1bVjhKHH_QXBxDOB2anwgc4-t1aa8PWgmhIg,45148
+pixelcut-1.3.0.dist-info/licenses/LICENSE,sha256=Vvu7JrldqGO9y5oqWdhmnl86v4OyGkod1CgOxZfTjJ8,1063
+pixelcut-1.3.0.dist-info/METADATA,sha256=xbVCvmGyee7vamsz-3IAAtjuzD-e_zSsOWP9SFpROtY,14590
+pixelcut-1.3.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+pixelcut-1.3.0.dist-info/entry_points.txt,sha256=E1Nxk3OsDP8JjVjIOEmdXn2dlvtxsIAzzooSa2-afLs,43
+pixelcut-1.3.0.dist-info/top_level.txt,sha256=ILT3ZqlnF4DHcTTUq-r8eL8hxS2bpqWIo91BCoGBNSI,9
+pixelcut-1.3.0.dist-info/RECORD,,

pixelcut-1.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.2.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pixelcut-1.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+pixelcut = pixelcut:main

pixelcut-1.3.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 K&K AI
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pixelcut-1.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pixelcut

pixelcut.py

@@ -0,0 +1,829 @@
+#!/usr/bin/env python3
+"""K&K pixelcut - cut a picture into parts without changing a single pixel.
+
+Most "recreate this image" tools redraw, trace or upscale, so the result is only similar. pixelcut does the opposite: it keeps
+the original pixels and only decides which part each pixel belongs to. Put the parts back together over white and you get the
+original back (max. deviation <= 1/255, checked by `--verify`).
+
+Commands
+  alpha   white background -> transparent (colour-to-alpha), exact over white
+  split   cut into wedges around a centre, dividing lines at free angles, straight or zig-zag, with hit-area polygons
+  join    put the parts back together over white (exact)
+  compare SSIM + pixel difference of two images
+  trace   (vtracer) redraw as SVG - approximate
+  upscale (Real-ESRGAN, auto-download) AI upscale - invents pixels
+  key     lift a foreground element (e.g. a word) out of a flat area, shrink it, put it in the middle, heal the hole
+
+Run `python pixelcut.py COMMAND -h` for the options.
+"""
+import argparse
+import json
+import os
+import re
+import shutil
+import stat
+import sys
+from pathlib import Path
+
+import cv2
+import numpy as np
+from PIL import Image, ImageOps
+
+
+PART_NAME = re.compile(r"part_\d+\.png")
+
+
+def manifest_files(m):
+    """Validate a pixelcut manifest and return its part file names. Raises ValueError for anything that is not one.
+    Manifests from v1.0/1.1 have no 'files' list: the names are then part_0..part_N-1."""
+    if not isinstance(m, dict) or not isinstance(m.get("parts"), list) or not m["parts"]:
+        raise ValueError("no parts")
+    size = m.get("size")
+    if not (isinstance(size, list) and len(size) == 2 and all(isinstance(v, int) and not isinstance(v, bool) and v > 0 for v in size)):
+        raise ValueError("bad size")
+    c = m.get("centre")
+    if not (isinstance(c, list) and len(c) == 2 and all(isinstance(v, (int, float)) and not isinstance(v, bool) for v in c)):
+        raise ValueError("bad centre")
+    if not all(isinstance(x, dict) and isinstance(x.get("part"), int) and isinstance(x.get("starts_at_angle"), (int, float)) for x in m["parts"]):
+        raise ValueError("bad part entries")
+    names = m.get("files") or ["part_%d.png" % k for k in range(len(m["parts"]))]
+    if not (isinstance(names, list) and len(names) == len(m["parts"]) == len(set(names))
+            and all(isinstance(x, str) and PART_NAME.fullmatch(x) for x in names)):
+        raise ValueError("bad file list")
+    return names
+
+
+JOURNAL = ".journal.json"
+
+
+def link_like(path):
+    """Symlink or Windows junction/reparse point: it points somewhere else, so whatever we do 'in' it happens elsewhere."""
+    st = os.lstat(path)
+    return stat.S_ISLNK(st.st_mode) or bool(getattr(st, "st_file_attributes", 0) & 0x400)
+
+
+def real_folder(folder, what):
+    if folder.exists() and (link_like(folder) or not folder.is_dir()):
+        sys.exit("%s is a link or not a folder - pixelcut will not work inside it (%s)" % (folder, what))
+
+
+def scratch_beside(path):
+    """A fresh private folder next to the target (same disk, so the final rename is atomic). Returns (folder, file inside it
+    with the target's name). Nothing that already exists can be hit: the folder name is unique and created by us."""
+    import tempfile
+    path = Path(path).resolve()
+    d = Path(tempfile.mkdtemp(prefix=".pixelcut_", dir=path.parent))
+    return d, d / path.name
+
+
+def publish(pairs):
+    """Replace several finished files at once: [(finished_file, destination), ...]. Existing destinations are moved aside first and
+    put back if anything goes wrong, so either all new files are in place or all old ones are. The aside folder is the truth about
+    what has to be restored (no bookkeeping that an abort could skip) and it is deleted only when it is empty again."""
+    import tempfile
+    for _, dest in pairs:
+        if os.path.lexists(dest) and (link_like(dest) or not Path(dest).is_file()):
+            sys.exit("error: %s exists and is not a plain file (folder or link) - nothing was changed" % dest)
+        if Path(dest).exists() and not os.access(dest, os.W_OK):
+            sys.exit("error: %s is read-only - nothing was changed" % dest)
+    aside = Path(tempfile.mkdtemp(prefix=".pixelcut_", dir=Path(pairs[0][1]).resolve().parent))
+    installed = []
+    try:
+        for i, (_, dest) in enumerate(pairs):
+            if Path(dest).exists():
+                os.replace(dest, aside / str(i))
+        for src, dest in pairs:
+            installed.append(dest)                            # before the move: an abort in between must still clean up
+            os.replace(src, dest)
+    except BaseException:
+        stuck = []
+        for dest in installed:
+            try:
+                Path(dest).unlink(missing_ok=True)
+            except OSError as e:
+                stuck.append("%s (%s)" % (dest, e))
+        for f in list(aside.iterdir()):
+            try:
+                os.replace(f, pairs[int(f.name)][1])
+            except OSError as e:
+                stuck.append("%s (%s)" % (pairs[int(f.name)][1], e))
+        if stuck:                                             # never destroy the only copy: say where it is
+            print("error: could not restore everything - your previous files are kept in %s\n  problem with: %s" % (aside, "; ".join(stuck)), file=sys.stderr)
+        else:
+            shutil.rmtree(aside, ignore_errors=True)
+        raise
+    shutil.rmtree(aside, ignore_errors=True)
+
+
+def refuse_inputs(inputs, outputs):
+    """An output must never be one of the input files - writing it would destroy what is being read."""
+    ins = {Path(x).resolve() for x in inputs}
+    for o in outputs:
+        if Path(o).resolve() in ins:
+            sys.exit("error: %s is also an input - choose a different output file" % o)
+
+
+def need_folder_of(path):
+    if not Path(path).resolve().parent.is_dir():
+        sys.exit("error: the folder for %s does not exist" % path)
+
+
+def save_atomic(img, path):
+    """Write beside the target, replace only when complete: an abort never leaves half a picture in place of a good one."""
+    need_folder_of(path)
+    d, tmp = scratch_beside(path)
+    try:
+        img.save(tmp)
+        os.replace(tmp, Path(path).resolve())
+    finally:
+        shutil.rmtree(d, ignore_errors=True)
+
+
+def foreign_entries(folder, extra=()):
+    """Names in a pixelcut scratch/backup folder that pixelcut did not put there. Only plain files with pixelcut's own
+    names count as ours - a directory or a link called part_0.png is foreign, whatever it is named."""
+    bad = []
+    for f in folder.iterdir():
+        own = (PART_NAME.fullmatch(f.name) or f.name in ("parts.json", JOURNAL, JOURNAL + ".tmp") or f.name in extra)
+        if not own or link_like(f) or not f.is_file():
+            bad.append(f.name)
+    return bad
+DONE = ".pixelcut_done"
+
+
+def write_journal(folder, names):
+    """Atomic: a crash leaves either the old or the new journal, never half a file."""
+    tmp = folder / (JOURNAL + ".tmp")
+    tmp.write_text(json.dumps(names))
+    os.replace(tmp, folder / JOURNAL)
+
+
+# ----------------------------------------------------------------------------- helpers
+def open_upright(path):
+    """Image.open plus the camera's rotation: a phone photo is stored sideways with an 'Orientation' tag, viewers turn it - so do we
+    (with a notice), otherwise the result would not look like what the person sees."""
+    im = Image.open(path)
+    try:
+        orient = im.getexif().get(274, 1)
+    except Exception:
+        orient = 1
+    if orient not in (1, None, 0):
+        print("note: %s is rotated by its EXIF orientation tag (%s) - turned upright like a viewer shows it" % (path, orient), file=sys.stderr)
+        im = ImageOps.exif_transpose(im)
+    return im
+
+
+def load_rgb(path):
+    """8-bit RGB. Transparency is composited over white and 16-bit data is scaled to 8 bit - both with a notice, never silently."""
+    im = open_upright(path)
+    if im.width * im.height > 150_000_000:
+        sys.exit("image too large (%d x %d = %d MP, limit 150 MP)" % (im.width, im.height, im.width * im.height // 1_000_000))
+    if getattr(im, "n_frames", 1) > 1:
+        print("note: %s has %d frames - only the first one is used" % (path, im.n_frames), file=sys.stderr)
+    deep = None
+    if Path(path).suffix.lower() in (".png", ".tif", ".tiff"):                            # Pillow cuts 48/64-bit PNG silently
+        deep = cv2.imdecode(np.fromfile(str(path), np.uint8), cv2.IMREAD_UNCHANGED)
+    if deep is not None and deep.dtype == np.uint16 and deep.ndim == 3:
+        print("note: %s is 16 bit per channel - scaled to 8 bit, so the result is not exact for the full range" % path, file=sys.stderr)
+        rgb16 = deep[:, :, :3][:, :, ::-1].astype(np.float64) if deep.shape[2] >= 3 else np.dstack([deep[:, :, 0]] * 3).astype(np.float64)
+        if deep.shape[2] == 4:                                                              # transparency over white, as for 8 bit
+            al = deep[:, :, 3:4].astype(np.float64) / 65535.0
+            rgb16 = rgb16 * al + 65535.0 * (1 - al)
+        return np.clip(rgb16 / 257.0 + 0.5, 0, 255).astype(np.uint8)
+    if im.mode == "CMYK":
+        print("note: %s is CMYK - converted to RGB, colours are not exact" % path, file=sys.stderr)
+    if im.mode in ("I;16", "I;16L", "I;16B", "I", "F"):
+        print("note: %s is %s (more than 8 bit) - scaled to 8 bit, so the result is not exact for the full range" % (path, im.mode), file=sys.stderr)
+        arr = np.array(im).astype(np.float64)
+        top = 65535.0 if im.mode.startswith("I;16") else max(arr.max(), 1.0)
+        return np.dstack([np.clip(arr / top * 255 + 0.5, 0, 255).astype(np.uint8)] * 3)
+    if im.mode in ("RGBA", "LA", "PA") or "transparency" in im.info:                      # includes L/RGB with a PNG colour key
+        print("note: %s has transparency - composited over white" % path, file=sys.stderr)
+        im = im.convert("RGBA")
+        bg = Image.new("RGBA", im.size, (255, 255, 255, 255))
+        im = Image.alpha_composite(bg, im)
+    return np.array(im.convert("RGB"))
+
+
+def finite(values, what):
+    if not all(np.isfinite(values)):
+        sys.exit("%s must be finite numbers" % what)
+    return values
+
+
+def color_to_alpha(rgb):
+    """RGBA such that compositing over white gives `rgb` back (standard colour-to-alpha against white)."""
+    f = rgb.astype(np.float32) / 255.0
+    a = np.clip(1.0 - f.min(2), 0, 1)
+    col = np.clip((f - (1 - a[:, :, None])) / np.maximum(a, 1e-4)[:, :, None], 0, 1)
+    col[a < 1e-3] = 0
+    return np.dstack([col * 255, a * 255]).round().astype(np.uint8)
+
+
+def over_white(rgba_list):
+    h, w = rgba_list[0].shape[:2]
+    acc = np.full((h, w, 3), 255.0, np.float32)
+    for im in rgba_list:
+        al = im[:, :, 3:4].astype(np.float32) / 255.0
+        acc = acc * (1 - al) + im[:, :, :3].astype(np.float32) * al
+    return acc
+
+
+def tri(t):
+    """Triangle wave -1..1 with sharp teeth, period 1."""
+    t = np.mod(t, 1.0)
+    return np.where(t < .5, 4 * t - 1, 3 - 4 * t)
+
+
+def contour_polygon(mask, eps):
+    cs, _ = cv2.findContours(mask.astype(np.uint8), cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+    if not cs:
+        return []
+    c = max(cs, key=cv2.contourArea)
+    ap = cv2.approxPolyDP(c, eps, True)[:, 0, :]
+    return [[int(x), int(y)] for x, y in ap]
+
+
+def contour_polygons(mask, eps, min_area=4):
+    """Every connected area as {outer, holes}: rings and islands are kept, unlike contour_polygon (largest outline only)."""
+    cs, hier = cv2.findContours(mask.astype(np.uint8), cv2.RETR_CCOMP, cv2.CHAIN_APPROX_NONE)
+    out = []
+    if hier is None:
+        return out
+    hier = hier[0]
+
+    def ring(c):
+        return [[int(x), int(y)] for x, y in cv2.approxPolyDP(c, eps, True)[:, 0, :]]
+    for i, c in enumerate(cs):
+        if hier[i][3] == -1 and cv2.contourArea(c) >= min_area:                       # outer ring; holes are its children
+            holes = [ring(cs[j]) for j in range(len(cs)) if hier[j][3] == i and cv2.contourArea(cs[j]) >= min_area]
+            out.append({"outer": ring(c), "holes": holes})
+    return out
+
+
+def fattest_point(mask):
+    if not mask.any():
+        return None                                           # nothing solid in this part (e.g. only faint pixels): no honest answer
+    d = cv2.distanceTransform(mask.astype(np.uint8), cv2.DIST_L2, 5)
+    y, x = np.unravel_index(np.argmax(d), d.shape)
+    return [int(x), int(y)]
+
+
+# ----------------------------------------------------------------------------- alpha
+def cmd_alpha(a):
+    refuse_inputs([a.input], [a.output])
+    rgb = load_rgb(a.input)
+    rgba = color_to_alpha(rgb)
+    save_atomic(Image.fromarray(rgba, "RGBA"), a.output)
+    if a.verify:
+        err = np.abs(over_white([rgba]) - rgb.astype(np.float32)).max()
+        print("max deviation over white: %.2f / 255" % err)
+
+
+# ----------------------------------------------------------------------------- split
+def split_sectors(shape, centre, angles, tooth, depth, gap, edge, region=None):
+    """Sector id per pixel (0..n-1, sector i starts at angles[i]), slit mask and ink-edge mask.
+
+    The dividing lines run from `centre` outwards at `angles` (degrees, screen angle: 0 = right, 90 = down). With depth > 0 each
+    line is a zig-zag (teeth of period `tooth`, amplitude `depth`) instead of straight. Lines may be uneven (any angles).
+    """
+    h, w = shape
+    cx, cy = centre
+    yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
+    dx, dy = xx - cx, yy - cy
+    r = np.hypot(dx, dy)
+    ang = (np.degrees(np.arctan2(dy, dx)) + 360) % 360
+    order = sorted(range(len(angles)), key=lambda i: angles[i])
+    ang_sorted = [angles[i] for i in order]
+    n = len(ang_sorted)
+    sector = np.zeros((h, w), np.int16)                       # sector k = from ang_sorted[k] to ang_sorted[k+1]
+    for k in range(n):
+        lo, hi = ang_sorted[k], ang_sorted[(k + 1) % n]
+        m = (ang >= lo) & (ang < hi) if hi > lo else (ang >= lo) | (ang < hi)
+        sector[m] = k
+    slit_dist = np.full((h, w), 1e9, np.float32)
+    for k in range(n):                                        # line k separates sector k-1 and k
+        bang = ang_sorted[k]
+        d = np.radians(((ang - bang + 180) % 360) - 180)
+        along, perp = r * np.cos(d), r * np.sin(d)
+        zig = depth * tri(along / tooth + .25 * k) if depth > 0 else 0.0
+        near = (np.abs(perp) <= depth + gap / 2 + edge + 2) & (along > 0)      # a narrow band along the line, never a wide wedge
+        if depth > 0:                                                          # straight lines: membership by angle is already exact
+            sector = np.where(near, np.where(perp > zig, k, (k - 1) % n), sector)
+        slit_dist = np.where(near, np.minimum(slit_dist, np.abs(perp - zig)), slit_dist)
+    limit = region if region is not None else np.ones((h, w), bool)
+    slit = (slit_dist < gap / 2) & limit
+    edge_zone = (slit_dist < gap / 2 + edge) & ~slit & limit
+    return sector, slit, edge_zone, order
+
+
+def cmd_split(a):
+    refuse_inputs([a.input], [Path(a.outdir) / n for n in ["parts.json"] + ["part_%d.png" % k for k in range(64)]])
+    rgb = load_rgb(a.input)
+    h, w = rgb.shape[:2]
+    rgba = np.dstack([rgb, np.full(rgb.shape[:2], 255, np.uint8)]) if a.opaque else color_to_alpha(rgb)
+    if rgba[:, :, 3].max() == 0:                              # no pixel has any alpha: there is literally nothing to cut
+        sys.exit("the image is completely white - nothing to cut (use --opaque to cut it anyway)")
+    if a.centre == "auto":                                    # centroid of everything that is not white
+        m = (rgb.min(2) < 250).astype(np.uint8)
+        M = cv2.moments(m, True)
+        centre = (M["m10"] / M["m00"], M["m01"] / M["m00"]) if M["m00"] > 0 else (w / 2.0, h / 2.0)
+    else:
+        try:
+            centre = tuple(float(v) for v in a.centre.split(","))
+            assert len(centre) == 2
+        except (ValueError, AssertionError):
+            sys.exit("--centre must look like 300,240 (x,y) or 'auto'")
+    finite(list(centre), "--centre")
+    if a.simplify < 0 or not np.isfinite(a.simplify):
+        sys.exit("--simplify must be 0 or greater")
+    try:
+        angles = [float(v) for v in a.angles.split(",")]
+        finite(angles, "--angles")
+        angles = [v % 360.0 for v in angles]                  # 360 means 0, -90 means 270
+    except ValueError:
+        sys.exit("--angles must be numbers separated by commas, e.g. 32,148,214,327")
+    if len(angles) < 2 or len({round(v % 360, 6) for v in angles}) != len(angles):
+        sys.exit("--angles needs at least two different angles")
+    for flag, value in (("--gap", a.gap), ("--edge", a.edge), ("--depth", a.depth), ("--tooth", a.tooth)):
+        if not np.isfinite(value) or value < 0:
+            sys.exit("%s must be a finite number, 0 or greater" % flag)
+    if a.gap > 100 or a.edge > 100 or a.depth > 1000:
+        sys.exit("--gap/--edge/--depth are in pixels; these values are far too large")
+    if a.depth > 0 and a.tooth <= 0:
+        sys.exit("--tooth must be greater than 0 (or use --depth 0 for straight lines)")
+    region = None
+    if a.only_inside:                                         # cut only inside the largest non-white blob, leave satellites whole
+        m = (rgb.min(2) < 250).astype(np.uint8)
+        m = cv2.morphologyEx(m, cv2.MORPH_CLOSE, np.ones((7, 7), np.uint8))
+        n, lab, st, _ = cv2.connectedComponentsWithStats(m)
+        if n > 1:                                             # an all-background image has no blob: cut the whole picture
+            big = 1 + int(np.argmax(st[1:, cv2.CC_STAT_AREA]))
+            region = cv2.dilate((lab == big).astype(np.uint8), np.ones((5, 5), np.uint8)) > 0
+    sector, slit, edge_zone, order = split_sectors((h, w), centre, angles, a.tooth, a.depth, a.gap, a.edge, region)
+    if region is not None:                                    # satellites stay whole: one sector per connected area outside the main blob
+        content = cv2.morphologyEx((rgb.min(2) < 250).astype(np.uint8), cv2.MORPH_CLOSE, np.ones((7, 7), np.uint8))
+        nl, lab, _, _ = cv2.connectedComponentsWithStats(np.where(region, 0, content).astype(np.uint8))
+        for c in range(1, nl):
+            cc = lab == c
+            sector[cc] = np.bincount(sector[cc].ravel()).argmax()
+    out = Path(a.outdir)
+    out.mkdir(parents=True, exist_ok=True)
+    for scratch in (DONE, ".pixelcut_old", ".pixelcut_new"):
+        real_folder(out / scratch, "scratch folder")
+    if (out / DONE).is_dir():                                 # the swap had finished, only the clean-up was interrupted
+        if foreign_entries(out / DONE):
+            sys.exit("%s holds files pixelcut did not put there - check and remove it first" % (out / DONE))
+        shutil.rmtree(out / DONE)
+    leftover = out / ".pixelcut_old"                          # an earlier run was interrupted while swapping: its old set is the only full copy
+    if leftover.is_dir():
+        strange = foreign_entries(leftover)
+        if strange:
+            sys.exit("%s holds files pixelcut did not put there (%s) - check and remove it first" % (leftover, ", ".join(strange)))
+        journal = leftover / JOURNAL
+        if journal.is_file():                                 # files the interrupted run had already put in place: take them out again
+            try:
+                for name in json.loads(journal.read_text()):
+                    if isinstance(name, str) and (PART_NAME.fullmatch(name) or name == "parts.json") and (out / name).is_file():
+                        (out / name).unlink()
+            except ValueError:
+                pass
+            journal.unlink()
+        if (leftover / (JOURNAL + ".tmp")).is_file():
+            (leftover / (JOURNAL + ".tmp")).unlink()
+        for f in leftover.iterdir():                          # only pixelcut's own names are ever restored
+            os.replace(f, out / f.name)
+        shutil.rmtree(leftover)
+        print("note: an interrupted earlier run was rolled back first (previous parts restored)", file=sys.stderr)
+    old_manifest = out / "parts.json"                        # only files that an earlier pixelcut run listed may be replaced
+    ours = set()
+    if old_manifest.exists():
+        try:
+            ours = set(manifest_files(json.loads(old_manifest.read_text())))
+        except Exception:                                    # a parts.json that is not ours is never touched
+            sys.exit("%s exists but is not a pixelcut manifest - use an empty folder" % old_manifest)
+    clash = [("part_%d.png" % k) for k in range(len(angles)) if (out / ("part_%d.png" % k)).exists() and ("part_%d.png" % k) not in ours]
+    if clash:
+        sys.exit("%s already exists in %s and was not written by pixelcut - use an empty folder" % (", ".join(clash), out))
+    staging = out / ".pixelcut_new"                           # everything is written here first, replacing happens only when all parts worked
+    if staging.exists():
+        if foreign_entries(staging):
+            sys.exit("%s exists and does not look like pixelcut's own scratch folder - remove it first" % staging)
+        shutil.rmtree(staging)
+    staging.mkdir()
+    ink = np.array([20, 16, 14], np.uint8)
+    parts, info = [], []
+    for k in range(len(angles)):
+        img = rgba.copy()
+        img[(sector != k) | slit] = 0
+        if a.edge > 0:
+            e = edge_zone & (sector == k) & (img[:, :, 3] > 0)
+            img[e, :3] = ink
+            img[e, 3] = 255
+        parts.append(img)
+        Image.fromarray(img, "RGBA").save(staging / ("part_%d.png" % k))
+        solid = ((sector == k) & ~slit & (rgba[:, :, 3] > 8)).astype(np.uint8)
+        info.append({"part": k, "starts_at_angle": sorted(angles)[k],
+                     "polygon": contour_polygon(solid, a.simplify), "polygons": contour_polygons(solid, a.simplify),
+                     "fattest_point": fattest_point(solid)})
+    files = ["part_%d.png" % k for k in range(len(parts))]
+    (staging / "parts.json").write_text(json.dumps({"size": [w, h], "centre": list(centre), "files": files, "parts": info}, indent=1))
+    backup = out / ".pixelcut_old"                            # old files are moved aside, not deleted - an abort rolls back
+    backup.mkdir()                                            # (a leftover one was restored above, so this is always new)
+    write_journal(backup, [])                       # names this run is installing, written BEFORE each install (all old files are aside by then)
+    moved, installed = [], []
+    try:
+        for name in sorted(ours | {"parts.json"}):
+            if (out / name).is_file():
+                os.replace(out / name, backup / name)
+                moved.append(name)
+        for name in files + ["parts.json"]:
+            installed.append(name)
+            write_journal(backup, installed)
+            os.replace(staging / name, out / name)
+    except BaseException:
+        for name in installed:                                # 1. take back exactly what this run put in place (journal stays: an interrupted
+            if (out / name).is_file():                        #    roll-back is finished by the next run from the same list)
+                (out / name).unlink()
+        (backup / JOURNAL).unlink(missing_ok=True)            # 2. only now may the journal go - the files restored next must not be taken out again
+        for f in list(backup.iterdir()):                      # 3. restore whatever is really in the backup (an abort between the move and the
+            if f.name != JOURNAL + ".tmp":                    #    bookkeeping must not hide a file), and never delete a backup that is not empty
+                os.replace(f, out / f.name)
+        (backup / (JOURNAL + ".tmp")).unlink(missing_ok=True)
+        backup.rmdir()
+        shutil.rmtree(staging, ignore_errors=True)
+        raise
+    os.replace(backup, out / DONE)                            # commit point: from here on the new set is the truth
+    shutil.rmtree(out / DONE)
+    shutil.rmtree(staging)
+    print("wrote %d parts + parts.json to %s" % (len(parts), out))
+    if a.verify:
+        # without slit and edge the parts must add up to the original over white
+        flat = [rgba.copy() for _ in parts]
+        for k, im in enumerate(flat):
+            im[sector != k] = 0
+        err = np.abs(over_white(flat) - rgb.astype(np.float32)).max()
+        print("max deviation over white without slit: %.2f / 255" % err)
+        real = over_white([np.array(Image.open(out / ("part_%d.png" % k)).convert("RGBA")) for k in range(len(parts))])
+        real_err = np.abs(real - rgb.astype(np.float32)).max()
+        print("saved files joined over white:        %.2f / 255 (with --gap %.1f --edge %.1f the slit is visible on purpose; 0 slit = exact)" % (real_err, a.gap, a.edge))
+
+
+# ----------------------------------------------------------------------------- key
+def cmd_key(a):
+    refuse_inputs([a.input], [Path(a.outdir) / n for n in ("base.png", "element.png", "preview.png")])
+    rgb = load_rgb(a.input)
+    h, w = rgb.shape[:2]
+    try:
+        x0, y0, x1, y1 = (int(v) for v in a.box.split(","))
+    except ValueError:
+        sys.exit("--box must look like x0,y0,x1,y1 (four whole numbers)")
+    if not (0 <= x0 < x1 <= w and 0 <= y0 < y1 <= h):
+        sys.exit("--box %s does not lie inside the image (%dx%d) or is empty/reversed" % (a.box, w, h))
+    if not (np.isfinite(a.scale) and 0 < a.scale <= 10):
+        sys.exit("--scale must be greater than 0 and at most 10")
+    if a.close < 1 or a.close > 99 or not np.isfinite(a.threshold) or a.threshold < 0:
+        sys.exit("--close must be 1..99 and --threshold 0 or greater")
+    roi = rgb[y0:y1, x0:x1].astype(np.float32)
+    ring = np.concatenate([roi[:3].reshape(-1, 3), roi[-3:].reshape(-1, 3), roi[:, :3].reshape(-1, 3), roi[:, -3:].reshape(-1, 3)])
+    fill = np.median(ring, 0)                                  # the flat colour the element sits on
+    diff = np.abs(roi - fill).max(2)
+    fg = (diff > a.threshold).astype(np.uint8)
+    fg = cv2.morphologyEx(fg, cv2.MORPH_CLOSE, cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (a.close, a.close)))
+    cs, _ = cv2.findContours(fg, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_NONE)
+    fg = np.zeros_like(fg)
+    cv2.drawContours(fg, cs, -1, 1, -1)                        # holes (counters, highlights) filled
+    ys, xs = np.nonzero(fg)
+    if len(xs) == 0:
+        sys.exit("nothing stands out from the background inside --box (try a lower --threshold)")
+    bx0, bx1, by0, by1 = xs.min(), xs.max(), ys.min(), ys.max()
+    # heal the hole with the flat colour, softly blended
+    soft = cv2.GaussianBlur(cv2.dilate(fg, np.ones((5, 5), np.uint8)).astype(np.float32), (0, 0), 1.2)[:, :, None]
+    healed = rgb.astype(np.float32).copy()
+    healed[y0:y1, x0:x1] = roi * (1 - soft) + fill * soft
+    # the element: exact pixels, shrunk, centred on (cx, cy)
+    try:
+        cx, cy = (float(v) for v in a.to.split(",")) if a.to else ((x0 + x1) / 2, (y0 + y1) / 2)
+    except ValueError:
+        sys.exit("--to must look like x,y")
+    finite([cx, cy], "--to")
+    el = rgb[y0:y1, x0:x1][by0:by1 + 1, bx0:bx1 + 1]
+    al = cv2.GaussianBlur(fg[by0:by1 + 1, bx0:bx1 + 1].astype(np.float32), (0, 0), .8)
+    kw, kh = max(1, int(round(el.shape[1] * a.scale))), max(1, int(round(el.shape[0] * a.scale)))
+    el = cv2.resize(el, (kw, kh), interpolation=cv2.INTER_AREA)
+    al = cv2.resize(al, (kw, kh), interpolation=cv2.INTER_AREA)
+    layer = np.zeros((h, w, 4), np.uint8)
+    px, py = int(round(cx - kw / 2)), int(round(cy - kh / 2))
+    if px < 0 or py < 0 or px + kw > w or py + kh > h:
+        sys.exit("the element would leave the image at --to %s (needs %dx%d px around that point)" % (a.to, kw, kh))
+    layer[py:py + kh, px:px + kw, :3] = el
+    layer[py:py + kh, px:px + kw, 3] = np.clip(al * 255, 0, 255).astype(np.uint8)
+    out = Path(a.outdir)
+    out.mkdir(parents=True, exist_ok=True)
+    comp = healed.copy()
+    al3 = layer[:, :, 3:4].astype(np.float32) / 255
+    comp = comp * (1 - al3) + layer[:, :, :3].astype(np.float32) * al3
+    work, _ = scratch_beside(out / "base.png")                # all three are finished first, then published together
+    try:
+        Image.fromarray(np.clip(healed, 0, 255).round().astype(np.uint8)).save(work / "base.png")
+        Image.fromarray(layer, "RGBA").save(work / "element.png")
+        Image.fromarray(np.clip(comp, 0, 255).round().astype(np.uint8)).save(work / "preview.png")
+        publish([(work / n, out / n) for n in ("base.png", "element.png", "preview.png")])
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    print("wrote base.png (hole healed), element.png (exact pixels, scale %.2f), preview.png" % a.scale)
+
+
+
+# ----------------------------------------------------------------------------- join / compare
+def cmd_join(a):
+    """Put parts back together (over white or a colour) - the way to 'rebuild' a picture from its exact pieces."""
+    manifest = Path(a.parts) / "parts.json"
+    size = None
+    if manifest.exists():                                     # the manifest says which parts belong together - all of them are needed
+        try:
+            m = json.loads(manifest.read_text())
+            n = len(m["parts"])
+            size = tuple(m["size"])
+            assert len(size) == 2 and all(isinstance(v, int) and v > 0 for v in size) and n > 0
+            names = m.get("files") or ["part_%d.png" % k for k in range(n)]
+            assert len(names) == n == len(set(names)) and all(isinstance(x, str) and PART_NAME.fullmatch(x) for x in names)
+        except (ValueError, KeyError, TypeError, AssertionError, AttributeError):
+            sys.exit("parts.json is damaged (needs 'size' [w,h], 'parts' and matching 'files')")
+        files = [Path(a.parts) / x for x in names]
+        missing = [f.name for f in files if not f.exists()]
+        if missing:
+            sys.exit("parts.json lists %d parts but these are missing: %s" % (n, ", ".join(missing)))
+    else:
+        files = sorted(f for f in Path(a.parts).glob("part_*.png") if PART_NAME.fullmatch(f.name))
+        numbers = sorted(int(f.stem.split("_")[1]) for f in files)
+        gaps = [k for k in range(numbers[-1] + 1) if k not in numbers] if numbers else []
+        if gaps:
+            sys.exit("part numbering has a gap (missing part_%d.png) - without parts.json every part is needed" % gaps[0])
+    if not files:
+        sys.exit("no part_*.png in %s" % a.parts)
+    ims = [np.array(Image.open(f).convert("RGBA")) for f in files]
+    shapes = {im.shape[:2] for im in ims}
+    if len(shapes) != 1 or (size and (size[1], size[0]) not in shapes):
+        sys.exit("the parts do not all have the same size%s" % (" as parts.json says" if size else ""))
+    refuse_inputs(files + [Path(a.parts) / "parts.json"], [a.output])
+    out = over_white(ims)
+    save_atomic(Image.fromarray(np.clip(out, 0, 255).round().astype(np.uint8)), a.output)
+    print("joined %d parts -> %s" % (len(ims), a.output))
+
+
+def measure(x, y):
+    """(SSIM on grey, mean abs diff, max abs diff) of two same-size RGB arrays."""
+    from skimage.metrics import structural_similarity
+    gx = cv2.cvtColor(x, cv2.COLOR_RGB2GRAY)
+    gy = cv2.cvtColor(y, cv2.COLOR_RGB2GRAY)
+    d = np.abs(x.astype(np.float32) - y.astype(np.float32))
+    win = min(7, min(gx.shape) // 2 * 2 - 1 if min(gx.shape) % 2 == 0 else min(gx.shape))
+    ss = structural_similarity(gx, gy, win_size=win) if win >= 3 else float("nan")   # tiny images: no SSIM window
+    return ss, float(d.mean()), float(d.max())
+
+
+def cmd_compare(a):
+    x, y = load_rgb(a.first), load_rgb(a.second)
+    if x.shape != y.shape:
+        if not a.resize:
+            sys.exit("the images have different sizes (%dx%d vs %dx%d) - use --resize to scale the second one" % (x.shape[1], x.shape[0], y.shape[1], y.shape[0]))
+        y = cv2.resize(y, (x.shape[1], x.shape[0]), interpolation=cv2.INTER_AREA)
+    ss, mean, mx = measure(x, y)
+    print("SSIM %.4f   mean |diff| %.3f   max |diff| %d" % (ss, mean, mx))
+
+
+# ----------------------------------------------------------------------------- trace / upscale (optional external engines)
+def find_chrome():
+    import shutil
+    for c in ("chrome", "google-chrome", "chromium", "msedge", "brave"):
+        w = shutil.which(c)
+        if w:
+            return w
+    for c in (r"C:\Program Files\Google\Chrome\Application\chrome.exe", r"C:\Program Files (x86)\Microsoft\Edge\Application\msedge.exe",
+              "/usr/bin/google-chrome", "/usr/bin/chromium", "/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"):
+        if Path(c).exists():
+            return c
+    return None
+
+
+def cmd_trace(a):
+    """Redraw the picture as vector shapes (vtracer). Approximate by nature: use `compare` to see how far it is from the original."""
+    import vtracer
+    if not Path(a.input).is_file():
+        sys.exit("error: %s does not exist" % a.input)
+    if not (0 <= a.speckle <= 128 and 1 <= a.colors <= 8 and 0 <= a.layers <= 255):
+        sys.exit("--speckle must be 0..128, --colors 1..8, --layers 0..255")
+    if not Path(a.output).resolve().parent.is_dir():
+        sys.exit("error: the folder for %s does not exist" % a.output)
+    here = Path(a.input).resolve()
+    if Path(a.output).resolve() == here:
+        sys.exit("error: the SVG must be a different file than the input")
+    if a.render and Path(a.render).resolve() in (here, Path(a.output).resolve()):
+        sys.exit("error: --render must be a different file than the input and the SVG")
+    work, tmp_svg = scratch_beside(a.output)
+    try:
+        vtracer.convert_image_to_svg_py(a.input, str(tmp_svg), colormode="color", hierarchical="stacked", mode="spline",
+                                        filter_speckle=a.speckle, color_precision=a.colors, layer_difference=a.layers,
+                                        corner_threshold=60, length_threshold=3.5, splice_threshold=45, path_precision=3)
+        os.replace(tmp_svg, Path(a.output).resolve())
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    print("wrote", a.output)
+    if a.render:
+        import subprocess
+        import tempfile
+        render_target = Path(a.render).resolve()
+        if render_target in (Path(a.input).resolve(), Path(a.output).resolve()):
+            sys.exit("error: --render must be a different file than the input and the SVG")
+        chrome = find_chrome()
+        if not chrome:
+            sys.exit("--render needs Chrome/Edge/Brave")
+        w, h = Image.open(a.input).size
+        tmp = tempfile.TemporaryDirectory()
+        t = Path(tmp.name)
+        (t / "p.html").write_text('<html><body style="margin:0;background:#fff"><img src="%s" width=%d height=%d></body></html>'
+                                  % (Path(a.output).resolve().as_uri(), w, h))
+        shot = t / "shot.png"                                 # render aside, replace the target only when it worked
+        try:
+            subprocess.run([chrome, "--headless=new", "--disable-gpu", "--hide-scrollbars", "--allow-file-access-from-files",
+                            "--user-data-dir=" + str(t / "prof"), "--window-size=%d,%d" % (w, h), "--screenshot=" + str(shot),
+                            (t / "p.html").as_uri()], capture_output=True, timeout=120)
+            if not shot.exists():
+                sys.exit("error: Chrome did not produce a picture - %s was left as it was" % a.render)
+            wd, staged = scratch_beside(render_target)        # copy beside the target first (may be another disk), then one atomic rename
+            try:
+                shutil.copyfile(shot, staged)
+                os.replace(staged, render_target)
+            finally:
+                shutil.rmtree(wd, ignore_errors=True)
+        finally:
+            shutil.rmtree(tmp.name, ignore_errors=True)       # browser profile included
+        print("rendered", a.render)
+
+
+ESRGAN_SHA256 = {"windows": "abc02804e17982a3be33675e4d471e91ea374e65b70167abc09e31acb412802d",
+                 "ubuntu": "e5aa6eb131234b87c0c51f82b89390f5e3e642b7b70f2b9bbe95b6a285a40c96",
+                 "macos": "e0ad05580abfeb25f8d8fb55aaf7bedf552c375b5b4d9bd3c8d59764d2cc333a"}
+ESRGAN_URL = "https://github.com/xinntao/Real-ESRGAN/releases/download/v0.2.5.0/realesrgan-ncnn-vulkan-20220424-%s.zip"
+
+
+def ensure_esrgan():
+    """Find realesrgan-ncnn-vulkan; if it is missing, download the official release once into ~/.cache/pixelcut.
+    Returns None when this machine cannot run it (e.g. ARM Linux)."""
+    import platform
+    import shutil
+    import urllib.request
+    import zipfile
+    found = shutil.which("realesrgan-ncnn-vulkan")
+    if found:
+        return found
+    osname = {"win32": "windows", "darwin": "macos"}.get(sys.platform, "ubuntu")
+    if platform.machine().lower() not in ("amd64", "x86_64") and osname != "macos":
+        return None
+    exename = "realesrgan-ncnn-vulkan" + (".exe" if osname == "windows" else "")
+    cache = Path.home() / ".cache" / "pixelcut" / "realesrgan"
+    exe = next(cache.rglob(exename), None) if cache.exists() else None
+    if exe:
+        return str(exe)
+    cache.mkdir(parents=True, exist_ok=True)
+    zpath = cache / "release.zip"
+    print("realesrgan-ncnn-vulkan not found - downloading the official release (~50 MB, once) ...")
+    try:
+        import hashlib
+        import socket
+        socket.setdefaulttimeout(60)                          # a dead connection must end in the Lanczos fallback, not hang
+        urllib.request.urlretrieve(ESRGAN_URL % osname, zpath)
+        if hashlib.sha256(zpath.read_bytes()).hexdigest() != ESRGAN_SHA256[osname]:
+            zpath.unlink()
+            print("download rejected: checksum does not match the known Real-ESRGAN release")
+            return None
+        with zipfile.ZipFile(zpath) as z:
+            for member in z.namelist():                       # no path may leave the cache folder
+                if not (cache / member).resolve().is_relative_to(cache.resolve()):
+                    raise ValueError("unsafe path in archive: %s" % member)
+            z.extractall(cache)
+        zpath.unlink()
+    except Exception as e:
+        print("download failed (%s)" % e)
+        return None
+    exe = next(cache.rglob(exename), None)
+    if exe and osname != "windows":
+        exe.chmod(0o755)
+    return str(exe) if exe else None
+
+
+def lanczos_upscale(a, why):
+    """Fallback without AI: plain Lanczos resize. Smooth, but no invented detail."""
+    print("Real-ESRGAN not usable here (%s) - using plain Lanczos resize instead (no AI detail)." % why)
+    im = open_upright(a.input)
+    im = im.convert("RGBA" if (im.mode in ("RGBA", "LA", "PA") or "transparency" in im.info) else "RGB")   # keep transparency
+    save_atomic(im.resize((im.width * a.scale, im.height * a.scale), Image.LANCZOS), a.output)
+    print("wrote", a.output)
+
+
+def cmd_upscale(a):
+    """AI upscale with Real-ESRGAN (realesrgan-ncnn-vulkan). New pixels are invented: sharper, but not exact any more.
+    Falls back to Lanczos where the engine cannot run (ARM, no Vulkan GPU)."""
+    import subprocess
+    if not 1 <= a.scale <= 8:
+        sys.exit("--scale must be a whole number from 1 to 8")
+    refuse_inputs([a.input], [a.output])
+    need_folder_of(a.output)
+    if a.no_ai:
+        return lanczos_upscale(a, "--no-ai")
+    exe = a.bin or ensure_esrgan()
+    if not exe:
+        return lanczos_upscale(a, "no build for this machine")
+    target = Path(a.output).resolve()
+    work, tmp = scratch_beside(target)                        # the engine writes into a private folder beside the target; only a finished file replaces it
+    try:
+        subprocess.run([exe, "-i", str(Path(a.input).resolve()), "-o", str(tmp), "-n", a.model, "-s", str(a.scale)],
+                       check=True, cwd=str(Path(exe).parent), capture_output=True, timeout=1800)
+        if not tmp.is_file() or tmp.stat().st_size == 0:
+            raise OSError("the engine produced no picture")
+        os.replace(tmp, target)
+    except subprocess.TimeoutExpired:
+        return lanczos_upscale(a, "the engine did not finish in 30 minutes")
+    except OSError as e:
+        return lanczos_upscale(a, "cannot start: %s" % e)
+    except subprocess.CalledProcessError:
+        return lanczos_upscale(a, "needs a Vulkan GPU/driver")
+    finally:
+        shutil.rmtree(work, ignore_errors=True)
+    print("wrote", a.output)
+
+
+# ----------------------------------------------------------------------------- cli
+def main(argv=None):
+    for stream in (sys.stdout, sys.stderr):                   # a path with characters the console cannot show must not turn a finished job into an error
+        try:
+            stream.reconfigure(errors="backslashreplace")
+        except (AttributeError, ValueError):
+            pass
+    p = argparse.ArgumentParser(prog="pixelcut", description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("alpha", help="white background -> transparent, exact over white")
+    s.add_argument("input"); s.add_argument("output")
+    s.add_argument("--verify", action="store_true", help="print the max deviation over white")
+    s.set_defaults(fn=cmd_alpha)
+
+    s = sub.add_parser("split", help="cut into wedges with straight or zig-zag dividing lines")
+    s.add_argument("input"); s.add_argument("outdir")
+    s.add_argument("--centre", default="auto", help="x,y of the centre or 'auto' (centroid of the non-white area)")
+    s.add_argument("--angles", default="45,135,225,315", help="angles of the dividing lines in degrees (0 = right, 90 = down); free, e.g. 32,148,214,327")
+    s.add_argument("--tooth", type=float, default=18.0, help="zig-zag period in px")
+    s.add_argument("--depth", type=float, default=9.0, help="zig-zag amplitude in px, 0 = straight lines")
+    s.add_argument("--gap", type=float, default=2.6, help="width of the slit in px")
+    s.add_argument("--edge", type=float, default=3.2, help="thin ink edge along the slit in px, 0 = none")
+    s.add_argument("--only-inside", action="store_true", help="cut only the biggest blob, keep satellites (clouds, dots) whole")
+    s.add_argument("--simplify", type=float, default=2.0, help="polygon simplification in px (for hit areas)")
+    s.add_argument("--opaque", action="store_true", help="photos: keep every pixel opaque, no white-to-alpha")
+    s.add_argument("--verify", action="store_true")
+    s.set_defaults(fn=cmd_split)
+
+    s = sub.add_parser("key", help="lift a foreground element out of a flat area, shrink and centre it, heal the hole")
+    s.add_argument("input"); s.add_argument("outdir")
+    s.add_argument("--box", required=True, help="x0,y0,x1,y1 box around the element; its border must be flat background")
+    s.add_argument("--scale", type=float, default=.55)
+    s.add_argument("--to", help="x,y where the element is centred (default: centre of the box)")
+    s.add_argument("--threshold", type=float, default=40, help="colour distance from the flat background that counts as element")
+    s.add_argument("--close", type=int, default=9, help="closing kernel px, joins letters and fills gaps")
+    s.set_defaults(fn=cmd_key)
+
+    s = sub.add_parser("join", help="put parts_dir/part_*.png back together over white")
+    s.add_argument("parts"); s.add_argument("output")
+    s.set_defaults(fn=cmd_join)
+
+    s = sub.add_parser("compare", help="SSIM and pixel difference of two images")
+    s.add_argument("first"); s.add_argument("second")
+    s.add_argument("--resize", action="store_true", help="scale the second image to the size of the first (otherwise different sizes are an error)")
+    s.set_defaults(fn=cmd_compare)
+
+    s = sub.add_parser("trace", help="redraw as SVG (vtracer): approximate")
+    s.add_argument("input"); s.add_argument("output")
+    s.add_argument("--render", help="also render the SVG to this PNG (needs Chrome/Edge/Brave)")
+    s.add_argument("--speckle", type=int, default=2); s.add_argument("--colors", type=int, default=7); s.add_argument("--layers", type=int, default=8)
+    s.set_defaults(fn=cmd_trace)
+
+    s = sub.add_parser("upscale", help="AI upscale (Real-ESRGAN, downloaded automatically on first use): invents pixels")
+    s.add_argument("input"); s.add_argument("output")
+    s.add_argument("--scale", type=int, default=4); s.add_argument("--model", default="realesrgan-x4plus-anime")
+    s.add_argument("--bin", help="path to realesrgan-ncnn-vulkan (default: automatic)")
+    s.add_argument("--no-ai", action="store_true", help="plain Lanczos resize: no download, no engine, works offline")
+    s.set_defaults(fn=cmd_upscale)
+
+    a = p.parse_args(argv)
+    try:
+        a.fn(a)
+    except (SystemExit, KeyboardInterrupt):
+        raise
+    except BaseException as e:                                # includes pyo3 PanicException, which is not an Exception
+        if os.environ.get("PIXELCUT_DEBUG"):
+            raise
+        sys.exit("error: %s (set PIXELCUT_DEBUG=1 for the full trace)" % (str(e).strip().splitlines() or [type(e).__name__])[0])
+
+
+if __name__ == "__main__":
+    sys.exit(main())