3d-base 0.1.0__py3-none-any.whl

3d_base-0.1.0.dist-info/METADATA

@@ -0,0 +1,104 @@
+Metadata-Version: 2.4
+Name: 3d-base
+Version: 0.1.0
+Summary: Headless pictures of 3D meshes with correct occlusion and smooth shading, and a health check for exported STL files
+Author: Konstantinos Georgiou
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/drkostas/3d-base
+Keywords: 3d,mesh,stl,render,headless,trimesh,3d-printing,cad
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Multimedia :: Graphics :: 3D Rendering
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.22
+Requires-Dist: trimesh>=3.20
+Requires-Dist: scipy>=1.8
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Dynamic: license-file
+
+# 3d-base
+
+3d-base draws pictures of 3D meshes from Python with no display, no OpenGL and no browser. It needs numpy, trimesh and scipy. I use it to check models for 3D printing from a script, and to give an AI assistant pictures it can judge a design from.
+
+![Three views of a box, a ball and a rod that pass through each other](docs/example.png)
+
+It also loads exported STL files and reports what is really wrong with them, after removing the zero-area triangles that CAD exporters write.
+
+## Install
+
+```bash
+pip install 3d-base
+```
+
+In Python it is imported as `base3d`, because a Python name cannot start with a digit.
+
+## Use
+
+```bash
+3d-base render part.stl -o part.png                  # one view, from the front right
+3d-base render part.stl --view below -o below.png
+3d-base render part.stl --azim 30 --elev 20 -o x.png
+3d-base render part.stl --view sheet -o sheet.png    # six views in a grid
+3d-base check part.stl                               # faces, bodies, closed cavities, volume
+```
+
+`3d-base check` exits with 1 when the file has a closed cavity, so it can stop a script before a print.
+
+From Python:
+
+```python
+import trimesh
+from base3d import frame_on, render, save_png, sheet
+
+mesh = trimesh.load("part.stl")
+eye, target = frame_on(mesh, azim=-45, elev=25)
+save_png(render(mesh, eye, target, size=(1400, 1000)), "part.png")
+save_png(sheet(mesh, views=("front", "top", "below")), "views.png")
+```
+
+`render` takes `face_colors` (one RGB colour per face, values from 0 to 1), so parts can have their own colours. It returns an RGB array, so the picture can also go to Pillow, matplotlib or anything else.
+
+## Why not matplotlib
+
+Matplotlib's 3D axes sort whole triangles from back to front and then draw them. When parts overlap or pass through each other, triangles come out in the wrong order, and a correct model looks broken. 3d-base keeps a depth value for every pixel, so the nearest surface always wins.
+
+## Shading
+
+A few choices came from looking at real pictures and finding them misleading.
+
+- The light comes partly from the camera (`HEADLIGHT`). With only a fixed lamp, a view from below or from behind came out close to black (about a fifth of full brightness), and those views are often the ones you need.
+- Curved surfaces are shaded smoothly, and real edges stay sharp. With one normal per triangle, a sphere looks like a quilt of flat facets even when the mesh is within a few microns of a true sphere, which reads as a defect that is not in the model. Normals are averaged only over neighbouring faces within 32 degrees (`CREASE_DEG`), so box corners and cut edges keep their own normal.
+- The average for a corner is taken over faces close to that face's own direction, not over all faces at the vertex. The simpler version bends the normals at the rim of a cut toward the cut's walls and draws a bright spike that is not there. `corner_normals(mesh, naive=True)` returns the simpler version, so you can see the difference.
+- Colour is flat per face and only the light changes across a triangle, so a colour boundary in the picture is a face boundary in the mesh.
+
+`display_mesh(mesh)` returns the mesh with these same normals stored on its vertices. A GLB exported by trimesh carries no normals, so a web viewer such as three.js shows it unlit with smooth shading on. Exporting `display_mesh(mesh)` instead makes the viewer and the pictures agree.
+
+## Checking an exported STL
+
+OpenCascade (and tools built on it, such as build123d and CadQuery) writes zero-area triangles at every sphere pole. A plain sphere then reports `is_watertight=False` and two or three extra bodies. `load_clean` removes them, and after that a second body is real. A body with negative volume is a closed cavity inside the part (a socket that never reached the surface, for example).
+
+```python
+from base3d import load_clean, voids
+mesh, bodies = load_clean("part.stl")
+assert not voids(bodies)
+```
+
+`surface_points(mesh, n)` samples points on the surface with a fixed seed, so a step that places things from those points gives the same answer on every run.
+
+## Speed
+
+It is plain numpy with a loop over triangles. A part with 225,721 faces renders at 700 by 500 in 6 to 9 seconds on an M1 Max, and a part with 40,960 faces in about 1.5 seconds. For an interactive viewer use something else. For pictures in a script, a test or a report it is fast enough.
+
+## Development
+
+```bash
+python -m venv .venv && .venv/bin/pip install -e '.[test]'
+.venv/bin/pytest
+python examples/make_example.py   # rebuilds docs/example.png
+```
+
+## License
+
+MIT

