pycodecad 1.0.0__py3-none-any.whl

pycodecad/__init__.py

@@ -0,0 +1,18 @@
+"""Code-CAD with build123d: write a Python script, see the part, export it."""
+from typing import TYPE_CHECKING
+
+__version__ = "1.0.0"
+
+__all__ = ["show", "clear", "frame", "import_mesh", "expose"]
+
+if TYPE_CHECKING:
+    from .api import clear, expose, frame, import_mesh, show
+
+
+def __getattr__(name: str):
+    # Lazy, so `import pycodecad` (and the CLI) start instantly.
+    if name in __all__:
+        from . import api
+
+        return getattr(api, name)
+    raise AttributeError(name)

pycodecad/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

pycodecad/api.py

@@ -0,0 +1,105 @@
+"""The modeling API: show(), clear(), frame(), import_mesh() and expose().
+
+While pycodecad runs a script, `scene` is the list that show() fills, `frames` the scenes frame()
+saved and `values` the parameter values of exposed functions. Outside pycodecad (plain
+`python script.py`) scene is None: show()/clear()/frame() do nothing and expose() calls the
+function with its defaults, so scripts still run.
+"""
+from __future__ import annotations
+
+from dataclasses import replace
+
+from .cad import Mesh, Shown, copy_shape, flatten, import_mesh, parse_color, placed
+
+__all__ = ["show", "clear", "frame", "import_mesh", "expose"]
+
+scene: list[Shown] | None = None
+frames: list[list[Shown]] = []
+FPS = 30                         # frames per second of the animation
+values: dict[str, object] = {}   # "function.param" or "param" -> value, set by the runner
+used: set[str] = set()           # keys of `values` some expose() took
+exposed: list = []               # params.Exposed, in call order
+strict = True                    # False (the window): values the parameter no longer accepts are skipped
+
+
+def show(*objs: object, name: str | None = None, color: object = None) -> None:
+    """Add build123d shapes, builders or meshes (or lists of them) to the scene.
+
+    name: label of the object (numbered when several objects are passed).
+    color: "#RRGGBB", a basic name like "red", or an RGB triple (0..1 or 0..255).
+    """
+    if scene is None:
+        return
+    if name is not None and not isinstance(name, str):
+        raise TypeError(f"show() name must be a string, not {type(name).__name__}")
+    shapes = flatten(list(objs))
+    for number, shape in enumerate(shapes, start=1):
+        index = len(scene)
+        if name is None:
+            label = f"{type(shape).__name__} {index + 1}"
+        else:
+            label = name if len(shapes) == 1 else f"{name}_{number}"
+        mesh, matrix, volume = placed(shape)
+        source = shape if isinstance(shape, Mesh) else copy_shape(shape)  # later moves: not this placement
+        scene.append(Shown(label, parse_color(color, index), mesh, volume, source, matrix))
+
+
+def clear() -> None:
+    """Remove everything shown so far."""
+    if scene is not None:
+        scene.clear()
+
+
+def frame() -> None:
+    """Save the scene as it is now as the next frame of an animation (1/30 s each). The window plays
+    the frames; without any frame() the scene is a still one. The scene stays: clear() it yourself."""
+    if scene is not None:
+        frames.append([Shown(obj.name, obj.color, obj.mesh, obj.volume, None, obj.matrix) for obj in scene])
+
+
+def expose(fn):
+    """Call fn with the values of its parameters: from the window's controls (or `--set` on
+    the command line), otherwise its defaults. Returns what fn returns.
+
+    Only simple parameters: int, float, bool or str with a default, annotated with pytypehint
+    Min, Max, Step, Slider, Label and Description. Anything else raises TypeError.
+    """
+    from . import params
+
+    signature, found = params.compile_function(fn)
+    name = fn.__name__
+    if scene is not None and any(e.function == name for e in exposed):
+        raise ValueError(f"expose({name}) was already called in this run")
+    chosen = {}
+    try:
+        for param in found:
+            keys = [key for key in (f"{name}.{param.name}", param.name) if key in values]
+            if keys:  # "function.param" wins over "param"; both count as taken
+                used.update(keys)
+                if strict:
+                    chosen[param.name] = params.convert(param, values[keys[0]])
+                elif (value := accepted(signature, param, values[keys[0]])) is not None:
+                    chosen[param.name] = value  # else the edited script no longer accepts it: default
+        kwargs = signature.build(chosen)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"expose({name}): {params.name_parameter(fn, str(exc))}") from None
+    if scene is not None:  # plain python: nothing to show the parameters to
+        ran = []
+        for param in found:
+            try:
+                ran.append(replace(param, value=kwargs[param.name]))
+            except ValueError as exc:  # e.g. --set beyond what the window's controls handle
+                raise ValueError(f"expose({name}): parameter {param.name!r}: {exc}") from None
+        exposed.append(params.Exposed(function=name, params=tuple(ran)))
+    return fn(**kwargs)
+
+
+def accepted(signature, param, value: object) -> object | None:
+    """The value for param, or None when param does not accept it (any more)."""
+    if type(value) is not {"int": int, "float": float, "bool": bool, "str": str}[param.kind]:
+        return None  # the window sends values of the kind the parameter had: another kind is stale
+    try:
+        signature.build({param.name: value})
+    except (TypeError, ValueError):
+        return None
+    return value

