3d-card 0.1.0__tar.gz

3d_card-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Konstantinos Georgiou
+
+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.

3d_card-0.1.0/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: 3d-card
+Version: 0.1.0
+Summary: Turn a set of 3D-printable parts into one printable card: parts gated to a frame like a model-kit sprue, with a check that every part comes off clean. Includes print-in-place joints and printability checks
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/3d-card
+Keywords: 3d-printing,sprue,kit card,model kit,joints,print-in-place,trimesh,build123d
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: 3d-base>=0.1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: trimesh>=4.0
+Requires-Dist: manifold3d>=2.4
+Requires-Dist: scipy>=1.10
+Requires-Dist: shapely>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: build123d>=0.8
+Requires-Dist: rtree>=1.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: sim
+Requires-Dist: mujoco>=3.0; extra == "sim"
+Requires-Dist: coacd>=1.0; extra == "sim"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# 3d-card
+
+3d-card turns a set of 3D-printable parts into one printable card, like the sprue of a plastic model kit. The parts sit on a flat frame, each held by small gates at the bottom, and you print the whole card in one go, cut the parts off and put them together. Before it gives you the card, it cuts every gate itself and checks that every part comes back whole and loose (the round trip).
+
+I wrote it for a posable toy figure I designed and printed, and I could not find a public tool that makes this kind of card. It also has the print-in-place joints and the printability checks I needed on the way.
+
+![A made-up kit of a block, a rod on a peg and two wheels, laid out on one card](docs/example.png)
+
+## Install
+
+```bash
+pip install 3d-card
+pip install "3d-card[sim]"     # adds the MuJoCo stand-up test and convex decomposition
+```
+
+In Python it is imported as `card3d`. It uses build123d (the CAD kernel), trimesh and manifold3d for the geometry, and [3d-base](https://github.com/drkostas/3d-base) for mesh loading and pictures.
+
+## Make a card
+
+You give it a function that returns your parts, the joints between them and a list of notes.
+
+```python
+import trimesh
+from card3d import tosprue
+
+def source():
+    parts = {"body": trimesh.load("body.stl"), "arm": trimesh.load("arm.stl"), "wheel": trimesh.load("wheel.stl")}
+    joints = []            # optional, see below
+    return parts, joints, []
+
+got, report = tosprue.best_card(source=source)
+print(got["size"], got["fits_bed"], report["ok"])
+got["card"].export("card.stl")
+```
+
+`best_card` tries a few layouts and keeps the smallest one whose round trip passes. `build` makes one card with the options you pass. `export(out="card", name="card.stl", ...)` builds and writes it.
+
+What it does, in order.
+
+1. Each part is turned so it rests on a face with enough first layer. A part with only a few square millimetres on the plate comes loose in the first layers and the nozzle drags it away.
+2. The parts are laid out in rows, with a runner bar under each row.
+3. Gates are placed at the bottom of each part, in the frame's own plane, where the part comes closest to its bar. A gate higher up would print in the air.
+4. Each part gets a small number stamped on the frame next to it.
+5. The card is made into one solid, the gates are cut, and every piece is matched back to its part by area and size.
+
+The card is as tall as its tallest part, and it is checked against your printer's bed (`bed=(width, depth)` in mm, or set `card3d.sprue.BED`).
+
+### A card you can read
+
+By default the parts go into one row after another. To make the card read like the finished model (head at the top, legs lower down, and so on), pass the rows yourself.
+
+```python
+tosprue.build(source=source,
+              rows=[["head"], ["arm_left", "body", "arm_right"], ["leg_left", "leg_right"]],
+              down=["arm_left", "arm_right", "leg_left", "leg_right"],   # long axis down the card
+              across=["head"])                                         # long axis across it
+```
+
+Parts you do not name go into a last row. Someone can then put the kit together without instructions.
+
+### Joints
+
+`card3d.joints` makes the two halves of a joint (`male` is what sticks out, `female` is what is cut away) for pegs, axles, pivots, ball joints, tabs and cross laps. The clearances were measured on a real printer with the two test prints in `card3d.coupons` (0.30 mm for push fits, 0.20 mm for a pivot that holds its pose). Print the coupons on your own printer and change `joints.CLEAR` and `joints.PIVOT_CLEAR` if yours differ.
+
+If you list your joints in the source as `{"type": "peg", "size": 3.0, "axis": (1, 0, 0), "at": (x, y, z), "child": "arm", "parent": "body"}`, the card keeps gates away from them and does not cut a part's sole through a peg.
+
+## Flat cards and checks
+
+- `card3d.sprue.make_card` makes the flat version, a kit card of flat plates of one thickness, and `card3d.roundtrip.check` cuts it and checks every plate comes back.
+- `card3d.simulator` reports overhangs and where supports would leave marks, sweeps a peg into its socket to find collisions, finds the best print orientation, and with the `sim` extra decomposes a part into convex pieces and tests in MuJoCo whether the assembled model stands.
+- `card3d.labels` makes small 3D numbers for parts and cards.
+
+## Claude Code skill
+
+```bash
+3d-card skill             # copies it to ~/.claude/skills/3d-card
+```
+
+The skill gives Claude the whole procedure we used, in order. It starts with measuring clearances on your printer and goes through joints, building the card, reading its notes and the round trip, and checking the slice, up to the first physical print. It ends with a table of the failures we met (a card that printed as spaghetti, gates that cut a joint, parts that stayed on the frame) with how to check and fix each one.
+
+## Limits
+
+- It was built for one toy with about twenty parts. Cards with many more parts work, but the layout is a row packer, not an optimiser.
+- The round trip proves the gates can be cut in the model. Gate size still depends on your material and cutters, so print one card before printing many.
+- The clearances are from one printer and PLA.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test,sim]'
+.venv/bin/pytest
+python examples/make_example.py   # rebuilds docs/example.png
+```
+
+## License
+
+MIT

3d_card-0.1.0/README.md

@@ -0,0 +1,97 @@
+# 3d-card
+
+3d-card turns a set of 3D-printable parts into one printable card, like the sprue of a plastic model kit. The parts sit on a flat frame, each held by small gates at the bottom, and you print the whole card in one go, cut the parts off and put them together. Before it gives you the card, it cuts every gate itself and checks that every part comes back whole and loose (the round trip).
+
+I wrote it for a posable toy figure I designed and printed, and I could not find a public tool that makes this kind of card. It also has the print-in-place joints and the printability checks I needed on the way.
+
+![A made-up kit of a block, a rod on a peg and two wheels, laid out on one card](docs/example.png)
+
+## Install
+
+```bash
+pip install 3d-card
+pip install "3d-card[sim]"     # adds the MuJoCo stand-up test and convex decomposition
+```
+
+In Python it is imported as `card3d`. It uses build123d (the CAD kernel), trimesh and manifold3d for the geometry, and [3d-base](https://github.com/drkostas/3d-base) for mesh loading and pictures.
+
+## Make a card
+
+You give it a function that returns your parts, the joints between them and a list of notes.
+
+```python
+import trimesh
+from card3d import tosprue
+
+def source():
+    parts = {"body": trimesh.load("body.stl"), "arm": trimesh.load("arm.stl"), "wheel": trimesh.load("wheel.stl")}
+    joints = []            # optional, see below
+    return parts, joints, []
+
+got, report = tosprue.best_card(source=source)
+print(got["size"], got["fits_bed"], report["ok"])
+got["card"].export("card.stl")
+```
+
+`best_card` tries a few layouts and keeps the smallest one whose round trip passes. `build` makes one card with the options you pass. `export(out="card", name="card.stl", ...)` builds and writes it.
+
+What it does, in order.
+
+1. Each part is turned so it rests on a face with enough first layer. A part with only a few square millimetres on the plate comes loose in the first layers and the nozzle drags it away.
+2. The parts are laid out in rows, with a runner bar under each row.
+3. Gates are placed at the bottom of each part, in the frame's own plane, where the part comes closest to its bar. A gate higher up would print in the air.
+4. Each part gets a small number stamped on the frame next to it.
+5. The card is made into one solid, the gates are cut, and every piece is matched back to its part by area and size.
+
+The card is as tall as its tallest part, and it is checked against your printer's bed (`bed=(width, depth)` in mm, or set `card3d.sprue.BED`).
+
+### A card you can read
+
+By default the parts go into one row after another. To make the card read like the finished model (head at the top, legs lower down, and so on), pass the rows yourself.
+
+```python
+tosprue.build(source=source,
+              rows=[["head"], ["arm_left", "body", "arm_right"], ["leg_left", "leg_right"]],
+              down=["arm_left", "arm_right", "leg_left", "leg_right"],   # long axis down the card
+              across=["head"])                                         # long axis across it
+```
+
+Parts you do not name go into a last row. Someone can then put the kit together without instructions.
+
+### Joints
+
+`card3d.joints` makes the two halves of a joint (`male` is what sticks out, `female` is what is cut away) for pegs, axles, pivots, ball joints, tabs and cross laps. The clearances were measured on a real printer with the two test prints in `card3d.coupons` (0.30 mm for push fits, 0.20 mm for a pivot that holds its pose). Print the coupons on your own printer and change `joints.CLEAR` and `joints.PIVOT_CLEAR` if yours differ.
+
+If you list your joints in the source as `{"type": "peg", "size": 3.0, "axis": (1, 0, 0), "at": (x, y, z), "child": "arm", "parent": "body"}`, the card keeps gates away from them and does not cut a part's sole through a peg.
+
+## Flat cards and checks
+
+- `card3d.sprue.make_card` makes the flat version, a kit card of flat plates of one thickness, and `card3d.roundtrip.check` cuts it and checks every plate comes back.
+- `card3d.simulator` reports overhangs and where supports would leave marks, sweeps a peg into its socket to find collisions, finds the best print orientation, and with the `sim` extra decomposes a part into convex pieces and tests in MuJoCo whether the assembled model stands.
+- `card3d.labels` makes small 3D numbers for parts and cards.
+
+## Claude Code skill
+
+```bash
+3d-card skill             # copies it to ~/.claude/skills/3d-card
+```
+
+The skill gives Claude the whole procedure we used, in order. It starts with measuring clearances on your printer and goes through joints, building the card, reading its notes and the round trip, and checking the slice, up to the first physical print. It ends with a table of the failures we met (a card that printed as spaghetti, gates that cut a joint, parts that stayed on the frame) with how to check and fix each one.
+
+## Limits
+
+- It was built for one toy with about twenty parts. Cards with many more parts work, but the layout is a row packer, not an optimiser.
+- The round trip proves the gates can be cut in the model. Gate size still depends on your material and cutters, so print one card before printing many.
+- The clearances are from one printer and PLA.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test,sim]'
+.venv/bin/pytest
+python examples/make_example.py   # rebuilds docs/example.png
+```
+
+## License
+
+MIT