3d_base-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+3d_base-0.1.0.dist-info/licenses/LICENSE,sha256=y2yT4XOJ5hjMzENqKJShtqLiwI-IE1PnWqMxbhhL5r8,1078
+base3d/__init__.py,sha256=g5MR_ocOXbM7Frob0y8-kjewb_nYHk5_jWsMjR2vX5s,343
+base3d/cli.py,sha256=h98eA_e8YZrL_1wpUCwg1Ep5KWUhAoTDbAoWl6L6MrI,1691
+base3d/mesh.py,sha256=44DZAKxlppiuDwUyX8zfuqX9P3Jo4nloEqVwWeJpPpA,3384
+base3d/show.py,sha256=7uw2Ev5UnRnKOuuke3C-l5h7TEAyGFldtBBKQ1DOT-Q,13679
+3d_base-0.1.0.dist-info/METADATA,sha256=yMTdKUzubV7M4f0OD92nNKPGeCIE4uXVSxUnT3HfESE,5271
+3d_base-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+3d_base-0.1.0.dist-info/entry_points.txt,sha256=5i_ZaQnITWllqzRW-Ka9UwJBT_awnhNI8LL_typmkvQ,44
+3d_base-0.1.0.dist-info/top_level.txt,sha256=TY3ZUX-6EPMJ-grHwU5WEgKJMBECahoPRphxcxZs8V4,7
+3d_base-0.1.0.dist-info/RECORD,,

3d_base-0.1.0.dist-info/WHEEL

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

3d_base-0.1.0.dist-info/entry_points.txt

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

3d_base-0.1.0.dist-info/licenses/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_base-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+base3d

base3d/__init__.py

@@ -0,0 +1,6 @@
+"""Headless pictures of 3D meshes, and an honest health check for exported STL files."""
+from .mesh import load_clean, report, surface_points, voids
+from .show import frame_on, render, save_png, sheet, tile
+
+__version__ = "0.1.0"
+__all__ = ["frame_on", "load_clean", "render", "report", "save_png", "sheet", "surface_points", "tile", "voids"]

base3d/cli.py