pycodecad/app.py

@@ -0,0 +1,34 @@
+"""The pycodecad window (`pycodecad file.py` or `pycodecad folder/`): one Workspace filling a Window."""
+from __future__ import annotations
+
+from slimgui import imgui
+
+from . import __version__
+from .window import create_window
+from .workspace import Workspace
+
+
+def open_window(path: str, screenshot: str | None = None, read_only: bool = False, run: bool = True) -> None:
+    """Work on a folder until the window closes. path: its main file, or the folder. screenshot: a
+    hidden window that saves a PNG of itself after the first run, then closes."""
+    workspace = Workspace(path, read_only=read_only, run=run or screenshot is not None)
+    window = create_window(workspace.title(), visible=screenshot is None)
+    workspace.say(f"pycodecad {__version__}")
+    try:
+        while window.frame(keep_open=workspace.dirty() and not screenshot):
+            window.set_title(workspace.title())
+            viewport = imgui.get_main_viewport()
+            imgui.set_next_window_pos(viewport.work_pos)
+            imgui.set_next_window_size(viewport.work_size)
+            imgui.push_style_var(imgui.StyleVar.WINDOW_PADDING, (6.0, 6.0))
+            imgui.begin("pycodecad", flags=imgui.WindowFlags.NO_DECORATION | imgui.WindowFlags.NO_MOVE
+                        | imgui.WindowFlags.NO_SAVED_SETTINGS | imgui.WindowFlags.NO_BRING_TO_FRONT_ON_FOCUS)
+            imgui.pop_style_var()
+            workspace.draw()
+            workspace.close_prompt(window)
+            imgui.end()
+            if screenshot and workspace.ran() and not workspace.running():
+                window.screenshot(screenshot)
+                window.request_close()
+    finally:
+        window.close()

pycodecad/cad.py

