kk-meshcut 0.2.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 K&K AI
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
@@ -0,0 +1,278 @@
1
+ Metadata-Version: 2.4
2
+ Name: kk-meshcut
3
+ Version: 0.2.0
4
+ Summary: K&K meshcut - cut 3D meshes into parts exactly and put them back together, with a round-trip proof
5
+ License: MIT
6
+ Project-URL: Homepage, https://github.com/CalyieX/meshcut
7
+ Project-URL: Browser, https://calyiex.github.io/meshcut/
8
+ Project-URL: Issues, https://github.com/CalyieX/meshcut/issues
9
+ Keywords: 3d,mesh,stl,3d-printing,slicing,split,boolean,3mf,glb,obj,ply,mcp,segmentation,ai
10
+ Classifier: Programming Language :: Python :: 3
11
+ Classifier: License :: OSI Approved :: MIT License
12
+ Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
13
+ Classifier: Intended Audience :: Developers
14
+ Requires-Python: >=3.9
15
+ Description-Content-Type: text/markdown
16
+ License-File: LICENSE
17
+ Requires-Dist: numpy<3,>=1.23
18
+ Provides-Extra: test
19
+ Requires-Dist: pytest; extra == "test"
20
+ Requires-Dist: hypothesis; extra == "test"
21
+ Provides-Extra: check
22
+ Requires-Dist: pytest; extra == "check"
23
+ Requires-Dist: hypothesis; extra == "check"
24
+ Requires-Dist: trimesh; extra == "check"
25
+ Requires-Dist: manifold3d; extra == "check"
26
+ Requires-Dist: shapely; extra == "check"
27
+ Requires-Dist: mapbox-earcut; extra == "check"
28
+ Requires-Dist: rtree; extra == "check"
29
+ Requires-Dist: networkx; extra == "check"
30
+ Requires-Dist: scipy; extra == "check"
31
+ Dynamic: license-file
32
+
33
+ # K&K meshcut
34
+
35
+ ![license](https://img.shields.io/badge/license-MIT-blue) ![python](https://img.shields.io/badge/python-3.9%2B-informational) ![round trip](https://img.shields.io/badge/Rundlauf-bitgenau-brightgreen) ![tests](https://github.com/CalyieX/meshcut/actions/workflows/ci.yml/badge.svg)
36
+
37
+ [![Unterstützen auf Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/kkwonderland)
38
+
39
+ **3D-Netze zerlegen und wieder zusammensetzen, mit Beweis, dass nichts verloren geht.**
40
+ *Cut 3D meshes into parts and put them back together, with a round-trip proof.*
41
+
42
+ **English in short:** a small command-line tool and Python library that splits triangle meshes (STL, OBJ, PLY, GLB, 3MF) by planes, grids, print-bed size, wedges around an axis, or along a per-triangle label map, caps every cut with a watertight lid, and joins the parts back. With the `meshcut.json` sidecar the join restores the *original triangles* and a SHA-256 over the triangle set proves it (bit-exact in 64-bit formats, after float32 rounding in STL/GLB). `meshcut segment` finds (and names) parts automatically - built-in methods, a local model, or any hosted service behind one adapter - and the result is always a per-triangle label map, so the exact join and the proof still apply. An MCP server and an HTTP API expose the same tools to agents. It also runs in the browser (Pyodide), nothing is uploaded. Everything below is in German.
43
+
44
+ **Auf einen Blick**
45
+
46
+ - **Rundlauf mit Beweis:** `split` → `join` ergibt dieselben Dreiecke (SHA-256 über die Dreiecksmenge), `verify` prüft zusätzlich Volumen, Fläche, wasserdicht und Euler-Zahl.
47
+ - **Viele Arten zu schneiden:** Ebenen (`x=12.5`, schräg), Gitter (`--grid 2x2x3`), Druckraum (`--max 220x220x250`), Keile um eine Achse (`--wedges 8`) und eine Zuordnungskarte (ein Wert pro Dreieck, z. B. aus einer KI-Segmentierung).
48
+ - **Sauber geschnitten:** Neue Eckpunkte entstehen genau **einmal pro Kante** und werden von beiden Seiten geteilt: keine Spalten, keine T-Kreuzungen. Jeder Schnitt bekommt einen Deckel (auch mit Löchern und Inseln).
49
+ - **KI als Zulieferer, Beweis bleibt:** `meshcut segment` findet Teile (eingebaut, lokales Modell oder gehosteter Dienst) und benennt sie auf Wunsch (`--names Kopf,Arme,Beine` oder `--prompt "trenne Kopf, Arme, Beine"`). Egal woher die Karte kommt: sie läuft durch denselben Weg, `join` und `verify` bleiben exakt.
50
+ - **Ein Satz genügt:** `regions` nummeriert die Elemente eines Modells, `remove` und `swap` entfernen oder ersetzen eines (Loch zu, Material, UV und Normalen bleiben), und eine Prüfzeile sagt, was sich geändert hat und dass der Rest identisch ist. Kein Blender, keine Parameter.
51
+ - **Für Agenten gebaut:** MCP-Server (`meshcut serve --mcp`) und HTTP-API (`meshcut serve --http 8765`), beide nur in einem Wurzelordner.
52
+ - **Läuft überall:** Windows, Mac, Linux; nur numpy als Abhängigkeit; und [im Browser](https://calyiex.github.io/meshcut/) (auch iPhone), ohne Upload.
53
+
54
+ Gebaut von K&K AI als Schwesterwerkzeug von [pixelcut](https://github.com/CalyieX/pixelcut) (dort Bilder, hier Netze).
55
+
56
+ ---
57
+
58
+ ## Leitidee
59
+
60
+ meshcut ist ein KI-Werkzeug mit Harness, kein Modellierprogramm zum Selberklicken. Niemand soll in Blender-Manier stundenlang Löcher flicken, Normalen glätten und Materialien neu zuweisen: Der Assistent nennt das Ziel, meshcut misst am Modell, entscheidet selbst und liefert ein Ergebnis, bei dem man keinen Unterschied zum Original sieht (Schattierung, UV und Materialien bleiben). Jede neue Funktion folgt dem: ein Befehl pro Aufgabe, gute Voreinstellungen statt Parameterlisten, eine Prüfzeile zum Schluss.
61
+
62
+ ## Warum meshcut? Drei Alleinstellungsmerkmale
63
+
64
+ Stand der Recherche: 10.11.2026. Die Cloud-Dienste (Meshy Auto Split, Tripo) verändern oder erfinden Geometrie (Verstärkung, „Part Completion“) und verlangen ein Bezahlkonto; KI-Modelle (PartField, SAMesh, P3-SAM) liefern nur Labels ohne Schnitt; Slicer-Werkzeuge (PrusaSlicer, Bambu Studio) und Blender schneiden von Hand und beweisen nichts.
65
+
66
+ 1. **Exakter Schnitt mit Beweis.** Neue Eckpunkte genau einmal pro Kante, ein wasserdichter Deckel je Schnitt, das Original-Netz bleibt außerhalb des Schnitts unverändert. Die Teile sind einzeln geschlossen, und `verify` weist es nach (wasserdicht, Euler, Volumen, Fläche, Deckel auf den Ebenen).
67
+ 2. **Rundlauf bitgenau.** `join` stellt die *ursprünglichen Dreiecke* wieder her; ein SHA-256 über die Dreiecksmenge, ein zweiter über ihre Reihenfolge und ein Hash je Teil belegen es. Bricht das Schreiben mittendrin ab (Fehler, `kill -9`, Stromausfall), bleibt der Ordner entweder ganz alt oder ganz neu; Dateien werden vor dem Umbenennen mit `fsync` gesichert (die Ordnereinträge nur unter Linux/macOS, unter Windows verlässt sich meshcut auf NTFS).
68
+ 3. **Die Zuordnungskarte als offene Schnittstelle.** Jedes Verfahren, das jedem Dreieck eine Teilnummer gibt, kann meshcut füttern: eingebaut, als Befehl für ein lokales Modell, als gehosteter Dienst. Danach ist es dasselbe wie ein Schnitt: exakt zusammensetzbar und nachprüfbar. So bleibt die KI austauschbar, der Beweis bleibt.
69
+
70
+ ## Installation
71
+
72
+ ```bash
73
+ pip install kk-meshcut # Befehl: meshcut, Python-Modul: kkmeshcut
74
+ ```
75
+
76
+ (Der Name `meshcut` auf PyPI gehört einem fremden Projekt, deshalb `kk-meshcut`. Der Befehl heißt trotzdem `meshcut`.)
77
+
78
+ ## Schnellstart
79
+
80
+ ```bash
81
+ # Ein Torus, an zwei Ebenen in vier Teile zerlegt, danach wieder zusammengesetzt
82
+ meshcut split examples/torus.stl teile --plane x=0 --plane z=0 --verify
83
+ meshcut join teile zurueck.obj
84
+ ```
85
+
86
+ `--verify` liest die *gespeicherten* Dateien neu ein und meldet:
87
+
88
+ ```
89
+ OK hash zusammengesetzt 9e2b374f3c40... = Hash der Quelle (float32)
90
+ OK wasserdicht jedes Teil wasserdicht
91
+ OK euler Euler-Zahl je Teil gerade
92
+ OK volumen Summe der Teile 19069.6383337, Original 19069.6383337
93
+ OK flaeche Flaeche ohne Deckel 5501.38007, Original 5501.38007
94
+ OK quelle Quelldatei 9e2b374f3c40... = Hash in der Begleitdatei
95
+ OK hausdorff Hausdorff (Eckpunkte, ohne Begleitdatei zusammengesetzt) 0, erlaubt 0.000103
96
+ ```
97
+
98
+ ## Befehle
99
+
100
+ | Befehl | Was er tut |
101
+ |---|---|
102
+ | `meshcut split EIN AUSORDNER ...` | zerlegt ein Netz, schreibt die Teile und `meshcut.json` |
103
+ | `meshcut join ORDNER AUS.stl` | setzt die Teile eines Ordners bitgenau wieder zusammen (mit `meshcut.json`) |
104
+ | `meshcut join teil1.stl teil2.stl AUS.stl` | ohne Begleitdatei: Näherung (Deckelpaare weg, Dreiecke bleiben fein) |
105
+ | `meshcut verify ORDNER [--source ORIGINAL]` | prüft den Rundlauf der gespeicherten Dateien |
106
+ | `meshcut segment EIN AUSORDNER [--parts N] [--names a,b,c] [--prompt "…"] [--backend …]` | findet Teile automatisch (und benennt sie), schreibt sie als Zuordnungskarte, prüft den Rundlauf |
107
+ | `meshcut regions EIN AUSORDNER` | nummeriert die Elemente (Teile, Objekte, Gruppen, Materialien): `regions.png` mit Nummern, `regions.json` mit Punkt, Rahmen, Fläche, Material |
108
+ | `meshcut remove EIN --region N` | entfernt ein Element, schließt das Loch sauber (Material, UV, Normalen der Umgebung), schreibt `EIN_edit.obj` |
109
+ | `meshcut swap EIN --region N [--shape box\|sphere\|cylinder]` | ersetzt ein Element durch einen Grundkörper gleicher Größe, mit dem Material des Originals |
110
+ | `meshcut tools` | alle Befehle als Tool-Definition (JSON-Schema) für KI-Assistenten, aus dem Parser erzeugt |
111
+ | `meshcut serve --root ORDNER --mcp` oder `--http PORT` | MCP-Server (stdio) bzw. HTTP-API für Agenten |
112
+ | `meshcut info DATEI` | Eckpunkte, Dreiecke, Volumen, Fläche, wasserdicht, Euler-Zahl, Hash |
113
+ | `meshcut labels DATEI KARTE.npy --grid 2x2x2` | schreibt eine Zuordnungskarte (Teilnummer pro Dreieck) für ein Gitter |
114
+
115
+ ### Arten zu zerlegen (`split`)
116
+
117
+ ```bash
118
+ meshcut split m.stl out --plane x=12.5 # eine Ebene (x, y oder z = Wert)
119
+ meshcut split m.stl out --plane x=0 --plane 1,1,0,4 # mehrere, auch schräg: a,b,c,d = a*x+b*y+c*z = d (negativ: --plane=-1,0,0,5)
120
+ meshcut split m.stl out --grid 2x2x3 # Gitter über den Begrenzungsquader, Teilnummer = Zelle
121
+ meshcut split m.stl out --max 220x220x250 # so viele gleichmäßige Schnitte, dass jedes Teil in den Druckraum passt
122
+ meshcut split m.stl out --wedges 8 --axis z # 8 Keile um die z-Achse (gerade Zahl; --center 10,5 verschiebt die Achse)
123
+ meshcut split m.stl out --labels karte.npy # Zuordnungsmodus: Geometrie bleibt unverändert
124
+ ```
125
+
126
+ Weitere Optionen: `--format stl|obj|ply|3mf|glb` (3MF und GLB legen alle Teile in **eine** Datei), `--no-cap` (ohne Deckel, für offene Netze), `--flip` (Dreiecke umdrehen, wenn das Netz nach innen orientiert ist), `--snap` (siehe unten), `--verify`.
127
+
128
+ **Zuordnungskarte:** eine Datei (`.npy`, `.json` oder `.csv`) mit **einer ganzen Zahl pro Dreieck** (Teilnummer, Lücken erlaubt, höchstens 1024 Teile). So lassen sich Ergebnisse einer Netz-Segmentierung (z. B. PartField, SAMesh, P3-SAM) verwenden: einfach ihre Dreiecks-Labels als `.npy` speichern. meshcut zeichnet selbst nur Gitter-Karten (`meshcut labels`).
129
+
130
+ ## KI: Teile finden und benennen (`segment`)
131
+
132
+ ```bash
133
+ meshcut segment figur.stl teile --parts 3 # eingebaut: räumliche Gruppen (k-Means), ohne Modell und ohne Netz
134
+ meshcut segment figur.stl teile --names Kopf,Rumpf,Beine --format 3mf # Anzahl und Namen; Namen werden Objektnamen in 3MF/GLB
135
+ meshcut segment szene.glb teile --backend components # eigenständige Hüllen (Gehäuse, lose Teile)
136
+ meshcut segment figur.stl teile --prompt "trenne Kopf, Arme, Beine" # Sprachmodell holt die Namen aus dem Satz
137
+ ```
138
+
139
+ Das Ergebnis ist **immer eine Zuordnungskarte** (ein Wert pro Dreieck). Teil 0 ist das höchste Teil (z), dann abwärts, damit Namen stabil bleiben. Die Namen stehen in `meshcut.json` (`names`) und werden beim Einlesen streng geprüft (Buchstaben, Ziffern, Leerzeichen, `- . _`, höchstens 64 Zeichen, eindeutig).
140
+
141
+ | Verfahren (`--backend`) | Quelle | Einrichtung |
142
+ |---|---|---|
143
+ | `kmeans` (Vorgabe), `components` | eingebaut, deterministisch | keine |
144
+ | `command` | lokales Modell als Befehl (PartField, SAMesh, eigenes Skript) | `MESHCUT_SEGMENTER_CMD='python mein_modell.py {input} {output} {parts}'` |
145
+ | `http` | gehosteter Dienst, der ein GLB annimmt und `{"labels": [...]}` zurückgibt | `MESHCUT_SEGMENT_URL`, `MESHCUT_SEGMENT_KEY` |
146
+
147
+ Sprachmodell zum Benennen (`--prompt`): `ANTHROPIC_API_KEY` (Modell über `MESHCUT_LLM_MODEL`, Vorgabe `claude-sonnet-5-5`) **oder** ein OpenAI-kompatibler Endpunkt mit `MESHCUT_LLM_URL`, `MESHCUT_LLM_MODEL`, `MESHCUT_LLM_KEY`. Ist `MESHCUT_LLM_URL` gesetzt, gewinnt der Endpunkt; der Anthropic-Schlüssel geht nur an `api.anthropic.com`. Das Modell bekommt nur Namen und Kennzahlen der Teile (Lage, Größe), kein Netz; die Antwort wird geprüft (jeder Name genau einmal, nur bekannte Teile).
148
+
149
+ **Sicherheit.** Schlüssel kommen nur aus der Umgebung, nie aus Dateien oder Argumenten, und stehen weder in Ausgaben noch in `meshcut.json`. Entfernte Adressen müssen `https` sein (`http` nur für localhost), Weiterleitungen werden nicht befolgt, und was ein eigener Befehl auf stderr schreibt, reicht meshcut nicht weiter. Netzzugriff gibt es nur, wenn Sie ihn einrichten (`http`-Segmentierer, `--prompt`); `--prompt` mit `ANTHROPIC_API_KEY` ruft `api.anthropic.com` auf (oder den https-Endpunkt aus `MESHCUT_ANTHROPIC_URL`, falls Sie ihn setzen; der Schlüssel geht dann dorthin).
150
+
151
+ **Lizenzen der bekannten Modelle (Stand 10.11.2026, vor dem Einsatz selbst prüfen):** PartField (NVIDIA) nur nicht-kommerziell; P3-SAM/Hunyuan3D-Part (Tencent) gilt laut Lizenz nicht in EU, UK und Südkorea; SAMesh hat keine Lizenzdatei; PartCrafter (MIT) erzeugt Teile aus einem Bild, zerlegt aber kein vorhandenes Netz. meshcut bringt keines davon mit, der Adapter ruft nur an, was Sie selbst eingerichtet haben.
152
+
153
+ ## Mit KI-Assistenten bedienen
154
+
155
+ meshcut ist dafür gebaut, dass ein KI-Assistent (Claude, ChatGPT, Codex und andere) es steuert: ein Befehl pro Aufgabe, klare Fehlerzeilen, Ergebnisse als Dateien. Sag zum Beispiel:
156
+
157
+ > „Nimm die Antenne vom Roboter ab und schließ die Stelle sauber.“
158
+ > „Ersetze den Knauf durch eine Kugel in derselben Größe, mit demselben Material.“
159
+ > „Teil das Modell so, dass es auf mein Druckbett 220 × 220 passt, und prüf, dass nichts fehlt.“
160
+
161
+ Der Assistent wählt den Befehl (`regions` + `remove`, `regions` + `swap`, `split --max` + `verify`), meshcut führt ihn exakt aus. meshcut selbst versteht keine Sätze, es ist die verlässliche Ausführung dahinter. Das Modellieren von Hand entfällt: der Assistent sagt, was er will, meshcut erledigt Auswahl, Lochschluss, Material, UV und Normalen selbst.
162
+
163
+ Das Werkzeug für Assistenten (Harness):
164
+
165
+ - `meshcut regions modell.obj ordner` nummeriert die erkennbaren Elemente: zusammenhängende Teile, Objekte, Gruppen und Materialien (`regions.png` mit Nummern im Bild, `regions.json` mit Punkt, Rahmen, Fläche, Volumen und Material). Der Assistent schaut das Bild an und nennt die Nummer, ohne Koordinaten zu raten; alternativ wählt `--at x,y,z` das kleinste Element an einem Punkt (bei gleich großen gewinnt die kleinere Nummer) und `--name` ein Material, Objekt oder eine Gruppe (auch wenn das Element in der Liste als „Teil N“ steht; passt ein Name auf mehrere Elemente, bricht meshcut ab). Das Bild zeigt eine Ansicht: verdeckte Elemente haben keine Nummer im Bild (`visible: false` in `regions.json`), sie sind trotzdem über Nummer, `--at` oder `--name` wählbar. Mehr als 500 Elemente werden nicht nummeriert; dann wählt `--at` unter den nummerierten das kleinste.
166
+ - `meshcut tools` gibt alle Befehle als Tool-Definition (JSON-Schema) aus, die jeder Agent so registrieren kann. Sie wird aus dem Parser erzeugt und bleibt damit immer aktuell. Der MCP-Server und die HTTP-API bieten `regions`, `remove` und `swap` ebenfalls an.
167
+ - `remove` und `swap` messen am Modell selbst: Das Loch wird mit einem Ohrenschnitt in der Randebene geschlossen (ohne neue Punkte, jedes Dreieck mit eigener Normale). Folgt die Umgebung einer Wölbung (Kugel, Zylinder, Schale), legt meshcut einen Paraboloid an Rand und ersten Nachbarring und füllt mit Zwischenringen auf dieser Fläche; das greift nur bei einem sternförmigen Rand und einer Wölbung ab 1 % des Lochdurchmessers, eine ebene Fläche bleibt exakt eben. Material und UV-Werte kommen von der Umgebung (die UV der Zwischenringe aus der Lage, am Rand gefittet), die Glättung des Ersatzes kommt aus der Form. Ein Rand, der weder ebene Triangulation noch einen Fächer erlaubt, wird abgewiesen. Ändert sich das Volumen eines einzelnen geschlossenen Körpers um mehr als 2 %, nennt der Bericht die Zahl. Folgt der Rand einer Kugel (Kappen bis zur Halbkugel), wird die Füllung eine Kugelkappe; sonst gilt ein Paraboloid, und ragt dessen Wölbung über 15 % des Lochdurchmessers, bleibt die Füllung flach, statt eine Spitze ins Leere zu setzen. Ein Loch mit nicht ebenem, aber triangulierbarem Rand (etwa ein Fenster von 180° in einem Rohr) wird flach gefüllt und meshcut sagt das ausdrücklich dazu (`Hinweis`); auch bei `swap` ohne `--shape` meldet es, wenn keine Form gut passt (Abweichung über 0,15 der Diagonale). Liegt das Loch auf einer UV-Naht, bekommen die neuen Ecken fortlaufende UV-Werte (z. B. 1,02 statt 0,02), die Textur muss dafür wiederholen. Der Ersatz hat die Größe des Originals mal `--scale` (0,01 bis 100); ohne Material im Original bleibt er ohne Material (`usemtl off`). Der Assistent muss keine Parameter mitliefern (`--shape`, `--axis`, `--scale`, `--material` sind nur Feinschliff).
168
+ - Bei `swap` ohne `--shape` rechnet meshcut alle Kandidaten (Quader, Kugel, Zylinder je Achse), misst bei jedem den Abstand zum Original in beide Richtungen und nimmt den besten; die Zeile „Kandidaten verglichen“ zeigt die Werte. Beim Lochschluss wird ein Ohrenschnitt mit Splittern gegen einen Fächer vom Mittelpunkt abgewogen.
169
+ - Der Messprüfstand `bench/edit_bench.py` baut Netze mit bekannter Wahrheit (Platte und Kugel mit Höcker, rechteckig und C-förmig, freie Teile zum Ersetzen), entfernt/ersetzt und misst Außenbereich, offene Kanten, Abweichung, Fläche, Normalen, UV, Windung, Dreiecksgüte und Doppellauf, in fünf Maßstäben von 1e-9 bis 1e9. Die Schwellen stehen im Kopf der Datei und wurden vor dem Messen festgelegt; eine nachträgliche Lockerung ist dort ausgewiesen.
170
+ - Am Ende steht eine Prüfzeile: „von 24 Dreiecken 2 entfernt, 2 neu dazugekommen; die übrigen 22 sind unverändert (Eckpunkt, UV, Normale, Material verglichen)“. Meshcut liest dafür die geschriebene Datei zurück, vergleicht jede unberührte Fläche und prüft bei den neuen Flächen Material, Zahl und endliche Koordinaten; die Zahlen in der Zeile stammen aus dieser Datei. Stimmt etwas nicht, bricht es ab und entfernt die Ausgabe. Die Prüfung belegt nicht, dass das Ergebnis schön aussieht; die Deckel sind einfache Dreiecke, kein Remeshing. Bearbeitet werden höchstens 500 000 Flächen (größere Netze vorher mit `split` teilen).
171
+
172
+ OBJ wird vollständig mitgeführt (Material, UV, Normalen, Objekt- und Gruppennamen, Glättungsgruppen, `mtllib` wird mitkopiert). STL, PLY, 3MF und GLB werden hier nur mit Geometrie geschrieben (Farben, Materialien, UV gehen verloren); dort prüft meshcut Dreieckszahl und Koordinaten, und die Prüfzeile sagt es. Die Eingabedatei wird nie überschrieben.
173
+
174
+ ## Für Agenten: MCP und HTTP
175
+
176
+ ```bash
177
+ meshcut serve --root ./arbeit --mcp # MCP über stdin/stdout (Claude, Codex u. a.)
178
+ MESHCUT_TOKEN=geheim meshcut serve --root ./arbeit --http 8765
179
+ ```
180
+
181
+ Werkzeuge: `info`, `split`, `segment`, `join`, `verify`, `regions`, `remove`, `swap` (Schema über `tools/list` bzw. `GET /v1/tools`). Dateien werden nur unterhalb von `--root` gelesen und geschrieben, auch nicht über Links oder `..`. Die HTTP-API bindet an `127.0.0.1`; ohne `MESHCUT_TOKEN` nimmt sie nur Anfragen mit `Host: localhost` und `Content-Type: application/json` an (Schutz vor Angriffen aus dem Browser). Eine andere Adresse (`--host`) geht nur mit Schlüssel (Bearer).
182
+
183
+ ```bash
184
+ curl -s -H "Authorization: Bearer geheim" -H "Content-Type: application/json" \
185
+ -d '{"input":"figur.stl","outdir":"teile","parts":3}' http://127.0.0.1:8765/v1/segment
186
+ ```
187
+
188
+ ## Was genau garantiert wird
189
+
190
+ Zwei Stufen, die man nicht vermischen darf:
191
+
192
+ **Zuordnungsmodus.** Die Eckpunkte und Dreiecke bleiben unverändert, es werden nur Dreiecke auf Teile verteilt. Setzt man die Teile wieder zusammen, kommt dieselbe Dreiecksmenge heraus: gleicher SHA-256, **bitgenau**.
193
+
194
+ **Schnittmodus.** Dreiecke werden an Ebenen zerlegt. Der Rundlauf ist trotzdem exakt, weil meshcut in `meshcut.json` für jedes Teildreieck die Nummer seines Quelldreiecks und für jedes zerschnittene Dreieck dessen Original-Koordinaten (64 Bit) speichert. `join` entfernt die Deckel und setzt die Original-Dreiecke wieder ein; der Hash stimmt mit dem der Quelle überein. Ohne Begleitdatei bleibt die Geometrie gleich (Hausdorff-Abstand ~ Rundungsfehler), nur die Dreiecke bleiben so fein, wie der Schnitt sie gemacht hat.
195
+
196
+ **Dateiformat und Genauigkeit.** STL und GLB speichern 32 Bit: der Hash wird dann nach Rundung auf float32 gebildet (steht in `meshcut.json` als `precision`). Wer **wirklich 64 Bit** will, nimmt `--format obj` oder `3mf` (Text mit 17 Stellen, ohne Verlust).
197
+
198
+ **Rundlauf-Kriterien des Schnittmodus** (alle in `verify`):
199
+ - **Teile unverändert:** jede Teildatei hat denselben Hash wie beim Schreiben (Fragmente und Deckel eingeschlossen). Verschobene, beschädigte oder ausgetauschte Teile fallen sofort auf, auch ohne `--source`.
200
+ - **Deckel auf den Schnittebenen:** jedes Deckel-Dreieck liegt mit allen drei Ecken auf einer der in `meshcut.json` gespeicherten Ebenen. Ein Schnitt an der falschen Stelle fällt auf.
201
+ - Volumen aller Teile = Volumen des Originals, Fläche ohne Deckel = Originalfläche, jedes Teil wasserdicht (jede Kante genau zweimal, gegenläufig), Euler-Zahl gerade, Hash gleich.
202
+ - Mit `--source`: Hash der Quelldatei und Hausdorff-Abstand der ohne Begleitdatei zusammengesetzten Teile. Bei großen Netzen prüft der Hausdorff-Abstand eine **Stichprobe** der Eckpunkte (steht dann im Text); die Sicherheit kommt aus den Hashes, der Hausdorff-Abstand ist eine zusätzliche, unabhängige Gegenprobe.
203
+
204
+ Erlaubt sind 1e-9 relativ bei 64 Bit und 1e-4 bei 32 Bit; bei STL/GLB weit vom Ursprung kommt die float32-Rundung der Koordinaten dazu.
205
+
206
+ **Einheiten.** 3MF-Dateien werden beim Einlesen nach Millimeter umgerechnet (`inch`, `centimeter`, `meter`, `micron`, `foot`); meshcut schreibt 3MF immer in Millimeter. Die Größe in der Welt bleibt gleich, nur die Zahlen ändern sich.
207
+
208
+ **Abbruch beim Schreiben.** `split` ersetzt einen Ausgabeordner als Ganzes: Fehler und Ausnahmen rollen zurück, und auch nach einem harten Abbruch (Stromausfall, `kill -9`) legt ein Journal im versteckten `.meshcut_…`-Ordner fest, was passiert: Der nächste Aufruf von `split` auf diesen Ordner stellt den alten Satz wieder her (oder schließt ein fertiges Ersetzen ab) und meldet das auf stderr. `join` und `verify` räumen nur eigene Reste (Marker `.meshcut-staging` oder Journal, keine Links) auf, die älter als zehn Minuten sind, damit sie einen gerade laufenden `split` in einem anderen Prozess nicht stören. Zwei `split` gleichzeitig in denselben Ordner sind nicht vorgesehen (innerhalb des Dienstes sorgt eine Sperre dafür, dass immer nur ein Werkzeug läuft).
209
+
210
+ ### Wie geschnitten wird
211
+
212
+ 1. Jeder Eckpunkt bekommt ein Vorzeichen zur Ebene (davor / dahinter / auf der Ebene). Weil das Vorzeichen pro Eckpunkt feststeht, entscheiden beide Dreiecke an einer Kante gleich.
213
+ 2. Je Kante, die die Ebene kreuzt, entsteht **genau ein** neuer Eckpunkt (Endpunkte sortiert, `p = a + t·(b−a)`, `t = da/(da−db)`), beide Seiten verweisen darauf.
214
+ 3. Der Rand jedes Teils liegt danach in der Ebene. Daraus entstehen geschlossene Umrisse; Außenumrisse und Löcher werden erkannt, Löcher über Brückenkanten angebunden, die Fläche mit Ohrenschnitt trianguliert. Alle Randpunkte bleiben erhalten, deshalb schließt der Deckel ohne Spalt.
215
+ 4. Der Deckel des einen Teils ist das gespiegelte Gegenstück des anderen. Bei mehreren Ebenen werden auch Deckel weiter zerschnitten und bleiben dabei Paare.
216
+ 5. **Dreiecke, die in der Ebene liegen**, gehören zu der Seite, hinter der das Material liegt. Flächenlose Dreiecke in der Ebene gehen auf die Seite ihrer Nachbarn.
217
+ 6. `--snap` (Standard 1e-12): Eckpunkte, die nur um Rundungsrauschen neben der Ebene liegen (z. B. `cos(90°)` bei einer Kugel), gelten als *auf* der Ebene. Das verschiebt keinen Eckpunkt, es vermeidet nur Haarrisse-Dreiecke. `--snap 0` nimmt das exakte Vorzeichen.
218
+
219
+ ## Python
220
+
221
+ ```python
222
+ import kkmeshcut as mc
223
+
224
+ side = mc.split("examples/torus.stl", "teile", plane=["x=0", "z=0"], verify=True) # dict aus meshcut.json
225
+ mc.join("teile", "zurueck.obj")
226
+ r = mc.verify("teile", source="examples/torus.stl") # {'ok': True, 'checks': [...], ...}
227
+ print(mc.info("examples/torus.stl")["volume"])
228
+
229
+ mc.regions("figur.obj", "nummern") # nummern/regions.png + regions.json
230
+ r = mc.swap("figur.obj", region=3, shape="sphere") # {'output': 'figur_edit.obj', 'text': '... Pruefung: ...'}
231
+ mc.remove("figur.obj", name="Antenne", out="ohne.obj")
232
+ ```
233
+
234
+ Die Schnittstelle führt dieselben Befehle aus wie die Kommandozeile (gleiche Optionen mit Unterstrich: `no_cap=True`), schweigt auf stdout und stderr und wirft `mc.MeshcutError` statt das Programm zu beenden. Tiefer unten liegen `Mesh`, `split_planes`, `split_labels`, `triangle_hash`, `mesh_stats` für eigene Abläufe mit numpy-Arrays.
235
+
236
+ ## Im Browser
237
+
238
+ **[calyiex.github.io/meshcut](https://calyiex.github.io/meshcut/)** – derselbe Kern läuft in Pyodide/WebAssembly, nichts wird hochgeladen. Datei wählen, Schnitt einstellen, Teile als ZIP speichern; zum Zusammensetzen alle Teile samt `meshcut.json` wieder auswählen. Bis 40 MB je Datei. Bei jedem Commit prüft das CI die Seite in WebKit (Safari/iPhone-Engine), Chromium und Firefox: Zerlegen und Zusammensetzen im Browser müssen den Hash der Quelle ergeben.
239
+
240
+ ## Grenzen (ehrlich)
241
+
242
+ - **`split`, `join`, `segment` behandeln nur Geometrie.** UV-Koordinaten, Farben, Normalen und Materialien werden dort nicht übernommen; Texturen und Vertexfarben bleiben also nicht erhalten. (`regions`, `remove` und `swap` führen sie in OBJ mit, siehe unten.) Eckpunkte mit gleichen Koordinaten werden beim Einlesen verschmolzen (GLB-Nähte, STL-Dreiecksuppe).
243
+ - **Deckel brauchen ein wasserdichtes, nach außen orientiertes Netz.** Sonst bricht `split` mit einer klaren Meldung ab (`--no-cap` schneidet trotzdem, `--flip` dreht die Orientierung).
244
+ - **Keile nur in gerader Zahl.** Ungerade Keilzahlen bräuchten Halbebenen.
245
+ - **Stifte und Passungen** (Dübel, Zapfen/Loch mit Spiel) gibt es in v0.1 noch nicht, ebenso keine Bearbeitung mehrerer Objekte einer Datei auf einmal (3MF/GLB mit mehreren Objekten werden als ein Netz gelesen). manifold3d wird nur in den Tests als unabhängige Gegenprobe benutzt (Volumen der Teile gegen `split_by_plane`), nicht zur Laufzeit.
246
+ - **Triangulierung der Deckel** ist gültig und deckungsgleich, aber nicht „schön“: Ohrenschnitt erzeugt gern lange schmale Dreiecke. Für den Druck unkritisch, für Simulation ungeeignet. Läuft der Ohrenschnitt in einen Notfall (Punkte exakt aufeinander), meldet `split` das.
247
+ - **Bearbeiten (`remove`/`swap`) – bekannte Lücken:** Texturen in Unterordnern werden bei `--out` in einen anderen Ordner nicht mitkopiert (nur die `.mtl`); OBJ-Eingaben in UTF-16 oder mit Zeilenfortsetzung `\` werden abgelehnt; Vertexfarben (`v x y z r g b`) bekommen für neue Eckpunkte keine Farbe; eine Füllung, die weder einer Kugel noch einem flachen Paraboloid folgt (z. B. eine hohe Spitze), bleibt flach und verkleinert das Volumen ohne eigenen Hinweis; sehr große Netze (100 000+ Dreiecke) brauchen Sekunden, weil die Bearbeitung Python-Schleifen nutzt; Koordinaten jenseits von etwa 1e76 bricht `remove` mit einer Meldung zum Zahlenbereich ab.
248
+ - **Form der Füllung ist eine Näherung.** Auf einer echten Kugel mit glattem Rand folgt sie der Kugel (Kappen bis zur Halbkugel; bei zackigem Rand, etwa einer Auswahl per Schwerpunkt, fällt sie auf eine flache Füllung zurück und der Bericht sagt das, Beispiel −17 % bei 65°); sonst gilt ein Paraboloid durch Rand und ersten Ring, der Ellipsoide bis rund 9 % Volumen überschießen kann und bis 0,14 der Kugelgröße neben der Fläche liegen darf. Eine Halbkugel-Kappe liegt zwar auf der Kugel, verliert aber durch die feste Dichte (unten) rund 6 % Volumen. Bei mehr als 2 % Volumenänderung nennt der Bericht die Zahl; darunter schweigt er. Der Hinweis rechnet mit dem Betrag des Volumens und gilt nur für einen einzelnen geschlossenen Körper; bei Koordinaten jenseits von etwa 1e100 oder unter 1e-100 fehlt er. Die Füllung hat eine feste Dichte (rund 240 Dreiecke), bei sehr großen Kappen wird sie grob. Zufällig gezackte Ränder werden oft abgelehnt (Selbstprüfung, „zu verwickelt“), nicht falsch gefüllt; auf der Testmatrix mit Ellipsoiden und Kugeln waren es rund 40 %. `swap` ersetzt ein Element durch den besten Grundkörper und meldet erst ab einer Abweichung von 0,15 der Diagonale, dass er nur grob passt.
249
+ - **Geschwindigkeit.** Der Kern ist numpy; die Deckel-Triangulierung ist Python. Gemessen: `split` mit einer Ebene auf rund 100 000 Dreiecken etwa 5 Sekunden (mit Schreiben und Prüfungen), ein Gitter 3×3×3 etwa 18 Sekunden; Deckel mit mehreren tausend Randpunkten brauchen Sekunden. `remove` braucht auf 100 000 Dreiecken rund 10 Sekunden.
250
+ - **Ebene durch einen konkaven Eckpunkt oder eine Kante des Netzes:** berühren sich die Teile danach an einer Kante, ist ein Teil nicht wasserdicht. `split` meldet das („Teil … ist nicht wasserdicht“), `verify` ebenfalls.
251
+ - **Zielformat mit 32 Bit (STL, GLB):** liegt eine Ebene weniger als etwa 5e-7 der Netzgröße neben einem Eckpunktring, würden Eckpunkte des Deckels beim Runden mit denen des Netzes zusammenfallen. `split` erkennt das (Test auf den gerundeten Teilen) und zählt solche Eckpunkte dann als auf der Ebene; liegt das Netz weit vom Ursprung (gröbere 32-Bit-Schritte), wächst die Schwelle mit dem Abstand; hilft das nicht (auch bei eigenem `--snap`), verweigert `split` und schreibt nichts Kaputtes. Sind die 32-Bit-Schritte grob im Verhältnis zur Netzgröße (über 1e-4), nennt `split` das in einem Hinweis; Schnittflächen und Summen weichen dann messbar ab. Die Hinweise stehen auch in der Rückgabe von `meshcut.split()` und `warnings` im Dienst (nicht in `meshcut.json`); `verify` erlaubt für Volumen und Fläche dann den Rundungsfehler der Quelle. Mit eigenem `--snap` gilt Ihr Wert unverändert und `--verify` zeigt dann, ob die Dateien halten.
252
+ - **Eine Ebene mit negativer erster Zahl** (`--plane -0.55,-0.43,0.72,4.1`) liest argparse als Option; mit `--plane=-0.55,-0.43,0.72,4.1` geht es.
253
+ - **Weit vom Ursprung:** bei einem Netz, das um mehr als etwa das 1e5-fache seiner Größe vom Ursprung entfernt liegt, scheitern in `verify` Volumen und Fläche (und bei noch größerem Abstand die Wasserdichtheit) auch bei Formaten mit 64 Bit; die Rechnung verliert dort Stellen. `verify` meldet das laut, es bleibt kein stiller Fehler. Das Netz vorher zum Ursprung verschieben.
254
+ - **Die Reihenfolge der Dreiecke in einer Teildatei gehört zum Beweis.** Die Deckel stehen am Ende der Datei; schreibt ein anderes Programm (Slicer, Mesh-Editor) eine Teildatei mit denselben Dreiecken in anderer Reihenfolge neu, schlagen `ebenen`, `hash`, `reihenfolge` und `flaeche` an, obwohl die Geometrie gleich ist. Dann `join` ohne Ordner (aus den Dateien, Näherung) oder die Teile unverändert lassen.
255
+ - **`--flip` und der Rundlauf-Beweis.** `--flip` dreht die Dreiecke vor dem Teilen; `meshcut.json` und `join` gelten für das gedrehte Netz. Ein `verify --source` gegen die ursprüngliche Datei zeigt darum Abweichungen bei Quelle und Reihenfolge. `split` sagt das beim Start.
256
+ - **3MF mit 64 Bit.** meshcut schreibt 3MF mit float64 (Hash bitgenau); manche Slicer lesen 3MF als float32, dann gilt der bitgenaue Rundlauf nur für meshcut selbst.
257
+ - **32-Bit-Dateien und Topologie.** Bei STL/GLB können nahe beieinanderliegende Schnittpunkte beim Runden auf float32 zusammenfallen; dann meldet `verify` eventuell `wasserdicht`, obwohl der 64-Bit-Satz in Ordnung wäre. Wer das nicht will, nimmt `--format obj`, `ply` oder `3mf`.
258
+ - **Die Begleitdatei ist keine Signatur.** Die Hashes in `meshcut.json` belegen, dass nichts zufällig oder unbemerkt verloren ging oder vertauscht wurde. Wer die Teile *und* `meshcut.json` absichtlich zusammen umschreibt und alle Zahlen neu rechnet, erzeugt einen in sich stimmigen Satz, den `verify` ohne Quelle nicht von einem echten unterscheidet. Für Echtheit gegenüber Dritten: `verify --source ORIGINAL` mit der Originaldatei oder den Hash der Quelle (`source_hash`) getrennt aufbewahren.
259
+ - **Dienst: ein Werkzeug zur Zeit.** Ein Aufruf über MCP/HTTP hält die Sperre, bis er fertig ist, und der HTTP-Dienst hat keine Obergrenze für gleichzeitige Verbindungen (er ist für Vertrauenswürdige gedacht, nicht fürs offene Netz); ein eigener Segmentierungsbefehl darf bis zu einer Stunde laufen. Wer den Dienst teilt, schaltet ihn mit `MESHCUT_TOKEN` ab und lässt nur Vertrauenswürdige heran: jeder Aufrufer kann den eingerichteten Befehl oder das Sprachmodell (Kosten) auslösen.
260
+ - **Eingelesene Dateien sind begrenzt** (Schutz vor Dateien, die klein sind und sich beim Auflösen vervielfachen): höchstens 10 Millionen Dreiecke nach dem Auflösen aller Instanzen (GLB-Knoten, 3MF-Komponenten), 100 000 Knoten-/Komponentenbesuche, 128 MiB entpackte 3MF-Modelldatei, 5000 Ecken je Fläche und ein Arbeitsbudget für alle Flächen mit mehr als drei Ecken (Vierecke zählen ebenfalls; konvexe Vierecke gehen einen schnellen Weg, alles andere kostet mehr). Das ist ein Deckel gegen Hänger, kein Speicherschutz: 10 Millionen Dreiecke brauchen mehrere GB Arbeitsspeicher, 3MF-Dateien etwa das 20-fache der XML-Größe. Wer meshcut als Dienst für Fremde betreibt, begrenzt zusätzlich Speicher und Laufzeit des Prozesses selbst.
261
+ - **Sehr große Koordinaten.** Weit vom Ursprung (ab etwa dem 1e8-fachen der Netzgröße) geht in 64 Bit die Auflösung aus; in STL/GLB (32 Bit) schon ab etwa dem 1e5-fachen. Vorher das Netz in die Nähe des Ursprungs verschieben.
262
+ - **Bearbeiten (`remove`, `swap`) ist kein exakter Schnitt.** Es gibt keinen Rundlauf-Beweis wie bei `split`; stattdessen liest meshcut die geschriebene Datei zurück und belegt, dass jede unberührte Fläche (Eckpunkt-, UV-, Normalen- und Materialtext, Reihenfolge) unverändert ist, und prüft, dass keine neue Fläche gegenläufig auf einer vorhandenen liegt (gerichtete Doppelkanten). Das Schließen eines Lochs und der Ersatz sind eine gute, keine perfekte Wahl: ebene und konkave Ränder werden mit einem Ohrenschnitt aus Randpunkten gefüllt (bei konkaven Löchern auf gewölbter Fläche bleibt der Deckel flach: im Prüfstand verliert er dort etwa 8 % Fläche), sternförmige Löcher auf gewölbter Fläche folgen der Wölbung; Inseln im Loch (ein behaltenes Dreieck mitten im Rand) werden nicht erkannt; als Ersatz gibt es Quader, Zylinder und Kugel in der Größe des Originals (keine Nachbildung der Form, keine Textur-Neuberechnung, die UV nehmen den Bereich des Originals). Fehlen dem Modell UV oder Normalen, schreibt meshcut auch keine.
263
+ - **Elemente heißen nach Reihenfolge.** Die Nummern aus `regions` gelten für genau diese Datei in ihrem jetzigen Zustand; nach einer Bearbeitung neu nummerieren. Als Elemente zählen zusammenhängende Teile (über gleiche Eckpunktlage, UV-Nähte trennen nichts), Objekte, Gruppen und Materialien; Elemente, die dieselben Flächen haben wie ein früheres, stehen nicht doppelt da. Linien und Punkte (`l`, `p`) eines OBJ werden nicht übernommen (meshcut sagt es).
264
+ - **Die eingebauten Verfahren sind einfach.** `kmeans` teilt nach Lage, nicht nach Bedeutung; für echte Teilerkennung (Arm, Griff, Rad) braucht es ein Modell über `command` oder `http`. Das ist beabsichtigt: meshcut garantiert, was nach der Karte kommt, nicht die Qualität der Karte.
265
+ - **Höchstens 1024 Teile** (`--grid`, `--max`): wird vor dem Schneiden geprüft.
266
+ - Nichtmanifold-Eckpunkte, an denen sich zwei Teile nur in einem Punkt berühren, sind erlaubt; `verify` zählt sie für die Euler-Zahl getrennt.
267
+
268
+ ## Entwicklung
269
+
270
+ ```bash
271
+ pip install -e ".[check]" # pytest, hypothesis, trimesh, manifold3d (Gegenproben)
272
+ python -m pytest -q tests
273
+ MESHCUT_EXAMPLES=300 python -m pytest -q tests/test_property.py # gründlicher
274
+ ```
275
+
276
+ Die Tests prüfen unter anderem (Befunde aus den Prüfrunden stehen in `tests/test_review.py`, auch der harte Abbruch mit `os._exit`): Zufallsebenen, Ebenen durch Eckpunkte/Kanten/Flächen (hypothesis), Dreiecke in der Ebene, Keile um eine Achse, Torus/Hohlkugel (Löcher und Inseln im Deckel), alle fünf Formate, Absturz-Injektion beim Schreiben, Fremddateien im Ausgabeordner und den Vergleich mit trimesh und manifold3d. Dazu kommt ein Mutationstest (345 absichtlich eingebaute Fehler in Kern, Bearbeitung (133 davon), KI-Schicht und Dienst, jeder wird von den Tests bemerkt; `python tests/mutate.py`) sowie Tests für KI-Adapter (lokale Fake-Dienste), MCP und HTTP-API. Die Browser-Version liegt als Kopie in `docs/kkmeshcut.py`; ein Test stellt sicher, dass beide Dateien gleich sind.
277
+
278
+ Lizenz: MIT, © K&K AI.
@@ -0,0 +1,246 @@
1
+ # K&K meshcut
2
+
3
+ ![license](https://img.shields.io/badge/license-MIT-blue) ![python](https://img.shields.io/badge/python-3.9%2B-informational) ![round trip](https://img.shields.io/badge/Rundlauf-bitgenau-brightgreen) ![tests](https://github.com/CalyieX/meshcut/actions/workflows/ci.yml/badge.svg)
4
+
5
+ [![Unterstützen auf Ko-fi](https://ko-fi.com/img/githubbutton_sm.svg)](https://ko-fi.com/kkwonderland)
6
+
7
+ **3D-Netze zerlegen und wieder zusammensetzen, mit Beweis, dass nichts verloren geht.**
8
+ *Cut 3D meshes into parts and put them back together, with a round-trip proof.*
9
+
10
+ **English in short:** a small command-line tool and Python library that splits triangle meshes (STL, OBJ, PLY, GLB, 3MF) by planes, grids, print-bed size, wedges around an axis, or along a per-triangle label map, caps every cut with a watertight lid, and joins the parts back. With the `meshcut.json` sidecar the join restores the *original triangles* and a SHA-256 over the triangle set proves it (bit-exact in 64-bit formats, after float32 rounding in STL/GLB). `meshcut segment` finds (and names) parts automatically - built-in methods, a local model, or any hosted service behind one adapter - and the result is always a per-triangle label map, so the exact join and the proof still apply. An MCP server and an HTTP API expose the same tools to agents. It also runs in the browser (Pyodide), nothing is uploaded. Everything below is in German.
11
+
12
+ **Auf einen Blick**
13
+
14
+ - **Rundlauf mit Beweis:** `split` → `join` ergibt dieselben Dreiecke (SHA-256 über die Dreiecksmenge), `verify` prüft zusätzlich Volumen, Fläche, wasserdicht und Euler-Zahl.
15
+ - **Viele Arten zu schneiden:** Ebenen (`x=12.5`, schräg), Gitter (`--grid 2x2x3`), Druckraum (`--max 220x220x250`), Keile um eine Achse (`--wedges 8`) und eine Zuordnungskarte (ein Wert pro Dreieck, z. B. aus einer KI-Segmentierung).
16
+ - **Sauber geschnitten:** Neue Eckpunkte entstehen genau **einmal pro Kante** und werden von beiden Seiten geteilt: keine Spalten, keine T-Kreuzungen. Jeder Schnitt bekommt einen Deckel (auch mit Löchern und Inseln).
17
+ - **KI als Zulieferer, Beweis bleibt:** `meshcut segment` findet Teile (eingebaut, lokales Modell oder gehosteter Dienst) und benennt sie auf Wunsch (`--names Kopf,Arme,Beine` oder `--prompt "trenne Kopf, Arme, Beine"`). Egal woher die Karte kommt: sie läuft durch denselben Weg, `join` und `verify` bleiben exakt.
18
+ - **Ein Satz genügt:** `regions` nummeriert die Elemente eines Modells, `remove` und `swap` entfernen oder ersetzen eines (Loch zu, Material, UV und Normalen bleiben), und eine Prüfzeile sagt, was sich geändert hat und dass der Rest identisch ist. Kein Blender, keine Parameter.
19
+ - **Für Agenten gebaut:** MCP-Server (`meshcut serve --mcp`) und HTTP-API (`meshcut serve --http 8765`), beide nur in einem Wurzelordner.
20
+ - **Läuft überall:** Windows, Mac, Linux; nur numpy als Abhängigkeit; und [im Browser](https://calyiex.github.io/meshcut/) (auch iPhone), ohne Upload.
21
+
22
+ Gebaut von K&K AI als Schwesterwerkzeug von [pixelcut](https://github.com/CalyieX/pixelcut) (dort Bilder, hier Netze).
23
+
24
+ ---
25
+
26
+ ## Leitidee
27
+
28
+ meshcut ist ein KI-Werkzeug mit Harness, kein Modellierprogramm zum Selberklicken. Niemand soll in Blender-Manier stundenlang Löcher flicken, Normalen glätten und Materialien neu zuweisen: Der Assistent nennt das Ziel, meshcut misst am Modell, entscheidet selbst und liefert ein Ergebnis, bei dem man keinen Unterschied zum Original sieht (Schattierung, UV und Materialien bleiben). Jede neue Funktion folgt dem: ein Befehl pro Aufgabe, gute Voreinstellungen statt Parameterlisten, eine Prüfzeile zum Schluss.
29
+
30
+ ## Warum meshcut? Drei Alleinstellungsmerkmale
31
+
32
+ Stand der Recherche: 10.11.2026. Die Cloud-Dienste (Meshy Auto Split, Tripo) verändern oder erfinden Geometrie (Verstärkung, „Part Completion“) und verlangen ein Bezahlkonto; KI-Modelle (PartField, SAMesh, P3-SAM) liefern nur Labels ohne Schnitt; Slicer-Werkzeuge (PrusaSlicer, Bambu Studio) und Blender schneiden von Hand und beweisen nichts.
33
+
34
+ 1. **Exakter Schnitt mit Beweis.** Neue Eckpunkte genau einmal pro Kante, ein wasserdichter Deckel je Schnitt, das Original-Netz bleibt außerhalb des Schnitts unverändert. Die Teile sind einzeln geschlossen, und `verify` weist es nach (wasserdicht, Euler, Volumen, Fläche, Deckel auf den Ebenen).
35
+ 2. **Rundlauf bitgenau.** `join` stellt die *ursprünglichen Dreiecke* wieder her; ein SHA-256 über die Dreiecksmenge, ein zweiter über ihre Reihenfolge und ein Hash je Teil belegen es. Bricht das Schreiben mittendrin ab (Fehler, `kill -9`, Stromausfall), bleibt der Ordner entweder ganz alt oder ganz neu; Dateien werden vor dem Umbenennen mit `fsync` gesichert (die Ordnereinträge nur unter Linux/macOS, unter Windows verlässt sich meshcut auf NTFS).
36
+ 3. **Die Zuordnungskarte als offene Schnittstelle.** Jedes Verfahren, das jedem Dreieck eine Teilnummer gibt, kann meshcut füttern: eingebaut, als Befehl für ein lokales Modell, als gehosteter Dienst. Danach ist es dasselbe wie ein Schnitt: exakt zusammensetzbar und nachprüfbar. So bleibt die KI austauschbar, der Beweis bleibt.
37
+
38
+ ## Installation
39
+
40
+ ```bash
41
+ pip install kk-meshcut # Befehl: meshcut, Python-Modul: kkmeshcut
42
+ ```
43
+
44
+ (Der Name `meshcut` auf PyPI gehört einem fremden Projekt, deshalb `kk-meshcut`. Der Befehl heißt trotzdem `meshcut`.)
45
+
46
+ ## Schnellstart
47
+
48
+ ```bash
49
+ # Ein Torus, an zwei Ebenen in vier Teile zerlegt, danach wieder zusammengesetzt
50
+ meshcut split examples/torus.stl teile --plane x=0 --plane z=0 --verify
51
+ meshcut join teile zurueck.obj
52
+ ```
53
+
54
+ `--verify` liest die *gespeicherten* Dateien neu ein und meldet:
55
+
56
+ ```
57
+ OK hash zusammengesetzt 9e2b374f3c40... = Hash der Quelle (float32)
58
+ OK wasserdicht jedes Teil wasserdicht
59
+ OK euler Euler-Zahl je Teil gerade
60
+ OK volumen Summe der Teile 19069.6383337, Original 19069.6383337
61
+ OK flaeche Flaeche ohne Deckel 5501.38007, Original 5501.38007
62
+ OK quelle Quelldatei 9e2b374f3c40... = Hash in der Begleitdatei
63
+ OK hausdorff Hausdorff (Eckpunkte, ohne Begleitdatei zusammengesetzt) 0, erlaubt 0.000103
64
+ ```
65
+
66
+ ## Befehle
67
+
68
+ | Befehl | Was er tut |
69
+ |---|---|
70
+ | `meshcut split EIN AUSORDNER ...` | zerlegt ein Netz, schreibt die Teile und `meshcut.json` |
71
+ | `meshcut join ORDNER AUS.stl` | setzt die Teile eines Ordners bitgenau wieder zusammen (mit `meshcut.json`) |
72
+ | `meshcut join teil1.stl teil2.stl AUS.stl` | ohne Begleitdatei: Näherung (Deckelpaare weg, Dreiecke bleiben fein) |
73
+ | `meshcut verify ORDNER [--source ORIGINAL]` | prüft den Rundlauf der gespeicherten Dateien |
74
+ | `meshcut segment EIN AUSORDNER [--parts N] [--names a,b,c] [--prompt "…"] [--backend …]` | findet Teile automatisch (und benennt sie), schreibt sie als Zuordnungskarte, prüft den Rundlauf |
75
+ | `meshcut regions EIN AUSORDNER` | nummeriert die Elemente (Teile, Objekte, Gruppen, Materialien): `regions.png` mit Nummern, `regions.json` mit Punkt, Rahmen, Fläche, Material |
76
+ | `meshcut remove EIN --region N` | entfernt ein Element, schließt das Loch sauber (Material, UV, Normalen der Umgebung), schreibt `EIN_edit.obj` |
77
+ | `meshcut swap EIN --region N [--shape box\|sphere\|cylinder]` | ersetzt ein Element durch einen Grundkörper gleicher Größe, mit dem Material des Originals |
78
+ | `meshcut tools` | alle Befehle als Tool-Definition (JSON-Schema) für KI-Assistenten, aus dem Parser erzeugt |
79
+ | `meshcut serve --root ORDNER --mcp` oder `--http PORT` | MCP-Server (stdio) bzw. HTTP-API für Agenten |
80
+ | `meshcut info DATEI` | Eckpunkte, Dreiecke, Volumen, Fläche, wasserdicht, Euler-Zahl, Hash |
81
+ | `meshcut labels DATEI KARTE.npy --grid 2x2x2` | schreibt eine Zuordnungskarte (Teilnummer pro Dreieck) für ein Gitter |
82
+
83
+ ### Arten zu zerlegen (`split`)
84
+
85
+ ```bash
86
+ meshcut split m.stl out --plane x=12.5 # eine Ebene (x, y oder z = Wert)
87
+ meshcut split m.stl out --plane x=0 --plane 1,1,0,4 # mehrere, auch schräg: a,b,c,d = a*x+b*y+c*z = d (negativ: --plane=-1,0,0,5)
88
+ meshcut split m.stl out --grid 2x2x3 # Gitter über den Begrenzungsquader, Teilnummer = Zelle
89
+ meshcut split m.stl out --max 220x220x250 # so viele gleichmäßige Schnitte, dass jedes Teil in den Druckraum passt
90
+ meshcut split m.stl out --wedges 8 --axis z # 8 Keile um die z-Achse (gerade Zahl; --center 10,5 verschiebt die Achse)
91
+ meshcut split m.stl out --labels karte.npy # Zuordnungsmodus: Geometrie bleibt unverändert
92
+ ```
93
+
94
+ Weitere Optionen: `--format stl|obj|ply|3mf|glb` (3MF und GLB legen alle Teile in **eine** Datei), `--no-cap` (ohne Deckel, für offene Netze), `--flip` (Dreiecke umdrehen, wenn das Netz nach innen orientiert ist), `--snap` (siehe unten), `--verify`.
95
+
96
+ **Zuordnungskarte:** eine Datei (`.npy`, `.json` oder `.csv`) mit **einer ganzen Zahl pro Dreieck** (Teilnummer, Lücken erlaubt, höchstens 1024 Teile). So lassen sich Ergebnisse einer Netz-Segmentierung (z. B. PartField, SAMesh, P3-SAM) verwenden: einfach ihre Dreiecks-Labels als `.npy` speichern. meshcut zeichnet selbst nur Gitter-Karten (`meshcut labels`).
97
+
98
+ ## KI: Teile finden und benennen (`segment`)
99
+
100
+ ```bash
101
+ meshcut segment figur.stl teile --parts 3 # eingebaut: räumliche Gruppen (k-Means), ohne Modell und ohne Netz
102
+ meshcut segment figur.stl teile --names Kopf,Rumpf,Beine --format 3mf # Anzahl und Namen; Namen werden Objektnamen in 3MF/GLB
103
+ meshcut segment szene.glb teile --backend components # eigenständige Hüllen (Gehäuse, lose Teile)
104
+ meshcut segment figur.stl teile --prompt "trenne Kopf, Arme, Beine" # Sprachmodell holt die Namen aus dem Satz
105
+ ```
106
+
107
+ Das Ergebnis ist **immer eine Zuordnungskarte** (ein Wert pro Dreieck). Teil 0 ist das höchste Teil (z), dann abwärts, damit Namen stabil bleiben. Die Namen stehen in `meshcut.json` (`names`) und werden beim Einlesen streng geprüft (Buchstaben, Ziffern, Leerzeichen, `- . _`, höchstens 64 Zeichen, eindeutig).
108
+
109
+ | Verfahren (`--backend`) | Quelle | Einrichtung |
110
+ |---|---|---|
111
+ | `kmeans` (Vorgabe), `components` | eingebaut, deterministisch | keine |
112
+ | `command` | lokales Modell als Befehl (PartField, SAMesh, eigenes Skript) | `MESHCUT_SEGMENTER_CMD='python mein_modell.py {input} {output} {parts}'` |
113
+ | `http` | gehosteter Dienst, der ein GLB annimmt und `{"labels": [...]}` zurückgibt | `MESHCUT_SEGMENT_URL`, `MESHCUT_SEGMENT_KEY` |
114
+
115
+ Sprachmodell zum Benennen (`--prompt`): `ANTHROPIC_API_KEY` (Modell über `MESHCUT_LLM_MODEL`, Vorgabe `claude-sonnet-5-5`) **oder** ein OpenAI-kompatibler Endpunkt mit `MESHCUT_LLM_URL`, `MESHCUT_LLM_MODEL`, `MESHCUT_LLM_KEY`. Ist `MESHCUT_LLM_URL` gesetzt, gewinnt der Endpunkt; der Anthropic-Schlüssel geht nur an `api.anthropic.com`. Das Modell bekommt nur Namen und Kennzahlen der Teile (Lage, Größe), kein Netz; die Antwort wird geprüft (jeder Name genau einmal, nur bekannte Teile).
116
+
117
+ **Sicherheit.** Schlüssel kommen nur aus der Umgebung, nie aus Dateien oder Argumenten, und stehen weder in Ausgaben noch in `meshcut.json`. Entfernte Adressen müssen `https` sein (`http` nur für localhost), Weiterleitungen werden nicht befolgt, und was ein eigener Befehl auf stderr schreibt, reicht meshcut nicht weiter. Netzzugriff gibt es nur, wenn Sie ihn einrichten (`http`-Segmentierer, `--prompt`); `--prompt` mit `ANTHROPIC_API_KEY` ruft `api.anthropic.com` auf (oder den https-Endpunkt aus `MESHCUT_ANTHROPIC_URL`, falls Sie ihn setzen; der Schlüssel geht dann dorthin).
118
+
119
+ **Lizenzen der bekannten Modelle (Stand 10.11.2026, vor dem Einsatz selbst prüfen):** PartField (NVIDIA) nur nicht-kommerziell; P3-SAM/Hunyuan3D-Part (Tencent) gilt laut Lizenz nicht in EU, UK und Südkorea; SAMesh hat keine Lizenzdatei; PartCrafter (MIT) erzeugt Teile aus einem Bild, zerlegt aber kein vorhandenes Netz. meshcut bringt keines davon mit, der Adapter ruft nur an, was Sie selbst eingerichtet haben.
120
+
121
+ ## Mit KI-Assistenten bedienen
122
+
123
+ meshcut ist dafür gebaut, dass ein KI-Assistent (Claude, ChatGPT, Codex und andere) es steuert: ein Befehl pro Aufgabe, klare Fehlerzeilen, Ergebnisse als Dateien. Sag zum Beispiel:
124
+
125
+ > „Nimm die Antenne vom Roboter ab und schließ die Stelle sauber.“
126
+ > „Ersetze den Knauf durch eine Kugel in derselben Größe, mit demselben Material.“
127
+ > „Teil das Modell so, dass es auf mein Druckbett 220 × 220 passt, und prüf, dass nichts fehlt.“
128
+
129
+ Der Assistent wählt den Befehl (`regions` + `remove`, `regions` + `swap`, `split --max` + `verify`), meshcut führt ihn exakt aus. meshcut selbst versteht keine Sätze, es ist die verlässliche Ausführung dahinter. Das Modellieren von Hand entfällt: der Assistent sagt, was er will, meshcut erledigt Auswahl, Lochschluss, Material, UV und Normalen selbst.
130
+
131
+ Das Werkzeug für Assistenten (Harness):
132
+
133
+ - `meshcut regions modell.obj ordner` nummeriert die erkennbaren Elemente: zusammenhängende Teile, Objekte, Gruppen und Materialien (`regions.png` mit Nummern im Bild, `regions.json` mit Punkt, Rahmen, Fläche, Volumen und Material). Der Assistent schaut das Bild an und nennt die Nummer, ohne Koordinaten zu raten; alternativ wählt `--at x,y,z` das kleinste Element an einem Punkt (bei gleich großen gewinnt die kleinere Nummer) und `--name` ein Material, Objekt oder eine Gruppe (auch wenn das Element in der Liste als „Teil N“ steht; passt ein Name auf mehrere Elemente, bricht meshcut ab). Das Bild zeigt eine Ansicht: verdeckte Elemente haben keine Nummer im Bild (`visible: false` in `regions.json`), sie sind trotzdem über Nummer, `--at` oder `--name` wählbar. Mehr als 500 Elemente werden nicht nummeriert; dann wählt `--at` unter den nummerierten das kleinste.
134
+ - `meshcut tools` gibt alle Befehle als Tool-Definition (JSON-Schema) aus, die jeder Agent so registrieren kann. Sie wird aus dem Parser erzeugt und bleibt damit immer aktuell. Der MCP-Server und die HTTP-API bieten `regions`, `remove` und `swap` ebenfalls an.
135
+ - `remove` und `swap` messen am Modell selbst: Das Loch wird mit einem Ohrenschnitt in der Randebene geschlossen (ohne neue Punkte, jedes Dreieck mit eigener Normale). Folgt die Umgebung einer Wölbung (Kugel, Zylinder, Schale), legt meshcut einen Paraboloid an Rand und ersten Nachbarring und füllt mit Zwischenringen auf dieser Fläche; das greift nur bei einem sternförmigen Rand und einer Wölbung ab 1 % des Lochdurchmessers, eine ebene Fläche bleibt exakt eben. Material und UV-Werte kommen von der Umgebung (die UV der Zwischenringe aus der Lage, am Rand gefittet), die Glättung des Ersatzes kommt aus der Form. Ein Rand, der weder ebene Triangulation noch einen Fächer erlaubt, wird abgewiesen. Ändert sich das Volumen eines einzelnen geschlossenen Körpers um mehr als 2 %, nennt der Bericht die Zahl. Folgt der Rand einer Kugel (Kappen bis zur Halbkugel), wird die Füllung eine Kugelkappe; sonst gilt ein Paraboloid, und ragt dessen Wölbung über 15 % des Lochdurchmessers, bleibt die Füllung flach, statt eine Spitze ins Leere zu setzen. Ein Loch mit nicht ebenem, aber triangulierbarem Rand (etwa ein Fenster von 180° in einem Rohr) wird flach gefüllt und meshcut sagt das ausdrücklich dazu (`Hinweis`); auch bei `swap` ohne `--shape` meldet es, wenn keine Form gut passt (Abweichung über 0,15 der Diagonale). Liegt das Loch auf einer UV-Naht, bekommen die neuen Ecken fortlaufende UV-Werte (z. B. 1,02 statt 0,02), die Textur muss dafür wiederholen. Der Ersatz hat die Größe des Originals mal `--scale` (0,01 bis 100); ohne Material im Original bleibt er ohne Material (`usemtl off`). Der Assistent muss keine Parameter mitliefern (`--shape`, `--axis`, `--scale`, `--material` sind nur Feinschliff).
136
+ - Bei `swap` ohne `--shape` rechnet meshcut alle Kandidaten (Quader, Kugel, Zylinder je Achse), misst bei jedem den Abstand zum Original in beide Richtungen und nimmt den besten; die Zeile „Kandidaten verglichen“ zeigt die Werte. Beim Lochschluss wird ein Ohrenschnitt mit Splittern gegen einen Fächer vom Mittelpunkt abgewogen.
137
+ - Der Messprüfstand `bench/edit_bench.py` baut Netze mit bekannter Wahrheit (Platte und Kugel mit Höcker, rechteckig und C-förmig, freie Teile zum Ersetzen), entfernt/ersetzt und misst Außenbereich, offene Kanten, Abweichung, Fläche, Normalen, UV, Windung, Dreiecksgüte und Doppellauf, in fünf Maßstäben von 1e-9 bis 1e9. Die Schwellen stehen im Kopf der Datei und wurden vor dem Messen festgelegt; eine nachträgliche Lockerung ist dort ausgewiesen.
138
+ - Am Ende steht eine Prüfzeile: „von 24 Dreiecken 2 entfernt, 2 neu dazugekommen; die übrigen 22 sind unverändert (Eckpunkt, UV, Normale, Material verglichen)“. Meshcut liest dafür die geschriebene Datei zurück, vergleicht jede unberührte Fläche und prüft bei den neuen Flächen Material, Zahl und endliche Koordinaten; die Zahlen in der Zeile stammen aus dieser Datei. Stimmt etwas nicht, bricht es ab und entfernt die Ausgabe. Die Prüfung belegt nicht, dass das Ergebnis schön aussieht; die Deckel sind einfache Dreiecke, kein Remeshing. Bearbeitet werden höchstens 500 000 Flächen (größere Netze vorher mit `split` teilen).
139
+
140
+ OBJ wird vollständig mitgeführt (Material, UV, Normalen, Objekt- und Gruppennamen, Glättungsgruppen, `mtllib` wird mitkopiert). STL, PLY, 3MF und GLB werden hier nur mit Geometrie geschrieben (Farben, Materialien, UV gehen verloren); dort prüft meshcut Dreieckszahl und Koordinaten, und die Prüfzeile sagt es. Die Eingabedatei wird nie überschrieben.
141
+
142
+ ## Für Agenten: MCP und HTTP
143
+
144
+ ```bash
145
+ meshcut serve --root ./arbeit --mcp # MCP über stdin/stdout (Claude, Codex u. a.)
146
+ MESHCUT_TOKEN=geheim meshcut serve --root ./arbeit --http 8765
147
+ ```
148
+
149
+ Werkzeuge: `info`, `split`, `segment`, `join`, `verify`, `regions`, `remove`, `swap` (Schema über `tools/list` bzw. `GET /v1/tools`). Dateien werden nur unterhalb von `--root` gelesen und geschrieben, auch nicht über Links oder `..`. Die HTTP-API bindet an `127.0.0.1`; ohne `MESHCUT_TOKEN` nimmt sie nur Anfragen mit `Host: localhost` und `Content-Type: application/json` an (Schutz vor Angriffen aus dem Browser). Eine andere Adresse (`--host`) geht nur mit Schlüssel (Bearer).
150
+
151
+ ```bash
152
+ curl -s -H "Authorization: Bearer geheim" -H "Content-Type: application/json" \
153
+ -d '{"input":"figur.stl","outdir":"teile","parts":3}' http://127.0.0.1:8765/v1/segment
154
+ ```
155
+
156
+ ## Was genau garantiert wird
157
+
158
+ Zwei Stufen, die man nicht vermischen darf:
159
+
160
+ **Zuordnungsmodus.** Die Eckpunkte und Dreiecke bleiben unverändert, es werden nur Dreiecke auf Teile verteilt. Setzt man die Teile wieder zusammen, kommt dieselbe Dreiecksmenge heraus: gleicher SHA-256, **bitgenau**.
161
+
162
+ **Schnittmodus.** Dreiecke werden an Ebenen zerlegt. Der Rundlauf ist trotzdem exakt, weil meshcut in `meshcut.json` für jedes Teildreieck die Nummer seines Quelldreiecks und für jedes zerschnittene Dreieck dessen Original-Koordinaten (64 Bit) speichert. `join` entfernt die Deckel und setzt die Original-Dreiecke wieder ein; der Hash stimmt mit dem der Quelle überein. Ohne Begleitdatei bleibt die Geometrie gleich (Hausdorff-Abstand ~ Rundungsfehler), nur die Dreiecke bleiben so fein, wie der Schnitt sie gemacht hat.
163
+
164
+ **Dateiformat und Genauigkeit.** STL und GLB speichern 32 Bit: der Hash wird dann nach Rundung auf float32 gebildet (steht in `meshcut.json` als `precision`). Wer **wirklich 64 Bit** will, nimmt `--format obj` oder `3mf` (Text mit 17 Stellen, ohne Verlust).
165
+
166
+ **Rundlauf-Kriterien des Schnittmodus** (alle in `verify`):
167
+ - **Teile unverändert:** jede Teildatei hat denselben Hash wie beim Schreiben (Fragmente und Deckel eingeschlossen). Verschobene, beschädigte oder ausgetauschte Teile fallen sofort auf, auch ohne `--source`.
168
+ - **Deckel auf den Schnittebenen:** jedes Deckel-Dreieck liegt mit allen drei Ecken auf einer der in `meshcut.json` gespeicherten Ebenen. Ein Schnitt an der falschen Stelle fällt auf.
169
+ - Volumen aller Teile = Volumen des Originals, Fläche ohne Deckel = Originalfläche, jedes Teil wasserdicht (jede Kante genau zweimal, gegenläufig), Euler-Zahl gerade, Hash gleich.
170
+ - Mit `--source`: Hash der Quelldatei und Hausdorff-Abstand der ohne Begleitdatei zusammengesetzten Teile. Bei großen Netzen prüft der Hausdorff-Abstand eine **Stichprobe** der Eckpunkte (steht dann im Text); die Sicherheit kommt aus den Hashes, der Hausdorff-Abstand ist eine zusätzliche, unabhängige Gegenprobe.
171
+
172
+ Erlaubt sind 1e-9 relativ bei 64 Bit und 1e-4 bei 32 Bit; bei STL/GLB weit vom Ursprung kommt die float32-Rundung der Koordinaten dazu.
173
+
174
+ **Einheiten.** 3MF-Dateien werden beim Einlesen nach Millimeter umgerechnet (`inch`, `centimeter`, `meter`, `micron`, `foot`); meshcut schreibt 3MF immer in Millimeter. Die Größe in der Welt bleibt gleich, nur die Zahlen ändern sich.
175
+
176
+ **Abbruch beim Schreiben.** `split` ersetzt einen Ausgabeordner als Ganzes: Fehler und Ausnahmen rollen zurück, und auch nach einem harten Abbruch (Stromausfall, `kill -9`) legt ein Journal im versteckten `.meshcut_…`-Ordner fest, was passiert: Der nächste Aufruf von `split` auf diesen Ordner stellt den alten Satz wieder her (oder schließt ein fertiges Ersetzen ab) und meldet das auf stderr. `join` und `verify` räumen nur eigene Reste (Marker `.meshcut-staging` oder Journal, keine Links) auf, die älter als zehn Minuten sind, damit sie einen gerade laufenden `split` in einem anderen Prozess nicht stören. Zwei `split` gleichzeitig in denselben Ordner sind nicht vorgesehen (innerhalb des Dienstes sorgt eine Sperre dafür, dass immer nur ein Werkzeug läuft).
177
+
178
+ ### Wie geschnitten wird
179
+
180
+ 1. Jeder Eckpunkt bekommt ein Vorzeichen zur Ebene (davor / dahinter / auf der Ebene). Weil das Vorzeichen pro Eckpunkt feststeht, entscheiden beide Dreiecke an einer Kante gleich.
181
+ 2. Je Kante, die die Ebene kreuzt, entsteht **genau ein** neuer Eckpunkt (Endpunkte sortiert, `p = a + t·(b−a)`, `t = da/(da−db)`), beide Seiten verweisen darauf.
182
+ 3. Der Rand jedes Teils liegt danach in der Ebene. Daraus entstehen geschlossene Umrisse; Außenumrisse und Löcher werden erkannt, Löcher über Brückenkanten angebunden, die Fläche mit Ohrenschnitt trianguliert. Alle Randpunkte bleiben erhalten, deshalb schließt der Deckel ohne Spalt.
183
+ 4. Der Deckel des einen Teils ist das gespiegelte Gegenstück des anderen. Bei mehreren Ebenen werden auch Deckel weiter zerschnitten und bleiben dabei Paare.
184
+ 5. **Dreiecke, die in der Ebene liegen**, gehören zu der Seite, hinter der das Material liegt. Flächenlose Dreiecke in der Ebene gehen auf die Seite ihrer Nachbarn.
185
+ 6. `--snap` (Standard 1e-12): Eckpunkte, die nur um Rundungsrauschen neben der Ebene liegen (z. B. `cos(90°)` bei einer Kugel), gelten als *auf* der Ebene. Das verschiebt keinen Eckpunkt, es vermeidet nur Haarrisse-Dreiecke. `--snap 0` nimmt das exakte Vorzeichen.
186
+
187
+ ## Python
188
+
189
+ ```python
190
+ import kkmeshcut as mc
191
+
192
+ side = mc.split("examples/torus.stl", "teile", plane=["x=0", "z=0"], verify=True) # dict aus meshcut.json
193
+ mc.join("teile", "zurueck.obj")
194
+ r = mc.verify("teile", source="examples/torus.stl") # {'ok': True, 'checks': [...], ...}
195
+ print(mc.info("examples/torus.stl")["volume"])
196
+
197
+ mc.regions("figur.obj", "nummern") # nummern/regions.png + regions.json
198
+ r = mc.swap("figur.obj", region=3, shape="sphere") # {'output': 'figur_edit.obj', 'text': '... Pruefung: ...'}
199
+ mc.remove("figur.obj", name="Antenne", out="ohne.obj")
200
+ ```
201
+
202
+ Die Schnittstelle führt dieselben Befehle aus wie die Kommandozeile (gleiche Optionen mit Unterstrich: `no_cap=True`), schweigt auf stdout und stderr und wirft `mc.MeshcutError` statt das Programm zu beenden. Tiefer unten liegen `Mesh`, `split_planes`, `split_labels`, `triangle_hash`, `mesh_stats` für eigene Abläufe mit numpy-Arrays.
203
+
204
+ ## Im Browser
205
+
206
+ **[calyiex.github.io/meshcut](https://calyiex.github.io/meshcut/)** – derselbe Kern läuft in Pyodide/WebAssembly, nichts wird hochgeladen. Datei wählen, Schnitt einstellen, Teile als ZIP speichern; zum Zusammensetzen alle Teile samt `meshcut.json` wieder auswählen. Bis 40 MB je Datei. Bei jedem Commit prüft das CI die Seite in WebKit (Safari/iPhone-Engine), Chromium und Firefox: Zerlegen und Zusammensetzen im Browser müssen den Hash der Quelle ergeben.
207
+
208
+ ## Grenzen (ehrlich)
209
+
210
+ - **`split`, `join`, `segment` behandeln nur Geometrie.** UV-Koordinaten, Farben, Normalen und Materialien werden dort nicht übernommen; Texturen und Vertexfarben bleiben also nicht erhalten. (`regions`, `remove` und `swap` führen sie in OBJ mit, siehe unten.) Eckpunkte mit gleichen Koordinaten werden beim Einlesen verschmolzen (GLB-Nähte, STL-Dreiecksuppe).
211
+ - **Deckel brauchen ein wasserdichtes, nach außen orientiertes Netz.** Sonst bricht `split` mit einer klaren Meldung ab (`--no-cap` schneidet trotzdem, `--flip` dreht die Orientierung).
212
+ - **Keile nur in gerader Zahl.** Ungerade Keilzahlen bräuchten Halbebenen.
213
+ - **Stifte und Passungen** (Dübel, Zapfen/Loch mit Spiel) gibt es in v0.1 noch nicht, ebenso keine Bearbeitung mehrerer Objekte einer Datei auf einmal (3MF/GLB mit mehreren Objekten werden als ein Netz gelesen). manifold3d wird nur in den Tests als unabhängige Gegenprobe benutzt (Volumen der Teile gegen `split_by_plane`), nicht zur Laufzeit.
214
+ - **Triangulierung der Deckel** ist gültig und deckungsgleich, aber nicht „schön“: Ohrenschnitt erzeugt gern lange schmale Dreiecke. Für den Druck unkritisch, für Simulation ungeeignet. Läuft der Ohrenschnitt in einen Notfall (Punkte exakt aufeinander), meldet `split` das.
215
+ - **Bearbeiten (`remove`/`swap`) – bekannte Lücken:** Texturen in Unterordnern werden bei `--out` in einen anderen Ordner nicht mitkopiert (nur die `.mtl`); OBJ-Eingaben in UTF-16 oder mit Zeilenfortsetzung `\` werden abgelehnt; Vertexfarben (`v x y z r g b`) bekommen für neue Eckpunkte keine Farbe; eine Füllung, die weder einer Kugel noch einem flachen Paraboloid folgt (z. B. eine hohe Spitze), bleibt flach und verkleinert das Volumen ohne eigenen Hinweis; sehr große Netze (100 000+ Dreiecke) brauchen Sekunden, weil die Bearbeitung Python-Schleifen nutzt; Koordinaten jenseits von etwa 1e76 bricht `remove` mit einer Meldung zum Zahlenbereich ab.
216
+ - **Form der Füllung ist eine Näherung.** Auf einer echten Kugel mit glattem Rand folgt sie der Kugel (Kappen bis zur Halbkugel; bei zackigem Rand, etwa einer Auswahl per Schwerpunkt, fällt sie auf eine flache Füllung zurück und der Bericht sagt das, Beispiel −17 % bei 65°); sonst gilt ein Paraboloid durch Rand und ersten Ring, der Ellipsoide bis rund 9 % Volumen überschießen kann und bis 0,14 der Kugelgröße neben der Fläche liegen darf. Eine Halbkugel-Kappe liegt zwar auf der Kugel, verliert aber durch die feste Dichte (unten) rund 6 % Volumen. Bei mehr als 2 % Volumenänderung nennt der Bericht die Zahl; darunter schweigt er. Der Hinweis rechnet mit dem Betrag des Volumens und gilt nur für einen einzelnen geschlossenen Körper; bei Koordinaten jenseits von etwa 1e100 oder unter 1e-100 fehlt er. Die Füllung hat eine feste Dichte (rund 240 Dreiecke), bei sehr großen Kappen wird sie grob. Zufällig gezackte Ränder werden oft abgelehnt (Selbstprüfung, „zu verwickelt“), nicht falsch gefüllt; auf der Testmatrix mit Ellipsoiden und Kugeln waren es rund 40 %. `swap` ersetzt ein Element durch den besten Grundkörper und meldet erst ab einer Abweichung von 0,15 der Diagonale, dass er nur grob passt.
217
+ - **Geschwindigkeit.** Der Kern ist numpy; die Deckel-Triangulierung ist Python. Gemessen: `split` mit einer Ebene auf rund 100 000 Dreiecken etwa 5 Sekunden (mit Schreiben und Prüfungen), ein Gitter 3×3×3 etwa 18 Sekunden; Deckel mit mehreren tausend Randpunkten brauchen Sekunden. `remove` braucht auf 100 000 Dreiecken rund 10 Sekunden.
218
+ - **Ebene durch einen konkaven Eckpunkt oder eine Kante des Netzes:** berühren sich die Teile danach an einer Kante, ist ein Teil nicht wasserdicht. `split` meldet das („Teil … ist nicht wasserdicht“), `verify` ebenfalls.
219
+ - **Zielformat mit 32 Bit (STL, GLB):** liegt eine Ebene weniger als etwa 5e-7 der Netzgröße neben einem Eckpunktring, würden Eckpunkte des Deckels beim Runden mit denen des Netzes zusammenfallen. `split` erkennt das (Test auf den gerundeten Teilen) und zählt solche Eckpunkte dann als auf der Ebene; liegt das Netz weit vom Ursprung (gröbere 32-Bit-Schritte), wächst die Schwelle mit dem Abstand; hilft das nicht (auch bei eigenem `--snap`), verweigert `split` und schreibt nichts Kaputtes. Sind die 32-Bit-Schritte grob im Verhältnis zur Netzgröße (über 1e-4), nennt `split` das in einem Hinweis; Schnittflächen und Summen weichen dann messbar ab. Die Hinweise stehen auch in der Rückgabe von `meshcut.split()` und `warnings` im Dienst (nicht in `meshcut.json`); `verify` erlaubt für Volumen und Fläche dann den Rundungsfehler der Quelle. Mit eigenem `--snap` gilt Ihr Wert unverändert und `--verify` zeigt dann, ob die Dateien halten.
220
+ - **Eine Ebene mit negativer erster Zahl** (`--plane -0.55,-0.43,0.72,4.1`) liest argparse als Option; mit `--plane=-0.55,-0.43,0.72,4.1` geht es.
221
+ - **Weit vom Ursprung:** bei einem Netz, das um mehr als etwa das 1e5-fache seiner Größe vom Ursprung entfernt liegt, scheitern in `verify` Volumen und Fläche (und bei noch größerem Abstand die Wasserdichtheit) auch bei Formaten mit 64 Bit; die Rechnung verliert dort Stellen. `verify` meldet das laut, es bleibt kein stiller Fehler. Das Netz vorher zum Ursprung verschieben.
222
+ - **Die Reihenfolge der Dreiecke in einer Teildatei gehört zum Beweis.** Die Deckel stehen am Ende der Datei; schreibt ein anderes Programm (Slicer, Mesh-Editor) eine Teildatei mit denselben Dreiecken in anderer Reihenfolge neu, schlagen `ebenen`, `hash`, `reihenfolge` und `flaeche` an, obwohl die Geometrie gleich ist. Dann `join` ohne Ordner (aus den Dateien, Näherung) oder die Teile unverändert lassen.
223
+ - **`--flip` und der Rundlauf-Beweis.** `--flip` dreht die Dreiecke vor dem Teilen; `meshcut.json` und `join` gelten für das gedrehte Netz. Ein `verify --source` gegen die ursprüngliche Datei zeigt darum Abweichungen bei Quelle und Reihenfolge. `split` sagt das beim Start.
224
+ - **3MF mit 64 Bit.** meshcut schreibt 3MF mit float64 (Hash bitgenau); manche Slicer lesen 3MF als float32, dann gilt der bitgenaue Rundlauf nur für meshcut selbst.
225
+ - **32-Bit-Dateien und Topologie.** Bei STL/GLB können nahe beieinanderliegende Schnittpunkte beim Runden auf float32 zusammenfallen; dann meldet `verify` eventuell `wasserdicht`, obwohl der 64-Bit-Satz in Ordnung wäre. Wer das nicht will, nimmt `--format obj`, `ply` oder `3mf`.
226
+ - **Die Begleitdatei ist keine Signatur.** Die Hashes in `meshcut.json` belegen, dass nichts zufällig oder unbemerkt verloren ging oder vertauscht wurde. Wer die Teile *und* `meshcut.json` absichtlich zusammen umschreibt und alle Zahlen neu rechnet, erzeugt einen in sich stimmigen Satz, den `verify` ohne Quelle nicht von einem echten unterscheidet. Für Echtheit gegenüber Dritten: `verify --source ORIGINAL` mit der Originaldatei oder den Hash der Quelle (`source_hash`) getrennt aufbewahren.
227
+ - **Dienst: ein Werkzeug zur Zeit.** Ein Aufruf über MCP/HTTP hält die Sperre, bis er fertig ist, und der HTTP-Dienst hat keine Obergrenze für gleichzeitige Verbindungen (er ist für Vertrauenswürdige gedacht, nicht fürs offene Netz); ein eigener Segmentierungsbefehl darf bis zu einer Stunde laufen. Wer den Dienst teilt, schaltet ihn mit `MESHCUT_TOKEN` ab und lässt nur Vertrauenswürdige heran: jeder Aufrufer kann den eingerichteten Befehl oder das Sprachmodell (Kosten) auslösen.
228
+ - **Eingelesene Dateien sind begrenzt** (Schutz vor Dateien, die klein sind und sich beim Auflösen vervielfachen): höchstens 10 Millionen Dreiecke nach dem Auflösen aller Instanzen (GLB-Knoten, 3MF-Komponenten), 100 000 Knoten-/Komponentenbesuche, 128 MiB entpackte 3MF-Modelldatei, 5000 Ecken je Fläche und ein Arbeitsbudget für alle Flächen mit mehr als drei Ecken (Vierecke zählen ebenfalls; konvexe Vierecke gehen einen schnellen Weg, alles andere kostet mehr). Das ist ein Deckel gegen Hänger, kein Speicherschutz: 10 Millionen Dreiecke brauchen mehrere GB Arbeitsspeicher, 3MF-Dateien etwa das 20-fache der XML-Größe. Wer meshcut als Dienst für Fremde betreibt, begrenzt zusätzlich Speicher und Laufzeit des Prozesses selbst.
229
+ - **Sehr große Koordinaten.** Weit vom Ursprung (ab etwa dem 1e8-fachen der Netzgröße) geht in 64 Bit die Auflösung aus; in STL/GLB (32 Bit) schon ab etwa dem 1e5-fachen. Vorher das Netz in die Nähe des Ursprungs verschieben.
230
+ - **Bearbeiten (`remove`, `swap`) ist kein exakter Schnitt.** Es gibt keinen Rundlauf-Beweis wie bei `split`; stattdessen liest meshcut die geschriebene Datei zurück und belegt, dass jede unberührte Fläche (Eckpunkt-, UV-, Normalen- und Materialtext, Reihenfolge) unverändert ist, und prüft, dass keine neue Fläche gegenläufig auf einer vorhandenen liegt (gerichtete Doppelkanten). Das Schließen eines Lochs und der Ersatz sind eine gute, keine perfekte Wahl: ebene und konkave Ränder werden mit einem Ohrenschnitt aus Randpunkten gefüllt (bei konkaven Löchern auf gewölbter Fläche bleibt der Deckel flach: im Prüfstand verliert er dort etwa 8 % Fläche), sternförmige Löcher auf gewölbter Fläche folgen der Wölbung; Inseln im Loch (ein behaltenes Dreieck mitten im Rand) werden nicht erkannt; als Ersatz gibt es Quader, Zylinder und Kugel in der Größe des Originals (keine Nachbildung der Form, keine Textur-Neuberechnung, die UV nehmen den Bereich des Originals). Fehlen dem Modell UV oder Normalen, schreibt meshcut auch keine.
231
+ - **Elemente heißen nach Reihenfolge.** Die Nummern aus `regions` gelten für genau diese Datei in ihrem jetzigen Zustand; nach einer Bearbeitung neu nummerieren. Als Elemente zählen zusammenhängende Teile (über gleiche Eckpunktlage, UV-Nähte trennen nichts), Objekte, Gruppen und Materialien; Elemente, die dieselben Flächen haben wie ein früheres, stehen nicht doppelt da. Linien und Punkte (`l`, `p`) eines OBJ werden nicht übernommen (meshcut sagt es).
232
+ - **Die eingebauten Verfahren sind einfach.** `kmeans` teilt nach Lage, nicht nach Bedeutung; für echte Teilerkennung (Arm, Griff, Rad) braucht es ein Modell über `command` oder `http`. Das ist beabsichtigt: meshcut garantiert, was nach der Karte kommt, nicht die Qualität der Karte.
233
+ - **Höchstens 1024 Teile** (`--grid`, `--max`): wird vor dem Schneiden geprüft.
234
+ - Nichtmanifold-Eckpunkte, an denen sich zwei Teile nur in einem Punkt berühren, sind erlaubt; `verify` zählt sie für die Euler-Zahl getrennt.
235
+
236
+ ## Entwicklung
237
+
238
+ ```bash
239
+ pip install -e ".[check]" # pytest, hypothesis, trimesh, manifold3d (Gegenproben)
240
+ python -m pytest -q tests
241
+ MESHCUT_EXAMPLES=300 python -m pytest -q tests/test_property.py # gründlicher
242
+ ```
243
+
244
+ Die Tests prüfen unter anderem (Befunde aus den Prüfrunden stehen in `tests/test_review.py`, auch der harte Abbruch mit `os._exit`): Zufallsebenen, Ebenen durch Eckpunkte/Kanten/Flächen (hypothesis), Dreiecke in der Ebene, Keile um eine Achse, Torus/Hohlkugel (Löcher und Inseln im Deckel), alle fünf Formate, Absturz-Injektion beim Schreiben, Fremddateien im Ausgabeordner und den Vergleich mit trimesh und manifold3d. Dazu kommt ein Mutationstest (345 absichtlich eingebaute Fehler in Kern, Bearbeitung (133 davon), KI-Schicht und Dienst, jeder wird von den Tests bemerkt; `python tests/mutate.py`) sowie Tests für KI-Adapter (lokale Fake-Dienste), MCP und HTTP-API. Die Browser-Version liegt als Kopie in `docs/kkmeshcut.py`; ein Test stellt sicher, dass beide Dateien gleich sind.
245
+
246
+ Lizenz: MIT, © K&K AI.