@@ -0,0 +1,48 @@
+"""3d-base command line."""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from . import __version__
+from .mesh import load_clean, report
+from .show import SHEET_BG, VIEWS, frame_on, render, save_png, sheet
+
+
+def main(argv=None) -> int:
+    p = argparse.ArgumentParser(prog="3d-base", description="Pictures of a 3D mesh, and a health check.")
+    p.add_argument("--version", action="version", version=f"3d-base {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    r = sub.add_parser("render", help="render one view, or a sheet of views, to PNG")
+    r.add_argument("mesh")
+    r.add_argument("-o", "--out", default="render.png")
+    r.add_argument("--view", default="front-right", help=f"one of {', '.join(VIEWS)}, or 'sheet'")
+    r.add_argument("--azim", type=float)
+    r.add_argument("--elev", type=float)
+    r.add_argument("--size", default="1400x1000")
+
+    c = sub.add_parser("check", help="faces, bodies, closed cavities and volume, after dropping slivers")
+    c.add_argument("mesh")
+
+    a = p.parse_args(argv)
+    if a.cmd == "check":
+        rep = report(a.mesh)
+        print(json.dumps(rep, indent=1))
+        return 1 if rep["voids"] else 0
+    m, _ = load_clean(a.mesh)
+    w, h = (int(x) for x in a.size.lower().split("x"))
+    if a.view == "sheet":
+        img = sheet(m, size=(w // 2, h // 2))
+    else:
+        azim, elev = (a.azim, a.elev) if a.azim is not None and a.elev is not None else VIEWS[a.view]
+        eye, target = frame_on(m, azim, elev)
+        img = render(m, eye, target, size=(w, h), bg=SHEET_BG)
+    save_png(img, a.out)
+    print(a.out)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

base3d/mesh.py

@@ -0,0 +1,87 @@
+"""Load an exported STL and tell real defects from tessellation noise.
+
+OpenCascade (and CAD tools built on it, such as build123d and CadQuery) writes zero-area triangles at
+every sphere pole when it exports STL. They make a correct solid report `is_watertight=False` with
+two or three extra bodies, so a plain `Sphere(20)` already looks broken. The slivers are an
+artefact of the tessellation and it is correct to drop them.
+
+Dropping them is also what makes the body count useful. Once the slivers are gone, a second body is
+real. A shell with negative volume is a sealed cavity (a socket that never reached the surface, for
+example), and that is a design defect worth catching before printing.
+"""
+from __future__ import annotations
+
+import numpy as np
+import trimesh
+
+SLIVER_AREA = 1e-9
+
+# Any fixed value. What matters is that it does not change between runs.
+SAMPLE_SEED = 11
+
+
+def clean(mesh: trimesh.Trimesh, sliver_area: float = SLIVER_AREA) -> trimesh.Trimesh:
+    """Drop zero-area faces and merge the vertices they leave behind. Changes the mesh in place."""
+    areas = mesh.area_faces
+    if (areas <= sliver_area).any():
+        mesh.update_faces(areas > sliver_area)
+        mesh.remove_unreferenced_vertices()
+        mesh.merge_vertices()
+    return mesh
+
+
+def load_clean(path):
+    """Load a mesh file, drop tessellation slivers, and return (mesh, bodies).
+
+    `bodies` is the list of connected pieces. After cleaning, more than one means more than one
+    real piece.
+    """
+    m = trimesh.load(str(path))
+    if isinstance(m, trimesh.Scene):  # a GLB or OBJ with several parts
+        m = m.to_geometry() if hasattr(m, "to_geometry") else m.dump(concatenate=True)
+    clean(m)
+    bodies = m.split(only_watertight=False)
+    return m, bodies
+
+
+def voids(bodies):
+    """Pieces with negative volume, which are closed cavities inside another piece."""
+    return [b for b in bodies if b.volume < 0]
+
+
+def surface_points(mesh, n=4000, seed=SAMPLE_SEED):
+    """Points on the surface of a mesh, the same points on every run.
+
+    An unseeded sample makes a design change between two builds of the same input whenever the
+    points decide something (where a support or a contact goes, for example).
+    """
+    rng = np.random.default_rng(seed)
+    try:
+        return mesh.sample(n, seed=rng)
+    except TypeError:
+        # Older trimesh has no seed argument. Sampling without one would break the promise above,
+        # so sample here: pick faces by area, then a uniform point inside each.
+        return _seeded_sample(mesh, n, rng)
+
+
+def _seeded_sample(mesh, n, rng):
+    cum = np.cumsum(np.asarray(mesh.area_faces, float))
+    face = np.searchsorted(cum, rng.random(n) * cum[-1])
+    tri = np.asarray(mesh.triangles, float)[face]
+    r = rng.random((n, 2))
+    over = r.sum(axis=1) > 1
+    r[over] = 1 - r[over]                       # fold the square onto the triangle
+    return tri[:, 0] + r[:, :1] * (tri[:, 1] - tri[:, 0]) + r[:, 1:] * (tri[:, 2] - tri[:, 0])
+
+
+def report(path) -> dict:
+    """A short health report for a mesh file."""
+    m, bodies = load_clean(path)
+    return {
+        "faces": int(len(m.faces)),
+        "bodies": len(bodies),
+        "voids": len(voids(bodies)),
+        "watertight": bool(m.is_watertight),
+        "volume": float(m.volume) if m.is_watertight else None,
+        "extents": [float(x) for x in m.extents],
+    }

base3d/show.py

@@ -0,0 +1,294 @@
+"""A small software renderer for judging a 3D model from pictures, with numpy and nothing else.
+
+Matplotlib's 3D axes sort whole polygons from back to front and then draw them, so faces that
+overlap or pass through each other come out in the wrong order. A limb shows through a body, and a
+model that is correct looks broken. A depth buffer decides for each pixel, which is the only way to
+get that right.
+
+The picture is the mesh itself, shaded by its own normals. Nothing is smoothed or simplified for
+the picture, so if a part looks wrong here, the part is wrong (with one exception, the shading of
+smooth surfaces, described at CREASE_DEG).
+"""
+from __future__ import annotations
+
+import struct
+import zlib
+
+import numpy as np
+import trimesh
+
+# How much of the light comes from the camera. This term keeps every view readable: a face you can
+# see is a face that faces the camera, so it always receives some light. Without it, views from
+# below and from behind come out close to black with a fixed key light.
+HEADLIGHT = 0.60
+
+# Smooth shading with real edges kept sharp.
+#
+# Shading with one normal per triangle makes every sphere look like a quilt of flat facets, even
+# when the mesh is within a few microns of a true sphere (much less than one pixel, and much less
+# than one printed layer). That reads as a modelling defect that does not exist. So the normal is
+# interpolated across each triangle from its corners, but only where the surface is really smooth.
+# A neighbouring face that turns more than CREASE_DEG away is on the other side of a real edge and
+# is left out of the average, so box corners, cuts and seams stay crisp.
+CREASE_DEG = 32.0
+
+
+def look_at(eye, target, up=(0.0, 0.0, 1.0)):
+    """A 4x4 view matrix for a camera at `eye` looking at `target`."""
+    eye, target = np.asarray(eye, float), np.asarray(target, float)
+    f = target - eye
+    f /= np.linalg.norm(f)
+    u = np.asarray(up, float)
+    s = np.cross(f, u)
+    if np.linalg.norm(s) < 1e-9:  # looking straight along `up`
+        s = np.cross(f, [0.0, 1.0, 0.0])
+    s /= np.linalg.norm(s)
+    u = np.cross(s, f)
+    M = np.eye(4)
+    M[0, :3], M[1, :3], M[2, :3] = s, u, -f
+    M[:3, 3] = -M[:3, :3] @ eye
+    return M
+
+
+def display_mesh(mesh, crease_deg=None):
+    """The same mesh with per-vertex normals baked in, for viewers that shade from stored normals.
+
+    A GLB exported by trimesh carries positions and colours but no normals, and a web viewer such as
+    three.js then renders it unlit when smooth shading is on. These are the same crease-aware
+    normals this renderer uses, so the viewer and the pictures agree. Vertices are split per corner
+    and then merged back where both position and normal agree, so only real edges duplicate.
+    """
+    deg = CREASE_DEG if crease_deg is None else float(crease_deg)
+    F = np.asarray(mesh.faces)
+    cn = corner_normals(mesh, deg).reshape(-1, 3)
+    V = np.asarray(mesh.vertices, float)[F].reshape(-1, 3)
+    key = np.hstack([np.round(V, 5), np.round(cn, 4)])
+    _, first, inverse = np.unique(key, axis=0, return_index=True, return_inverse=True)
+    out = trimesh.Trimesh(V[first], inverse.reshape(-1, 3), process=False)
+    out.vertex_normals = cn[first]
+    return out
+
+
+def corner_normals(mesh, crease_deg=CREASE_DEG, naive=False):
+    """A normal for each corner of each face, shape (faces, 3, 3).
+
+    For each corner, the normals of the faces at that vertex are averaged (weighted by area), but
+    only those within `crease_deg` of THIS face. Comparing each face to the plain average of all
+    faces at the vertex looks similar and is wrong at the rim of a cut, because there the average is
+    pulled toward the cut's walls. A rim triangle is then smoothed as if it faced the light and
+    shows as a bright spike that is not in the model.
+
+    `naive=True` returns that wrong version. It is kept so a test can show the difference.
+
+    The result is cached on the mesh, keyed by the angle and by the mesh's hash. The hash changes
+    when the mesh is moved or rotated, so a transformed mesh is never shaded with stale normals.
+    """
+    if naive:
+        n0 = np.asarray(mesh.face_normals, float)
+        F0 = np.asarray(mesh.faces)
+        vn = np.asarray(mesh.vertex_normals, float)[F0]
+        fn3 = np.repeat(n0[:, None, :], 3, axis=1)
+        dot = np.clip((vn * fn3).sum(axis=2), -1.0, 1.0)
+        cn0 = np.where((dot < np.cos(np.radians(crease_deg)))[..., None], fn3, vn)
+        ln0 = np.linalg.norm(cn0, axis=2, keepdims=True)
+        return cn0 / np.where(ln0 < 1e-9, 1.0, ln0)
+    key = "_base3d_corner_normals"
+    ck = (round(float(crease_deg), 1), hash(mesh))
+    got = getattr(mesh, key, None)
+    if got is not None and got[0] == ck:
+        return got[1]
+    n = np.asarray(mesh.face_normals, float)
+    F = np.asarray(mesh.faces)
+    try:
+        # Which faces touch each vertex. trimesh's `vertex_faces` raises on meshes with degenerate
+        # faces, so it is built here directly: sort the (vertex, face) pairs by vertex and put each
+        # vertex's faces in its own row, padded with -1.
+        F_flat = F.ravel()
+        f_of = np.repeat(np.arange(len(F)), 3)
+        order = np.argsort(F_flat, kind="stable")
+        vs, fs = F_flat[order], f_of[order]
+        V = int(F.max()) + 1
+        counts = np.bincount(vs, minlength=V)
+        start = np.concatenate([[0], np.cumsum(counts)[:-1]])
+        vf = np.full((V, int(counts.max())), -1, dtype=np.int64)
+        vf[vs, np.arange(len(vs)) - start[vs]] = fs
+        area = np.asarray(mesh.area_faces, float)
+        cosc = np.cos(np.radians(crease_deg))
+        cn = np.empty((len(F), 3, 3), float)
+        # In blocks of faces, so memory stays bounded on large meshes (the full neighbour array for
+        # a few hundred thousand faces is several gigabytes).
+        step = max(1, int(4_000_000 // max(vf.shape[1] * 3, 1)))
+        for a in range(0, len(F), step):
+            b = min(a + step, len(F))
+            nb = vf[F[a:b]]                             # (B, 3, max valence)
+            valid = nb >= 0
+            nbi = np.where(valid, nb, 0)
+            nbn = n[nbi]                                # (B, 3, max valence, 3)
+            d = np.einsum("fkmc,fc->fkm", nbn, n[a:b])
+            w = area[nbi] * (valid & (d >= cosc))
+            acc = np.einsum("fkmc,fkm->fkc", nbn, w)
+            ln = np.linalg.norm(acc, axis=2, keepdims=True)
+            flat = ln < 1e-9
+            cn[a:b] = np.where(flat, np.repeat(n[a:b, None, :], 3, axis=1),
+                               acc / np.where(flat, 1.0, ln))
+    except Exception as e:  # noqa: BLE001
+        # Say so. A silent fallback to flat shading would look like a faceted model.
+        print(f"3d-base: smooth normals failed ({type(e).__name__}: {e}), this mesh is shaded flat")
+        cn = np.repeat(n[:, None, :], 3, axis=1)
+    try:
+        setattr(mesh, key, (ck, cn))
+    except Exception:  # noqa: BLE001
+        pass
+    return cn
+
+
+def render(mesh, eye, target, size=(1400, 1000), fov=26.0, up=(0, 0, 1),
+           light=(0.4, -0.7, 0.75), base=(0.94, 0.94, 0.91), bg=(1.0, 1.0, 1.0),
+           face_colors=None, ao=0.35, headlight=None, naive_normals=False):
+    """Render one mesh with a depth buffer and return an RGB image (H, W, 3) of uint8.
+
+    The light is a fixed key light, a soft light from the sky (+Z), and a headlight from the
+    camera. The key light gives the shapes their form. The headlight keeps faces turned away from
+    the key light readable, which matters for views from below and from behind. Measured without
+    it, the model pixels in a view from below averaged about a fifth of full brightness.
+
+    `face_colors` is an (F, 3) array of RGB values from 0 to 1, one colour per face. `headlight`
+    overrides HEADLIGHT for this call. `ao` is accepted for compatibility and not used.
+    """
+    W, H = size
+    V = np.asarray(mesh.vertices, float)
+    F = np.asarray(mesh.faces)
+    M = look_at(eye, target, up)
+    cam = (M @ np.c_[V, np.ones(len(V))].T).T[:, :3]
+
+    f = 1.0 / np.tan(np.radians(fov) / 2.0)
+    z = -cam[:, 2]
+    z = np.where(z < 1e-6, 1e-6, z)
+    sx = (cam[:, 0] * f / z) * (H / 2) + W / 2
+    sy = (-cam[:, 1] * f / z) * (H / 2) + H / 2
+    P = np.column_stack([sx, sy, z])
+
+    n = np.asarray(mesh.face_normals, float)
+    cn = corner_normals(mesh, CREASE_DEG, naive=naive_normals)
+    L = np.asarray(light, float)
+    L /= np.linalg.norm(L)
+    lam = np.clip(cn @ L, 0, 1)
+    sky = np.clip(cn[:, :, 2] * 0.5 + 0.5, 0, 1)
+    # Read at call time, not as a default argument, so changing render.HEADLIGHT takes effect.
+    k = HEADLIGHT if headlight is None else float(headlight)
+    view = np.asarray(eye, float) - np.asarray(target, float)
+    vn = float(np.linalg.norm(view))
+    head = np.clip(cn @ (view / vn), 0, 1) if vn > 1e-9 else np.zeros((len(n), 3))
+    shade = np.clip(0.14 + 0.46 * lam + 0.22 * sky + k * head, 0, 1.25)   # (F, 3), per corner
+    if face_colors is None:
+        col = np.tile(np.asarray(base, float), (len(F), 1))
+    else:
+        col = np.asarray(face_colors, float)
+    col = np.clip(col, 0, 1)                    # colour is flat per face, only the light varies
+
+    img = np.tile(np.asarray(bg, float), (H, W, 1))
+    depth = np.full((H, W), np.inf)
+
+    tri = P[F]
+    a, b, c = tri[:, 0], tri[:, 1], tri[:, 2]
+    area2 = (b[:, 0] - a[:, 0]) * (c[:, 1] - a[:, 1]) - (c[:, 0] - a[:, 0]) * (b[:, 1] - a[:, 1])
+    keep = np.abs(area2) > 1e-9                 # skip faces seen exactly edge-on
+    tri, col, area2, shade = tri[keep], col[keep], area2[keep], shade[keep]
+
+    order = np.argsort(-tri[:, :, 2].min(axis=1))       # far to near
+    for i in order:
+        t, cc, sh = tri[i], col[i], shade[i]
+        x0 = max(int(np.floor(t[:, 0].min())), 0)
+        x1 = min(int(np.ceil(t[:, 0].max())) + 1, W)
+        y0 = max(int(np.floor(t[:, 1].min())), 0)
+        y1 = min(int(np.ceil(t[:, 1].max())) + 1, H)
+        if x1 <= x0 or y1 <= y0:
+            continue
+        xs = np.arange(x0, x1) + 0.5
+        ys = np.arange(y0, y1) + 0.5
+        gx, gy = np.meshgrid(xs, ys)
+        d = area2[i]
+        w0 = ((t[1, 0] - t[0, 0]) * (gy - t[0, 1]) - (gx - t[0, 0]) * (t[1, 1] - t[0, 1])) / d
+        w1 = ((gx - t[0, 0]) * (t[2, 1] - t[0, 1]) - (t[2, 0] - t[0, 0]) * (gy - t[0, 1])) / d
+        inside = (w0 >= -1e-9) & (w1 >= -1e-9) & (w0 + w1 <= 1 + 1e-9)
+        if not inside.any():
+            continue
+        zz = t[0, 2] + w1 * (t[1, 2] - t[0, 2]) + w0 * (t[2, 2] - t[0, 2])
+        sub = depth[y0:y1, x0:x1]
+        hit = inside & (zz < sub)
+        if not hit.any():
+            continue
+        sub[hit] = zz[hit]
+        # the same barycentric weights as the depth, so the light varies across the triangle
+        ss = sh[0] + w1 * (sh[1] - sh[0]) + w0 * (sh[2] - sh[0])
+        img[y0:y1, x0:x1][hit] = np.clip(cc[None, :] * ss[hit][:, None], 0, 1)
+    return (np.clip(img, 0, 1) * 255).astype(np.uint8)
+
+
+def frame_on(mesh, azim, elev, pad=1.22):
+    """(eye, target) that puts the whole mesh in frame from a direction in degrees.
+
+    `azim` turns around +Z starting from +X, and `elev` is the angle above the XY plane.
+    """
+    c = mesh.bounds.mean(axis=0)
+    r = float(np.linalg.norm(mesh.bounds[1] - mesh.bounds[0])) / 2.0
+    a, e = np.radians(azim), np.radians(elev)
+    d = np.array([np.cos(e) * np.cos(a), np.cos(e) * np.sin(a), np.sin(e)])
+    return c + d * r * 3.4 * pad, c
+
+
+def tile(images, cols=None, gap=16, bg=255, titles=None, title_h=0):
+    """Lay out images of equal size in a grid. `bg` is one grey value or an RGB tuple, and `title_h` leaves that many pixels above each one."""
+    cols = cols or len(images)
+    rows = int(np.ceil(len(images) / cols))
+    h, w = images[0].shape[:2]
+    out = np.full((rows * (h + title_h) + (rows + 1) * gap,
+                   cols * w + (cols + 1) * gap, 3), bg, np.uint8)
+    for i, im in enumerate(images):
+        r, c = divmod(i, cols)
+        y = gap + r * (h + title_h + gap) + title_h
+        x = gap + c * (w + gap)
+        out[y:y + h, x:x + w] = im
+    return out
+
+
+VIEWS = {
+    "front": (-90, 10), "back": (90, 10), "left": (180, 10), "right": (0, 10),
+    "top": (-90, 89), "below": (-90, -60), "front-right": (-45, 25), "back-left": (135, 25),
+}
+
+
+SHEET_BG = (0.83, 0.85, 0.88)
+
+
+def sheet(mesh, views=("front", "right", "back", "left", "top", "below"), size=(600, 450), cols=3, **kw):
+    """Render the mesh from several named views (see VIEWS) and lay them out in a grid.
+
+    The background is a light grey (SHEET_BG) unless `bg` is given, because the brightest faces of a
+    light model are drawn close to white and would disappear against a white background.
+    """
+    kw.setdefault("bg", SHEET_BG)
+    imgs = []
+    for v in views:
+        azim, elev = VIEWS[v] if isinstance(v, str) else v
+        eye, target = frame_on(mesh, azim, elev)
+        imgs.append(render(mesh, eye, target, size=size, **kw))
+    return tile(imgs, cols=cols, bg=tuple(int(255 * c) for c in kw["bg"]))
+
+
+def save_png(img, path):
+    """Write an (H, W, 3) uint8 image as PNG with the standard library only."""
+    img = np.ascontiguousarray(img, dtype=np.uint8)
+    h, w = img.shape[:2]
+    raw = b"".join(b"\x00" + img[y].tobytes() for y in range(h))
+
+    def chunk(kind, data):
+        return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)
+    png = (b"\x89PNG\r\n\x1a\n" + chunk(b"IHDR", struct.pack(">IIBBBBB", w, h, 8, 2, 0, 0, 0))
+           + chunk(b"IDAT", zlib.compress(raw, 6)) + chunk(b"IEND", b""))
+    with open(path, "wb") as f:
+        f.write(png)
+
+
+# The name used before this was a package.
+_corner_normals = corner_normals