@@ -0,0 +1,261 @@
+"""CAD objects to triangles: the Mesh type, colors, tessellation and import_mesh.
+
+Importing this module is cheap: build123d/OCP are imported inside the functions that need them.
+"""
+from __future__ import annotations
+
+import os
+import shutil
+import tempfile
+import time
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Iterable
+
+import numpy as np
+
+if TYPE_CHECKING:
+    from build123d.topology import Shape
+
+Vec = tuple[float, float, float]
+Color = tuple[float, float, float]
+Matrix = tuple[float, ...]  # 4x4, row by row: where a mesh in its own coordinates is placed
+# import_mesh(solid=True) needs a temporary STL; it goes here, not to /tmp (often RAM).
+TEMP = Path(os.environ.get("XDG_CACHE_HOME") or Path.home() / ".cache") / "pycodecad" / "tmp"
+
+PALETTE = ("#F4B02A", "#6947AE", "#48B5A4", "#5898DA", "#E87769", "#AAC86A")
+NAMED_COLORS = dict(red="#FF0000", green="#008000", blue="#0000FF", gold="#FFD700", violet="#EE82EE",
+                    purple="#800080", white="#FFFFFF", black="#000000", gray="#808080", grey="#808080",
+                    orange="#FFA500", yellow="#FFFF00", cyan="#00FFFF", magenta="#FF00FF")
+
+
+@dataclass(frozen=True)
+class Mesh:
+    """Triangles (positions/normals, 3 rows per triangle) and edge segments (2 rows per segment)."""
+
+    positions: np.ndarray
+    normals: np.ndarray
+    edges: np.ndarray
+
+    def __post_init__(self) -> None:
+        for name in ("positions", "normals", "edges"):
+            array = np.array(getattr(self, name), dtype=np.float32).reshape(-1, 3)
+            if not np.isfinite(array).all():
+                raise ValueError(f"Mesh {name} must be finite")
+            object.__setattr__(self, name, array)
+        if self.positions.shape != self.normals.shape or len(self.positions) % 3 or len(self.edges) % 2:
+            raise ValueError("Mesh requires whole triangles, one normal per vertex and edge pairs")
+
+    def bbox(self) -> tuple[Vec, Vec] | None:
+        points = np.concatenate((self.positions, self.edges))
+        if not len(points):
+            return None
+        return triple(points.min(axis=0)), triple(points.max(axis=0))
+
+
+@dataclass
+class Shown:
+    """One object of the scene. `source` is the build123d shape; it never leaves the run process."""
+
+    name: str
+    color: Color
+    mesh: Mesh
+    volume: float | None = None  # mm³, for solids
+    source: Shape | Mesh | None = None
+    matrix: Matrix | None = None  # None: the mesh is in world coordinates; else the mesh's placement
+
+    def world(self) -> Mesh:
+        """The mesh in world coordinates (exports, reports)."""
+        return self.mesh if self.matrix is None else moved(self.mesh, self.matrix)
+
+    def bbox(self) -> tuple[Vec, Vec] | None:
+        """The bounds of the placed mesh (of its points, not a turned box: exact for turned parts)."""
+        if self.matrix is None:
+            return self.mesh.bbox()
+        points = np.concatenate((self.mesh.positions, self.mesh.edges))
+        if not len(points):
+            return None
+        m = np.array(self.matrix).reshape(4, 4)
+        placed = points @ m[:3, :3].T + m[:3, 3]
+        return triple(placed.min(axis=0)), triple(placed.max(axis=0))
+
+
+def triple(values: Iterable[float]) -> Vec:
+    x, y, z = map(float, values)
+    return x, y, z
+
+
+def parse_color(color: object, index: int = 0) -> Color:
+    """#RRGGBB, a basic color name, or an RGB triple in 0..1 or 0..255; None picks from the palette."""
+    value = PALETTE[index % len(PALETTE)] if color is None else color
+    if isinstance(value, str):
+        value = NAMED_COLORS.get(value.lower(), value)
+        try:
+            if len(value) != 7 or value[0] != "#":
+                raise ValueError
+            return triple(int(value[i:i + 2], 16) / 255 for i in (1, 3, 5))
+        except ValueError:
+            raise ValueError(f"Color must be #RRGGBB or a basic color name, not {color!r}") from None
+    rgb = np.asarray(value, dtype=float)
+    if rgb.shape != (3,) or not np.isfinite(rgb).all() or rgb.min() < 0 or rgb.max() > 255:
+        raise ValueError("Color must be three components in 0..1 or 0..255")
+    return triple(rgb / 255 if rgb.max() > 1 else rgb)
+
+
+def hex_color(color: Color) -> str:
+    return "#" + "".join(f"{round(c * 255):02X}" for c in color)
+
+
+def flatten(objs: object) -> list:
+    """Nested lists/tuples of shapes, builders or meshes -> flat list of build123d Shapes and Meshes."""
+    import build123d as b
+    from build123d.topology import Shape
+
+    if isinstance(objs, (list, tuple)):
+        return [item for child in objs for item in flatten(child)]
+    if isinstance(objs, Mesh):
+        return [objs]
+    for builder, attribute in ((b.BuildPart, "part"), (b.BuildSketch, "sketch"), (b.BuildLine, "line")):
+        if isinstance(objs, builder):
+            objs = getattr(objs, attribute)
+            break
+    if not isinstance(objs, Shape):
+        raise TypeError(f"Cannot show {type(objs).__name__}: expected build123d shapes, builders or meshes")
+    if objs.wrapped is None:
+        raise ValueError("Cannot show an empty shape")
+    return [objs]
+
+
+def copy_shape(shape: Shape) -> Shape:
+    """Copy placement and export metadata, sharing the geometry (build123d's copy() deep-copies it)."""
+    from OCP.TopLoc import TopLoc_Location  # pyright: ignore[reportAttributeAccessIssue]
+    from build123d.topology import Shape
+
+    reference = Shape.cast(shape.wrapped.Moved(TopLoc_Location()))
+    reference.label, reference.color = shape.label, shape.color
+    if shape.children:
+        wrapped = reference.wrapped
+        reference.children = [copy_shape(child) for child in shape.children]
+        reference.wrapped = wrapped  # attaching children rebuilds a compound: keep its original placement
+    return reference
+
+
+_placed: dict[int, list[tuple[object, Mesh, float | None]]] = {}  # this run's, by shape without placement
+
+
+def placed(shape) -> tuple[Mesh, Matrix | None, float | None]:
+    """The mesh of a shape in its own coordinates, where the shape is placed and its volume (of its
+    solids). Copies moved with Pos/Rot share them: each different shape is computed once per run."""
+    if isinstance(shape, Mesh):
+        return shape, None, None
+    from OCP.TopLoc import TopLoc_Location  # pyright: ignore[reportAttributeAccessIssue]
+    from build123d.topology import Shape
+
+    bare = shape.wrapped.Located(TopLoc_Location())
+    same = _placed.setdefault(hash(bare), [])
+    found = next((entry for entry in same if entry[0].IsEqual(bare)), None)  # pyright: ignore[reportAttributeAccessIssue]
+    if found is None:
+        found = (bare, tessellate(Shape.cast(bare)), float(shape.volume) if shape.solids() else None)
+        same.append(found)
+    _, mesh, volume = found
+    location = shape.wrapped.Location()
+    if location.IsIdentity():
+        return mesh, None, volume
+    trsf = location.Transformation()
+    return mesh, tuple(trsf.Value(i, j) if i < 4 else float(j == 4) for i in range(1, 5) for j in range(1, 5)), volume
+
+
+def moved(mesh: Mesh, matrix: Matrix) -> Mesh:
+    """The mesh placed by the matrix, in world coordinates."""
+    m = np.array(matrix).reshape(4, 4)
+    rotation, offset = m[:3, :3].T, m[:3, 3]
+    return Mesh(mesh.positions @ rotation + offset, mesh.normals @ rotation, mesh.edges @ rotation + offset)
+
+
+def tessellate(shape, tolerance: float = 0.05, angular_tolerance: float = 0.2) -> Mesh:
+    """Triangles and edge polylines of a build123d Shape, in world coordinates."""
+    from OCP.BRep import BRep_Tool  # pyright: ignore[reportAttributeAccessIssue]
+    from OCP.BRepAdaptor import BRepAdaptor_Curve  # pyright: ignore[reportAttributeAccessIssue]
+    from OCP.BRepLib import BRepLib_ToolTriangulatedShape  # pyright: ignore[reportAttributeAccessIssue]
+    from OCP.GCPnts import GCPnts_QuasiUniformDeflection  # pyright: ignore[reportAttributeAccessIssue]
+    from OCP.TopAbs import TopAbs_REVERSED  # pyright: ignore[reportAttributeAccessIssue]
+    from OCP.TopLoc import TopLoc_Location  # pyright: ignore[reportAttributeAccessIssue]
+
+    positions, normals, segments = [], [], []
+    faces = shape.faces()
+    if faces:
+        shape.mesh(tolerance, angular_tolerance)
+    for face in faces:
+        location = TopLoc_Location()
+        poly = BRep_Tool.Triangulation_s(face.wrapped, location)
+        if poly is None:
+            continue
+        transform = location.Transformation()
+        reverse = face.wrapped.Orientation() == TopAbs_REVERSED
+        BRepLib_ToolTriangulatedShape.ComputeNormals_s(face.wrapped, poly)
+        nodes = range(1, poly.NbNodes() + 1)
+        vertices = np.array([poly.Node(i).Transformed(transform).Coord() for i in nodes], dtype=np.float32)
+        vertex_normals = np.array([poly.Normal(i).Transformed(transform).Coord() for i in nodes], dtype=np.float32)
+        triangles = np.array([poly.Triangle(i).Get() for i in range(1, poly.NbTriangles() + 1)], dtype=int) - 1
+        if reverse:
+            triangles = triangles[:, [0, 2, 1]]
+            vertex_normals = -vertex_normals
+        positions.append(vertices[triangles].reshape(-1, 3))
+        normals.append(vertex_normals[triangles].reshape(-1, 3))
+    for edge in shape.edges():
+        if edge.length <= 1e-12:
+            continue
+        samples = GCPnts_QuasiUniformDeflection(BRepAdaptor_Curve(edge.wrapped), tolerance)
+        if not samples.IsDone():
+            raise RuntimeError("Could not discretize an edge")
+        points = [samples.Value(i).Coord() for i in range(1, samples.NbPoints() + 1)]
+        for a, c in zip(points, points[1:]):
+            segments.extend((a, c))
+    return Mesh(np.concatenate(positions) if positions else np.empty((0, 3)),
+                np.concatenate(normals) if normals else np.empty((0, 3)),
+                np.asarray(segments, dtype=np.float32).reshape(-1, 3))
+
+
+def import_mesh(path, solid: bool = False, max_faces: int = 5000):
+    """Read an STL or 3MF file.
+
+    solid=False (default): a fast Mesh you can show() and export, not usable in booleans.
+    solid=True: a build123d Solid for booleans; only for small closed meshes (<= max_faces).
+    """
+    from .files import read_triangles, write_stl
+
+    points = read_triangles(path)
+    if not len(points):
+        raise ValueError(f"{path}: the mesh has no triangles")
+    triangles = points.reshape(-1, 3, 3)
+    normals = np.cross(triangles[:, 1] - triangles[:, 0], triangles[:, 2] - triangles[:, 0])
+    normals /= np.maximum(np.linalg.norm(normals, axis=1, keepdims=True), 1e-20)
+    mesh = Mesh(points, np.repeat(normals, 3, axis=0), np.empty((0, 3)))
+    if not solid:
+        return mesh
+    if len(triangles) > max_faces:
+        raise ValueError(f"{path} has {len(triangles)} faces (max_faces={max_faces}): booleans on big meshes "
+                         "are extremely slow. Use solid=False or simplify the mesh.")
+    from build123d import Mesher, Solid
+
+    TEMP.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(dir=TEMP) as folder:
+        stl = Path(folder) / "mesh.stl"
+        write_stl([mesh], stl)
+        try:
+            shapes = Mesher().read(stl)
+        except (AssertionError, RuntimeError, ValueError):
+            shapes = []
+    if len(shapes) != 1 or not isinstance(shapes[0], Solid) or not shapes[0].is_valid:
+        raise ValueError(f"{path} is not a single closed valid solid")
+    return shapes[0]
+
+
+def remove_stale_temp(age: float = 600.0) -> None:
+    """Delete temporary folders left behind by runs that were killed (Stop) mid-way."""
+    for folder in TEMP.glob("*"):
+        try:
+            if time.time() - folder.stat().st_mtime > age:
+                shutil.rmtree(folder, ignore_errors=True)
+        except OSError:
+            pass