3d_card-0.1.0/pyproject.toml

@@ -0,0 +1,42 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "3d-card"
+version = "0.1.0"
+description = "Turn a set of 3D-printable parts into one printable card: parts gated to a frame like a model-kit sprue, with a check that every part comes off clean. Includes print-in-place joints and printability checks"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Konstantinos Georgiou" }]
+dependencies = [
+  "3d-base>=0.1.0",
+  "numpy>=1.24",
+  "trimesh>=4.0",
+  "manifold3d>=2.4",
+  "scipy>=1.10",
+  "shapely>=2.0",
+  "matplotlib>=3.7",
+  "build123d>=0.8",
+  "rtree>=1.0",
+  "networkx>=3.0",
+]
+keywords = ["3d-printing", "sprue", "kit card", "model kit", "joints", "print-in-place", "trimesh", "build123d"]
+classifiers = ["Programming Language :: Python :: 3", "Topic :: Multimedia :: Graphics :: 3D Modeling"]
+
+[project.urls]
+Homepage = "https://github.com/drkostas/3d-card"
+
+[project.scripts]
+3d-card = "card3d.cli:main"
+
+[project.optional-dependencies]
+sim = ["mujoco>=3.0", "coacd>=1.0"]
+test = ["pytest>=8"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+card3d = ["skill/SKILL.md"]

3d_card-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

3d_card-0.1.0/src/3d_card.egg-info/PKG-INFO

@@ -0,0 +1,127 @@
+Metadata-Version: 2.4
+Name: 3d-card
+Version: 0.1.0
+Summary: Turn a set of 3D-printable parts into one printable card: parts gated to a frame like a model-kit sprue, with a check that every part comes off clean. Includes print-in-place joints and printability checks
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/3d-card
+Keywords: 3d-printing,sprue,kit card,model kit,joints,print-in-place,trimesh,build123d
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: 3d-base>=0.1.0
+Requires-Dist: numpy>=1.24
+Requires-Dist: trimesh>=4.0
+Requires-Dist: manifold3d>=2.4
+Requires-Dist: scipy>=1.10
+Requires-Dist: shapely>=2.0
+Requires-Dist: matplotlib>=3.7
+Requires-Dist: build123d>=0.8
+Requires-Dist: rtree>=1.0
+Requires-Dist: networkx>=3.0
+Provides-Extra: sim
+Requires-Dist: mujoco>=3.0; extra == "sim"
+Requires-Dist: coacd>=1.0; extra == "sim"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# 3d-card
+
+3d-card turns a set of 3D-printable parts into one printable card, like the sprue of a plastic model kit. The parts sit on a flat frame, each held by small gates at the bottom, and you print the whole card in one go, cut the parts off and put them together. Before it gives you the card, it cuts every gate itself and checks that every part comes back whole and loose (the round trip).
+
+I wrote it for a posable toy figure I designed and printed, and I could not find a public tool that makes this kind of card. It also has the print-in-place joints and the printability checks I needed on the way.
+
+![A made-up kit of a block, a rod on a peg and two wheels, laid out on one card](docs/example.png)
+
+## Install
+
+```bash
+pip install 3d-card
+pip install "3d-card[sim]"     # adds the MuJoCo stand-up test and convex decomposition
+```
+
+In Python it is imported as `card3d`. It uses build123d (the CAD kernel), trimesh and manifold3d for the geometry, and [3d-base](https://github.com/drkostas/3d-base) for mesh loading and pictures.
+
+## Make a card
+
+You give it a function that returns your parts, the joints between them and a list of notes.
+
+```python
+import trimesh
+from card3d import tosprue
+
+def source():
+    parts = {"body": trimesh.load("body.stl"), "arm": trimesh.load("arm.stl"), "wheel": trimesh.load("wheel.stl")}
+    joints = []            # optional, see below
+    return parts, joints, []
+
+got, report = tosprue.best_card(source=source)
+print(got["size"], got["fits_bed"], report["ok"])
+got["card"].export("card.stl")
+```
+
+`best_card` tries a few layouts and keeps the smallest one whose round trip passes. `build` makes one card with the options you pass. `export(out="card", name="card.stl", ...)` builds and writes it.
+
+What it does, in order.
+
+1. Each part is turned so it rests on a face with enough first layer. A part with only a few square millimetres on the plate comes loose in the first layers and the nozzle drags it away.
+2. The parts are laid out in rows, with a runner bar under each row.
+3. Gates are placed at the bottom of each part, in the frame's own plane, where the part comes closest to its bar. A gate higher up would print in the air.
+4. Each part gets a small number stamped on the frame next to it.
+5. The card is made into one solid, the gates are cut, and every piece is matched back to its part by area and size.
+
+The card is as tall as its tallest part, and it is checked against your printer's bed (`bed=(width, depth)` in mm, or set `card3d.sprue.BED`).
+
+### A card you can read
+
+By default the parts go into one row after another. To make the card read like the finished model (head at the top, legs lower down, and so on), pass the rows yourself.
+
+```python
+tosprue.build(source=source,
+              rows=[["head"], ["arm_left", "body", "arm_right"], ["leg_left", "leg_right"]],
+              down=["arm_left", "arm_right", "leg_left", "leg_right"],   # long axis down the card
+              across=["head"])                                         # long axis across it
+```
+
+Parts you do not name go into a last row. Someone can then put the kit together without instructions.
+
+### Joints
+
+`card3d.joints` makes the two halves of a joint (`male` is what sticks out, `female` is what is cut away) for pegs, axles, pivots, ball joints, tabs and cross laps. The clearances were measured on a real printer with the two test prints in `card3d.coupons` (0.30 mm for push fits, 0.20 mm for a pivot that holds its pose). Print the coupons on your own printer and change `joints.CLEAR` and `joints.PIVOT_CLEAR` if yours differ.
+
+If you list your joints in the source as `{"type": "peg", "size": 3.0, "axis": (1, 0, 0), "at": (x, y, z), "child": "arm", "parent": "body"}`, the card keeps gates away from them and does not cut a part's sole through a peg.
+
+## Flat cards and checks
+
+- `card3d.sprue.make_card` makes the flat version, a kit card of flat plates of one thickness, and `card3d.roundtrip.check` cuts it and checks every plate comes back.
+- `card3d.simulator` reports overhangs and where supports would leave marks, sweeps a peg into its socket to find collisions, finds the best print orientation, and with the `sim` extra decomposes a part into convex pieces and tests in MuJoCo whether the assembled model stands.
+- `card3d.labels` makes small 3D numbers for parts and cards.
+
+## Claude Code skill
+
+```bash
+3d-card skill             # copies it to ~/.claude/skills/3d-card
+```
+
+The skill gives Claude the whole procedure we used, in order. It starts with measuring clearances on your printer and goes through joints, building the card, reading its notes and the round trip, and checking the slice, up to the first physical print. It ends with a table of the failures we met (a card that printed as spaghetti, gates that cut a joint, parts that stayed on the frame) with how to check and fix each one.
+
+## Limits
+
+- It was built for one toy with about twenty parts. Cards with many more parts work, but the layout is a row packer, not an optimiser.
+- The round trip proves the gates can be cut in the model. Gate size still depends on your material and cutters, so print one card before printing many.
+- The clearances are from one printer and PLA.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test,sim]'
+.venv/bin/pytest
+python examples/make_example.py   # rebuilds docs/example.png
+```
+
+## License
+
+MIT

3d_card-0.1.0/src/3d_card.egg-info/SOURCES.txt

@@ -0,0 +1,24 @@
+LICENSE
+README.md
+pyproject.toml
+src/3d_card.egg-info/PKG-INFO
+src/3d_card.egg-info/SOURCES.txt
+src/3d_card.egg-info/dependency_links.txt
+src/3d_card.egg-info/entry_points.txt
+src/3d_card.egg-info/requires.txt
+src/3d_card.egg-info/top_level.txt
+src/card3d/__init__.py
+src/card3d/cli.py
+src/card3d/joints.py
+src/card3d/labels.py
+src/card3d/roundtrip.py
+src/card3d/simulator.py
+src/card3d/sprue.py
+src/card3d/tosprue.py
+src/card3d/coupons/__init__.py
+src/card3d/coupons/ball_coupon.py
+src/card3d/coupons/fit_coupon.py
+src/card3d/skill/SKILL.md
+tests/test_card.py
+tests/test_cli.py
+tests/test_parts.py

3d_card-0.1.0/src/3d_card.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

3d_card-0.1.0/src/3d_card.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+3d-card = card3d.cli:main

3d_card-0.1.0/src/3d_card.egg-info/requires.txt

@@ -0,0 +1,17 @@
+3d-base>=0.1.0
+numpy>=1.24
+trimesh>=4.0
+manifold3d>=2.4
+scipy>=1.10
+shapely>=2.0
+matplotlib>=3.7
+build123d>=0.8
+rtree>=1.0
+networkx>=3.0
+
+[sim]
+mujoco>=3.0
+coacd>=1.0
+
+[test]
+pytest>=8

3d_card-0.1.0/src/3d_card.egg-info/top_level.txt

@@ -0,0 +1 @@
+card3d

3d_card-0.1.0/src/card3d/__init__.py

@@ -0,0 +1,2 @@
+"""Printable kit cards from 3D parts, with print-in-place joints and printability checks."""
+__version__ = "0.1.0"

3d_card-0.1.0/src/card3d/cli.py

@@ -0,0 +1,27 @@
+"""3d-card command line."""
+from __future__ import annotations
+
+import argparse
+import shutil
+import sys
+from pathlib import Path
+
+from . import __version__
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="3d-card", description="Printable kit cards from 3D parts.")
+    p.add_argument("--version", action="version", version=f"3d-card {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+    k = sub.add_parser("skill", help="install the Claude Code skill for making kit cards")
+    k.add_argument("--dir", default="~/.claude/skills")
+    a = p.parse_args(argv)
+    dest = Path(a.dir).expanduser() / "3d-card"
+    dest.mkdir(parents=True, exist_ok=True)
+    shutil.copyfile(Path(__file__).parent / "skill" / "SKILL.md", dest / "SKILL.md")
+    print(f"installed {dest / 'SKILL.md'}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

3d_card-0.1.0/src/card3d/coupons/ball_coupon.py

@@ -0,0 +1,110 @@
+"""Ball-joint coupon. Checks that a ball and socket assemble, hold, and turn, by measuring them.
+
+For each ball size the check builds the socket in a small block and the ball on a stem, using the
+joint geometry in card3d.joints, and measures four things.
+
+1. The socket is one solid with no sealed voids inside it.
+2. The socket rim is narrower than the ball, so something retains the ball.
+3. Pulling the ball out of the socket meets interference, so the ball does not fall out.
+4. The seated ball tilts at least 30 degrees in every direction without clashing.
+
+To use it, run `python -m card3d.coupons.ball_coupon`. It reports each size from 3 mm to 6 mm. Then
+print the joints at the sizes you need, push each ball into its socket by hand and test the twist.
+If a ball is too tight or falls out, adjust the clearance in card3d.joints and run the check again.
+
+The checks encode the following lessons.
+
+- A ball joint for a kit that is printed flat and assembled by hand needs a mouth the ball can be
+  pushed through. A cavity whose only opening is a stem bore narrower than the ball cannot be
+  assembled.
+- `trimesh.util.concatenate` merges face lists and does not perform a union. Cutters combined that
+  way remain overlapping shells, and subtracting them leaves walls where they cross. The socket can
+  then contain sealed voids and still report `is_watertight`. Check 1 catches this.
+- A cylindrical mouth through a full spherical cavity cannot retain anything. The cavity is the
+  ball plus clearance, so wherever the bore is narrower than the cavity it is also narrower than
+  the ball. Check 2 catches this.
+- Retention is not measured on the seated ball. A seated ball should not touch the rim, so zero
+  interference there is correct. The test pulls the ball out and measures what it has to pass on
+  the way, which is check 3.
+"""
+import numpy as np
+import trimesh
+
+from card3d import joints as J
+
+
+def socket_block(size, axis, at):
+    """Return a block standing in for the parent part, with just enough material to hold the cup."""
+    R = size / 2.0
+    c = J.ball_centre(size, axis, at)
+    blk = trimesh.creation.cylinder(radius=R + J.BALL_CLEAR + J.BALL_WALL,
+                                    height=(R + J.BALL_CLEAR) * 2 + J.BALL_WALL * 2)
+    blk.apply_translation(c)
+    return blk.difference(J.female("ball", size, axis, at))
+
+
+def check(size=5.0, verbose=True):
+    """Measure one ball size and return the results, with "ok" true when all four checks pass."""
+    axis, at = np.array([0.0, 0.0, 1.0]), np.zeros(3)
+    R = size / 2.0
+    c = float(J.ball_centre(size, axis, at)[2])
+    depth = J.ball_depth(size)
+    rim = float(np.sqrt((R + J.BALL_CLEAR) ** 2 - depth ** 2))
+
+    sock = socket_block(size, axis, at)
+    ball = J.male("ball", size, axis, at, backset=3.0)
+
+    pieces = sock.split(only_watertight=False)
+    solids = [p for p in pieces if p.volume > 0]
+    voids = [p for p in pieces if p.volume < 0]
+
+    # 1. the socket must be one solid with nothing sealed inside it
+    sound = len(solids) == 1 and not voids
+
+    # 2. the rim must be narrower than the ball, or nothing holds it in
+    grips = rim < R
+
+    # 3. the ball must resist being pulled out
+    peak = 0.0
+    for d in np.arange(0.0, R * 1.2, R * 0.12):
+        b = ball.copy()
+        b.apply_translation([0, 0, -float(d)])
+        peak = max(peak, abs(sock.intersection(b).volume))
+
+    # 4. seated, the ball must turn. Two rotational degrees of freedom are the purpose of a ball joint
+    swing = {}
+    for deg in (15, 30, 45):
+        worst = 0.0
+        for az in range(0, 360, 45):
+            T = (trimesh.transformations.rotation_matrix(np.radians(az), [0, 0, 1], [0, 0, c])
+                 @ trimesh.transformations.rotation_matrix(np.radians(deg), [1, 0, 0], [0, 0, c]))
+            b = ball.copy()
+            b.apply_transform(T)
+            worst = max(worst, abs(sock.intersection(b).volume))
+        swing[deg] = worst
+    free_to = max([d for d, v in swing.items() if v < 1.0], default=0)
+
+    if verbose:
+        print(f"  ball {size:.1f} mm, cup reaches {depth:.2f} mm past the equator")
+        print(f"    socket is one sound solid          {'yes' if sound else 'NO'}"
+              f"  ({len(solids)} solid, {len(voids)} sealed void)")
+        print(f"    rim {rim:.3f} vs ball radius {R:.2f}    "
+              f"{'grips by ' + format(R - rim, '.3f') + ' mm/side' if grips else 'DOES NOT GRIP'}")
+        print(f"    resists being pulled out           peak {peak:.3f} mm3"
+              f"  {'' if peak > 0.05 else '  <- FALLS OUT'}")
+        for d, v in swing.items():
+            print(f"    seated, tilted {d:2d} deg all round   clash {v:6.3f} mm3")
+        print(f"    turns freely to at least           {free_to} deg")
+    return {"sound": sound, "grips": grips, "retain_mm3": peak,
+            "free_deg": free_to, "rim": rim, "ball_r": R,
+            "ok": bool(sound and grips and peak > 0.05 and free_to >= 30)}
+
+
+if __name__ == "__main__":
+    print("ball and socket, as it would print and as it would be handled")
+    allok = True
+    for s in (3.0, 4.0, 5.0, 6.0):
+        r = check(s)
+        allok = allok and r["ok"]
+        print()
+    print("EVERY SIZE HOLDS AND TURNS" if allok else "SOME SIZE FAILS, see above")