pycodecad/camera.py

@@ -0,0 +1,136 @@
+"""Orbit camera around a target point. Z is up; angles in degrees.
+
+Matrices are 16 floats in column-major order, the layout GL uniforms expect.
+"""
+from __future__ import annotations
+
+import math
+from dataclasses import replace
+from typing import Annotated
+
+from pytypehint import Max, Min, immutable
+
+Vec = tuple[float, float, float]
+BBox = tuple[Vec, Vec]  # (min corner, max corner)
+
+VIEWS = {  # name -> (yaw, pitch)
+    "iso": (315.0, 35.264), "front": (270.0, 0.0), "back": (90.0, 0.0), "left": (180.0, 0.0),
+    "right": (0.0, 0.0), "top": (270.0, 89.0), "bottom": (270.0, -89.0),
+}
+
+
+@immutable
+class Camera:
+    """Looks at target from distance away; yaw turns around Z (0 looks from +X), pitch tilts up."""
+    target: Vec = (0.0, 0.0, 0.0)
+    distance: Annotated[float, Min(1e-6), Max(1e12)] = 100.0
+    yaw: Annotated[float, Min(0.0), Max(360.0, exclusive=True)] = 315.0
+    pitch: Annotated[float, Min(-89.0), Max(89.0)] = 35.264
+    fov: Annotated[float, Min(0.0, exclusive=True), Max(180.0, exclusive=True)] = 45.0
+
+
+def wrap_yaw(degrees: float) -> float:
+    """Any angle as a yaw in [0, 360)."""
+    yaw = float(degrees) % 360.0
+    return 0.0 if yaw == 360.0 else yaw  # a tiny negative angle rounds up to 360
+
+
+def clamp(value: float, low: float, high: float) -> float:
+    return min(high, max(low, float(value)))
+
+
+def basis(cam: Camera) -> tuple[Vec, Vec, Vec]:
+    """Right, up and back unit vectors."""
+    yaw, pitch = math.radians(cam.yaw), math.radians(cam.pitch)
+    back = (math.cos(pitch) * math.cos(yaw), math.cos(pitch) * math.sin(yaw), math.sin(pitch))
+    right = (-math.sin(yaw), math.cos(yaw), 0.0)
+    up = (back[1] * right[2] - back[2] * right[1], back[2] * right[0] - back[0] * right[2],
+          back[0] * right[1] - back[1] * right[0])
+    return right, up, back
+
+
+def orbit(cam: Camera, dx: float, dy: float) -> Camera:
+    return replace(cam, yaw=wrap_yaw(cam.yaw - dx * 0.35), pitch=clamp(cam.pitch + dy * 0.35, -89.0, 89.0))
+
+
+def pan(cam: Camera, dx: float, dy: float, height: float) -> Camera:
+    """Move by pixels; height is the shorter viewport side (the axis the fov spans)."""
+    right, up, _ = basis(cam)
+    scale = 2 * cam.distance * math.tan(math.radians(cam.fov / 2)) / max(height, 1.0)
+    target = tuple(float(t - r * dx * scale + u * dy * scale) for t, r, u in zip(cam.target, right, up))
+    return replace(cam, target=target)
+
+
+def zoom(cam: Camera, wheel: float) -> Camera:
+    return replace(cam, distance=clamp(cam.distance * math.exp(-wheel * 0.12), 1e-6, 1e12))
+
+
+def check_view(view: str, *others: str) -> None:
+    """Raise ValueError unless `view` is one of VIEWS (or of `others`)."""
+    if view not in VIEWS and view not in others:
+        raise ValueError(f"Unknown view {view!r}: use one of {', '.join([*VIEWS, *others])}")
+
+
+def set_view(cam: Camera, view: str) -> Camera:
+    check_view(view)
+    yaw, pitch = VIEWS[view]
+    return replace(cam, yaw=yaw, pitch=pitch)
+
+
+def look_from(cam: Camera, direction: Vec) -> Camera:
+    """Look at the target from a direction (any length): (0, -1, 0) is the front view, (1, -1, 1) iso."""
+    x, y, z = direction
+    flat = math.hypot(x, y)
+    yaw = wrap_yaw(math.degrees(math.atan2(y, x))) if flat > 1e-9 else VIEWS["top"][0]  # straight down: front at the bottom
+    pitch = clamp(math.degrees(math.atan2(z, flat)), -89.0, 89.0)
+    return replace(cam, yaw=yaw, pitch=pitch)
+
+
+def fit(cam: Camera, bbox: BBox) -> Camera:
+    """Frame the bounding sphere of the box with a small margin."""
+    lo, hi = bbox
+    radius = max(math.dist(lo, hi) / 2, 1e-5)
+    target = tuple(float((a + b) / 2) for a, b in zip(lo, hi))
+    distance = clamp(radius / math.sin(math.radians(cam.fov / 2)) * 1.15, 1e-6, 1e12)
+    return replace(cam, target=target, distance=distance)
+
+
+def needs_fit(previous: BBox | None, current: BBox | None) -> bool:
+    """Keep the view for small edits; refit after a 2x size change or a large move."""
+    if current is None:
+        return False
+    if previous is None:
+        return True
+    old_size = max(math.dist(*previous), 1e-5)
+    new_size = max(math.dist(*current), 1e-5)
+    old_center = [(a + b) / 2 for a, b in zip(*previous)]
+    new_center = [(a + b) / 2 for a, b in zip(*current)]
+    return not old_size / 2 < new_size < old_size * 2 or math.dist(old_center, new_center) > old_size / 2
+
+
+def matrices(cam: Camera, aspect: float) -> tuple[tuple[float, ...], tuple[float, ...]]:
+    """(view, projection) matrices; the fov spans the shorter side of the viewport."""
+    right, up, back = basis(cam)
+    eye = tuple(t + b * cam.distance for t, b in zip(cam.target, back))
+    dot = lambda a, b: a[0] * b[0] + a[1] * b[1] + a[2] * b[2]
+    view = (right[0], up[0], back[0], 0.0,
+            right[1], up[1], back[1], 0.0,
+            right[2], up[2], back[2], 0.0,
+            -dot(right, eye), -dot(up, eye), -dot(back, eye), 1.0)
+    near, far = max(cam.distance * 0.001, 1e-8), cam.distance * 100
+    aspect = max(aspect, 1e-6)
+    f = min(1.0, aspect) / math.tan(math.radians(cam.fov / 2))
+    projection = (f / aspect, 0.0, 0.0, 0.0,
+                  0.0, f, 0.0, 0.0,
+                  0.0, 0.0, (far + near) / (near - far), -1.0,
+                  0.0, 0.0, 2 * far * near / (near - far), 0.0)
+    return view, projection
+
+
+def scene_bbox(boxes: list[BBox | None]) -> BBox | None:
+    present = [box for box in boxes if box is not None]
+    if not present:
+        return None
+    low_x, low_y, low_z = zip(*(low for low, _ in present))
+    high_x, high_y, high_z = zip(*(high for _, high in present))
+    return (min(low_x), min(low_y), min(low_z)), (max(high_x), max(high_y), max(high_z))