kulisse 1.0.1__tar.gz

kulisse-1.0.1/.gitignore

@@ -0,0 +1,7 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.coverage
+coverage.xml

kulisse-1.0.1/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2023 Johannes Roos <jhnnsrs@gmail.com>
+
+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.

kulisse-1.0.1/PKG-INFO

@@ -0,0 +1,49 @@
+Metadata-Version: 2.5
+Name: kulisse
+Version: 1.0.1
+Summary: device and scene models for arkitekt: self-contained binary glTF with a joint table, authored from URDF and checked before upload
+Project-URL: Repository, https://github.com/arkitektio/kulisse
+Project-URL: Specification, https://github.com/arkitektio/kulisse/blob/main/KULISSE.md
+Author-email: jhnnsrs <jhnnsrs@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Provides-Extra: complete
+Requires-Dist: numpy>=1.26; extra == 'complete'
+Requires-Dist: pycollada>=0.8; extra == 'complete'
+Requires-Dist: trimesh>=4; extra == 'complete'
+Requires-Dist: xacro>=2; extra == 'complete'
+Provides-Extra: urdf
+Requires-Dist: numpy>=1.26; extra == 'urdf'
+Requires-Dist: pycollada>=0.8; extra == 'urdf'
+Requires-Dist: trimesh>=4; extra == 'urdf'
+Requires-Dist: xacro>=2; extra == 'urdf'
+Description-Content-Type: text/markdown
+
+# kulisse
+
+Device and scene models for arkitekt. A model is one **self-contained binary glTF** (GLB) with
+an optional joint table: what a viewer draws as a `<Model>` or drives as a `<Robot>`, what an
+app registers as an asset, and what a server keeps in a `KulisseStore`.
+
+kulisse is strictly the authoring side, like fabriks for meshes: no network code, no storage
+opinions. The **format** is the contract ([`KULISSE.md`](KULISSE.md)), and the server reads it
+with its own implementation (`arkitekt_datalayer.kulisse`), never by importing this package.
+
+```bash
+pip install kulisse            # check, reference, snippet: standard library only
+pip install "kulisse[urdf]"    # import URDF / Xacro (numpy, trimesh, pycollada, xacro)
+
+kulisse import robot.urdf.xacro --out robot.glb --package my_robot=./share/my_robot
+kulisse check robot.glb
+kulisse joints robot.glb joints.json --out robot.glb
+kulisse snippet robot.glb --name robot
+```
+
+```python
+import kulisse
+
+report = kulisse.check("robot.glb")      # ModelReport, or ModelRefused(code, message)
+kulisse.reference("robot.glb")           # "sha256:…", what a blok names as for_model
+kulisse.snippet("robot.glb")             # '<Robot src="@self.assets.robot" … />'
+```

kulisse-1.0.1/README.md

@@ -0,0 +1,27 @@
+# kulisse
+
+Device and scene models for arkitekt. A model is one **self-contained binary glTF** (GLB) with
+an optional joint table: what a viewer draws as a `<Model>` or drives as a `<Robot>`, what an
+app registers as an asset, and what a server keeps in a `KulisseStore`.
+
+kulisse is strictly the authoring side, like fabriks for meshes: no network code, no storage
+opinions. The **format** is the contract ([`KULISSE.md`](KULISSE.md)), and the server reads it
+with its own implementation (`arkitekt_datalayer.kulisse`), never by importing this package.
+
+```bash
+pip install kulisse            # check, reference, snippet: standard library only
+pip install "kulisse[urdf]"    # import URDF / Xacro (numpy, trimesh, pycollada, xacro)
+
+kulisse import robot.urdf.xacro --out robot.glb --package my_robot=./share/my_robot
+kulisse check robot.glb
+kulisse joints robot.glb joints.json --out robot.glb
+kulisse snippet robot.glb --name robot
+```
+
+```python
+import kulisse
+
+report = kulisse.check("robot.glb")      # ModelReport, or ModelRefused(code, message)
+kulisse.reference("robot.glb")           # "sha256:…", what a blok names as for_model
+kulisse.snippet("robot.glb")             # '<Robot src="@self.assets.robot" … />'
+```

kulisse-1.0.1/kulisse/__init__.py

@@ -0,0 +1,56 @@
+"""kulisse: authoring device models for Arkitekt's 3D view.
+
+A model is a plain GLB. This package turns a URDF or Xacro into one, checks any GLB
+against the rules a model is held to, and writes the blok snippet that shows it. It
+uploads nothing itself: an app registers the file as an asset
+(``app.register_asset("scope", "scope.glb")``), names it in a blok
+(``@self.assets.scope``) and uploads it when it runs.
+
+Installed with ``pip install kulisse`` (``kulisse[urdf]`` to import URDF/Xacro); also a command,
+``kulisse``. The wire format both sides implement is ``KULISSE.md``.
+"""
+
+from pathlib import Path
+
+from .urdf import UrdfImportError, import_urdf, with_joints
+from .validate import ModelPolicy, ModelRefused, ModelReport, model_ref, validate_model
+
+__all__ = [
+    "ModelPolicy",
+    "ModelRefused",
+    "ModelReport",
+    "UrdfImportError",
+    "check",
+    "import_urdf",
+    "model_ref",
+    "reference",
+    "snippet",
+    "validate_model",
+    "with_joints",
+]
+
+
+def reference(path: str | Path) -> str:
+    """The reference of the model file at ``path``: the hash a blok decorating it names as ``for_model``."""
+    return model_ref(Path(path).read_bytes())
+
+
+def check(path: str | Path, policy: ModelPolicy | None = None) -> ModelReport:
+    """Hold the model file at ``path`` to the rules; what it contains, or ``ModelRefused``."""
+    data = Path(path).read_bytes()
+    return validate_model(data, model_ref(data), policy)
+
+
+def snippet(path: str | Path, name: str | None = None) -> str:
+    """The blok component that places the model at ``path``, registered as the asset ``name``.
+
+    The name is the file's, without its extension, when none is given: what the app
+    passes to ``app.register_asset``.
+    """
+    name = name or Path(path).stem
+    if not name.isidentifier():
+        raise ValueError(f"an asset's name is an identifier: {name!r} is not one, pass a name")
+    report = check(path)
+    if report.joints:
+        return f'<Robot src="@self.assets.{name}" joints="@self.State.joints" />'
+    return f'<Model src="@self.assets.{name}" />'

kulisse-1.0.1/kulisse/cli.py

@@ -0,0 +1,100 @@
+"""The ``kulisse`` command: import, check, joints, snippet."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import fields
+from pathlib import Path
+
+from . import check, snippet
+from .urdf import UrdfImportError, import_urdf, with_joints
+from .validate import ModelPolicy, ModelRefused, model_ref
+
+
+def _pairs(values: list[str], separator: str, what: str) -> dict[str, str]:
+    pairs: dict[str, str] = {}
+    for value in values:
+        name, found, rest = value.partition(separator)
+        if not found or not name:
+            raise SystemExit(f"{what} is written name{separator}value, not {value!r}")
+        pairs[name] = rest
+    return pairs
+
+
+def _policy(path: str | None) -> ModelPolicy | None:
+    """A policy read from a JSON file, as ``modelPolicy`` returns it (camelCase or snake_case keys)."""
+    if path is None:
+        return None
+    raw = json.loads(Path(path).read_text(encoding="utf-8"))
+    known = {field.name for field in fields(ModelPolicy)}
+    values: dict[str, object] = {}
+    for key, value in raw.items():
+        name = "".join("_" + letter.lower() if letter.isupper() else letter for letter in key)
+        if name not in known:
+            raise SystemExit(f"{path}: unknown policy field {key!r}")
+        values[name] = frozenset(value) if name == "extensions" else int(value)
+    return ModelPolicy(**values)  # type: ignore[arg-type]
+
+
+def _report(path: Path, policy: ModelPolicy | None) -> None:
+    report = check(path, policy)
+    print(f"{path}  {report.ref}")
+    stats = report.stats
+    print(f"  {report.size} bytes, {stats.nodes} nodes, {stats.triangles} triangles, {stats.textures} textures, {stats.animations} clips, {len(report.joints)} joints")
+    for warning in report.warnings:
+        print(f"  warning: {warning}")
+
+
+def main(argv: list[str] | None = None) -> int:
+    """Run the ``kulisse`` command; the exit code is 1 when a model or an import is refused."""
+    parser = argparse.ArgumentParser(prog="kulisse", description="Author device models for Arkitekt's 3D view.")
+    commands = parser.add_subparsers(dest="command", required=True)
+
+    importer = commands.add_parser("import", help="convert a URDF or Xacro file into a GLB model")
+    importer.add_argument("urdf", type=Path)
+    importer.add_argument("--out", type=Path, required=True, help="the GLB file to write")
+    importer.add_argument("--package", action="append", default=[], metavar="NAME=DIR", help="where a package:// the file refers to is on disk")
+    importer.add_argument("--arg", action="append", default=[], metavar="NAME:=VALUE", help="a Xacro argument")
+
+    checker = commands.add_parser("check", help="hold a GLB to the rules a model is held to")
+    checker.add_argument("glb", type=Path)
+    checker.add_argument("--policy", help="a JSON file with an organization's policy; the deployment defaults otherwise")
+
+    jointer = commands.add_parser("joints", help="write a joint table into a GLB that was not imported from URDF")
+    jointer.add_argument("glb", type=Path)
+    jointer.add_argument("table", type=Path, help="a JSON file: a list of joints as extras.arkitekt.joints holds them")
+    jointer.add_argument("--out", type=Path, required=True)
+
+    snipper = commands.add_parser("snippet", help="print the blok component that references a model")
+    snipper.add_argument("glb", type=Path)
+    snipper.add_argument("--name", default=None, help="the name the app registers the file under; the file's name without its extension by default")
+
+    args = parser.parse_args(argv)
+    try:
+        if args.command == "import":
+            data = import_urdf(args.urdf, packages={name: Path(root) for name, root in _pairs(args.package, "=", "--package").items()}, arguments=_pairs(args.arg, ":=", "--arg"))
+            args.out.write_bytes(data)
+            _report(args.out, None)
+            print(f"wrote {args.out}  {model_ref(data)}")
+        elif args.command == "check":
+            _report(args.glb, _policy(args.policy))
+        elif args.command == "joints":
+            data = with_joints(args.glb.read_bytes(), json.loads(args.table.read_text(encoding="utf-8")))
+            args.out.write_bytes(data)
+            _report(args.out, None)
+            print(f"wrote {args.out}  {model_ref(data)}")
+        else:
+            print(snippet(args.glb, args.name))
+    except ModelRefused as refusal:
+        print(f"refused ({refusal.code}): {refusal.message}", file=sys.stderr)
+        return 1
+    except (UrdfImportError, ValueError, OSError) as error:
+        print(f"error: {error}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

kulisse-1.0.1/kulisse/urdf.py

@@ -0,0 +1,394 @@
+"""URDF and Xacro to a model: a GLB whose nodes are the robot's links and joints.
+
+One node per link; for each joint that moves, a pivot node at the joint's origin, named
+after the joint, with the child link beneath it; a fixed joint is plain parent and child.
+The joints are written into ``extras.arkitekt`` with URDF's own semantics, so nothing is
+lost on the way. Collision, inertial and simulator tags are dropped.
+
+Identical input must give identical bytes, or the same robot ends up as two models. The
+GLB is therefore written here, in document order, with nothing in it that depends on the
+time, the machine or a dictionary's mood.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import struct
+import xml.etree.ElementTree as ET
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import TYPE_CHECKING, Any, cast
+from xml.dom.minidom import Document
+
+if TYPE_CHECKING:
+    # The urdf extra brings numpy; the rest of kulisse must import without it.
+    import numpy as np
+
+GENERATOR = "kulisse 1"
+"""Written into ``asset.generator``. Changes only when the bytes this module writes change."""
+
+MOVING = ("revolute", "continuous", "prismatic")
+
+
+class UrdfImportError(ValueError):
+    """A URDF this importer cannot turn into a model, with the reason."""
+
+
+def _floats(text: str | None, count: int, default: tuple[float, ...]) -> tuple[float, ...]:
+    if text is None:
+        return default
+    values = tuple(float(part) for part in text.split())
+    if len(values) != count:
+        raise UrdfImportError(f"expected {count} numbers, got {text!r}")
+    return values
+
+
+def _quaternion(roll: float, pitch: float, yaw: float) -> tuple[float, float, float, float]:
+    """URDF's fixed-axis roll, pitch, yaw as a glTF quaternion (x, y, z, w)."""
+    cr, sr = math.cos(roll / 2), math.sin(roll / 2)
+    cp, sp = math.cos(pitch / 2), math.sin(pitch / 2)
+    cy, sy = math.cos(yaw / 2), math.sin(yaw / 2)
+    return (
+        sr * cp * cy - cr * sp * sy,
+        cr * sp * cy + sr * cp * sy,
+        cr * cp * sy - sr * sp * cy,
+        cr * cp * cy + sr * sp * sy,
+    )
+
+
+def _multiply(a: tuple[float, ...], b: tuple[float, ...]) -> tuple[float, float, float, float]:
+    ax, ay, az, aw = a
+    bx, by, bz, bw = b
+    return (
+        aw * bx + ax * bw + ay * bz - az * by,
+        aw * by - ax * bz + ay * bw + az * bx,
+        aw * bz + ax * by - ay * bx + az * bw,
+        aw * bw - ax * bx - ay * by - az * bz,
+    )
+
+
+def _clean(values: tuple[float, ...]) -> list[float]:
+    """Numbers as they are written: rounded past float noise, and never a negative zero."""
+    return [0.0 if abs(value) < 1e-12 else round(value, 9) for value in values]
+
+
+@dataclass
+class Origin:
+    """A URDF ``<origin>``: translation and roll/pitch/yaw."""
+
+    xyz: tuple[float, ...] = (0.0, 0.0, 0.0)
+    rpy: tuple[float, ...] = (0.0, 0.0, 0.0)
+
+    @classmethod
+    def parse(cls, element: ET.Element | None) -> Origin:
+        """The origin an element states, or the identity when it states none."""
+        if element is None:
+            return cls()
+        return cls(_floats(element.get("xyz"), 3, (0.0, 0.0, 0.0)), _floats(element.get("rpy"), 3, (0.0, 0.0, 0.0)))
+
+    def node(self) -> dict[str, Any]:
+        """The transform as glTF node properties, left out where it is the identity."""
+        out: dict[str, Any] = {}
+        if any(self.xyz):
+            out["translation"] = _clean(self.xyz)
+        if any(self.rpy):
+            out["rotation"] = _clean(_quaternion(*self.rpy))
+        return out
+
+
+@dataclass
+class Builder:
+    """A glTF document and its binary chunk, grown in the order things are added."""
+
+    nodes: list[dict[str, Any]] = field(default_factory=list)
+    meshes: list[dict[str, Any]] = field(default_factory=list)
+    materials: list[dict[str, Any]] = field(default_factory=list)
+    accessors: list[dict[str, Any]] = field(default_factory=list)
+    views: list[dict[str, Any]] = field(default_factory=list)
+    images: list[dict[str, Any]] = field(default_factory=list)
+    textures: list[dict[str, Any]] = field(default_factory=list)
+    binary: bytearray = field(default_factory=bytearray)
+    material_index: dict[str, int] = field(default_factory=dict)
+
+    def view(self, data: bytes, target: int | None = None) -> int:
+        """Append ``data`` to the binary chunk as a buffer view; its index."""
+        self.binary.extend(b"\0" * (-len(self.binary) % 4))
+        view: dict[str, Any] = {"buffer": 0, "byteOffset": len(self.binary), "byteLength": len(data)}
+        if target is not None:
+            view["target"] = target
+        self.binary.extend(data)
+        self.views.append(view)
+        return len(self.views) - 1
+
+    def accessor(self, array: np.ndarray, kind: str, component: int, target: int, bounds: bool = False) -> int:
+        """An accessor over ``array``, with min/max when ``bounds``; its index."""
+        accessor: dict[str, Any] = {
+            "bufferView": self.view(array.tobytes(), target),
+            "componentType": component,
+            "count": int(array.shape[0]),
+            "type": kind,
+        }
+        if bounds:
+            accessor["min"] = [float(value) for value in array.min(axis=0)]
+            accessor["max"] = [float(value) for value in array.max(axis=0)]
+        self.accessors.append(accessor)
+        return len(self.accessors) - 1
+
+    def mesh(self, vertices: np.ndarray, normals: np.ndarray, faces: np.ndarray, material: int | None) -> int:
+        """One triangle-list primitive; the mesh index."""
+        primitive: dict[str, Any] = {
+            "attributes": {
+                "POSITION": self.accessor(vertices.astype("<f4"), "VEC3", 5126, 34962, bounds=True),
+                "NORMAL": self.accessor(normals.astype("<f4"), "VEC3", 5126, 34962),
+            },
+            "indices": self.accessor(faces.astype("<u4").reshape(-1), "SCALAR", 5125, 34963),
+        }
+        if material is not None:
+            primitive["material"] = material
+        self.meshes.append({"primitives": [primitive]})
+        return len(self.meshes) - 1
+
+    def material(self, key: str, rgba: tuple[float, ...] | None, texture: Path | None) -> int:
+        """The material for ``key``, made once; its index."""
+        known = self.material_index.get(key)
+        if known is not None:
+            return known
+        pbr: dict[str, Any] = {"metallicFactor": 0.1, "roughnessFactor": 0.7}
+        if rgba is not None:
+            pbr["baseColorFactor"] = _clean(rgba)
+        if texture is not None:
+            data = texture.read_bytes()
+            mime = {".png": "image/png", ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".webp": "image/webp"}.get(texture.suffix.lower())
+            if mime is None:
+                raise UrdfImportError(f"texture {texture.name} is not a PNG, JPEG or WebP")
+            self.images.append({"bufferView": self.view(data), "mimeType": mime})
+            self.textures.append({"source": len(self.images) - 1})
+            pbr["baseColorTexture"] = {"index": len(self.textures) - 1}
+        material: dict[str, Any] = {"pbrMetallicRoughness": pbr}
+        if rgba is not None and rgba[3] < 1:
+            material["alphaMode"] = "BLEND"
+        self.materials.append(material)
+        self.material_index[key] = len(self.materials) - 1
+        return self.material_index[key]
+
+    def node(self, properties: dict[str, Any]) -> int:
+        """Append a node; its index."""
+        self.nodes.append(properties)
+        return len(self.nodes) - 1
+
+    def glb(self, root: int, extras: dict[str, Any]) -> bytes:
+        """The finished GLB with ``root`` as the scene and ``extras`` on it."""
+        document: dict[str, Any] = {
+            "asset": {"version": "2.0", "generator": GENERATOR},
+            "scene": 0,
+            "scenes": [{"nodes": [root]}],
+            "nodes": self.nodes,
+        }
+        for key, value in (
+            ("meshes", self.meshes),
+            ("materials", self.materials),
+            ("textures", self.textures),
+            ("images", self.images),
+            ("accessors", self.accessors),
+            ("bufferViews", self.views),
+        ):
+            if value:
+                document[key] = value
+        binary = bytes(self.binary) + b"\0" * (-len(self.binary) % 4)
+        if binary:
+            document["buffers"] = [{"byteLength": len(binary)}]
+        document["extras"] = extras
+        payload = json.dumps(document, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+        payload += b" " * (-len(payload) % 4)
+        chunks = struct.pack("<II", len(payload), 0x4E4F534A) + payload
+        if binary:
+            chunks += struct.pack("<II", len(binary), 0x004E4942) + binary
+        return struct.pack("<III", 0x46546C67, 2, 12 + len(chunks)) + chunks
+
+
+def expand(path: Path, arguments: dict[str, str] | None = None) -> str:
+    """The URDF text of ``path``, with Xacro expanded when it is a Xacro file."""
+    if path.suffix != ".xacro" and not arguments:
+        return path.read_text(encoding="utf-8")
+    try:
+        import xacro
+    except ImportError as error:  # pragma: no cover - the extra installs it
+        raise UrdfImportError("expanding Xacro needs the xacro package: pip install 'kulisse[urdf]'") from error
+    # xacro's own annotation names a file object; what it returns is a minidom Document.
+    document = cast(Document, xacro.process_file(str(path), mappings=dict(arguments or {})))
+    return document.toxml()
+
+
+def _resolve(filename: str, base: Path, packages: dict[str, Path]) -> Path:
+    match = re.fullmatch(r"package://([^/]+)/(.*)", filename)
+    if match:
+        package, rest = match.groups()
+        if package not in packages:
+            raise UrdfImportError(f"{filename} names the package {package!r}; say where it is with --package {package}=<directory>")
+        return packages[package] / rest
+    return (base / filename.removeprefix("file://")).resolve()
+
+
+def _geometry(element: ET.Element, base: Path, packages: dict[str, Path]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+    """Vertices, normals and faces of one visual's geometry, in the visual's frame."""
+    import numpy as np
+    import trimesh
+
+    shape = next(iter(element), None)
+    if shape is None:
+        raise UrdfImportError("a visual has an empty geometry")
+    if shape.tag == "box":
+        mesh = trimesh.creation.box(extents=_floats(shape.get("size"), 3, (1.0, 1.0, 1.0)))
+    elif shape.tag == "cylinder":
+        mesh = trimesh.creation.cylinder(radius=float(shape.get("radius", 1)), height=float(shape.get("length", 1)), sections=32)
+    elif shape.tag == "sphere":
+        mesh = trimesh.creation.icosphere(subdivisions=3, radius=float(shape.get("radius", 1)))
+    elif shape.tag == "mesh":
+        source = _resolve(shape.get("filename", ""), base, packages)
+        if not source.is_file():
+            raise UrdfImportError(f"mesh file {source} does not exist")
+        mesh = cast(trimesh.Trimesh, trimesh.load(source, force="mesh", process=False))
+        scale = shape.get("scale")
+        if scale is not None:
+            mesh.apply_scale(_floats(scale, 3, (1.0, 1.0, 1.0)))
+    else:
+        raise UrdfImportError(f"geometry <{shape.tag}> is not supported")
+    return np.asarray(mesh.vertices), np.asarray(mesh.vertex_normals), np.asarray(mesh.faces)
+
+
+def import_urdf(
+    path: str | Path,
+    *,
+    packages: dict[str, str | Path] | None = None,
+    arguments: dict[str, str] | None = None,
+) -> bytes:
+    """Convert a URDF or Xacro file into the bytes of a GLB model.
+
+    Args:
+        path: The ``.urdf`` or ``.urdf.xacro`` file.
+        packages: Where each ``package://<name>/`` the file refers to is on disk.
+        arguments: Xacro arguments, as ``name: value``.
+
+    Raises:
+        UrdfImportError: For a floating or planar joint, a joint and a link sharing a name,
+            a robot with no single root link, or geometry that cannot be read.
+    """
+    import numpy as np
+
+    path = Path(path)
+    roots = {name: Path(directory) for name, directory in (packages or {}).items()}
+    text = expand(path, arguments)
+    robot = ET.fromstring(text)
+
+    links = {link.get("name", ""): link for link in robot.findall("link")}
+    joints = robot.findall("joint")
+    named_materials = {material.get("name", ""): material for material in robot.findall("material")}
+    for joint in joints:
+        name, kind = joint.get("name", ""), joint.get("type", "")
+        if kind in ("floating", "planar"):
+            raise UrdfImportError(f"joint {name!r} is {kind}; only fixed, revolute, continuous and prismatic joints are supported")
+        if kind != "fixed" and kind not in MOVING:
+            raise UrdfImportError(f"joint {name!r} has the unknown type {kind!r}")
+        if kind in MOVING and name in links:
+            raise UrdfImportError(f"the joint and the link {name!r} share a name; a node name must be unique, so rename one of them")
+    children_of: dict[str, list[ET.Element]] = {}
+    child_links: set[str] = set()
+    for joint in joints:
+        parent = joint.find("parent")
+        child = joint.find("child")
+        if parent is None or child is None:
+            raise UrdfImportError(f"joint {joint.get('name')!r} needs a parent and a child")
+        children_of.setdefault(parent.get("link", ""), []).append(joint)
+        child_links.add(child.get("link", ""))
+    root_links = [name for name in links if name not in child_links]
+    if len(root_links) != 1:
+        raise UrdfImportError(f"a robot has one root link; this one has {len(root_links)}: {root_links}")
+
+    builder = Builder()
+    table: list[dict[str, Any]] = []
+
+    def material_of(visual: ET.Element) -> int | None:
+        material = visual.find("material")
+        if material is None:
+            return None
+        name = material.get("name", "")
+        source = material if (material.find("color") is not None or material.find("texture") is not None) else named_materials.get(name)
+        if source is None:
+            return None
+        color = source.find("color")
+        texture = source.find("texture")
+        rgba = _floats(color.get("rgba"), 4, (1.0, 1.0, 1.0, 1.0)) if color is not None else None
+        image = _resolve(texture.get("filename", ""), path.parent, roots) if texture is not None else None
+        return builder.material(name or json.dumps([rgba, str(image)]), rgba, image)
+
+    def build_link(name: str, transform: dict[str, Any]) -> int:
+        link = links.get(name)
+        if link is None:
+            raise UrdfImportError(f"a joint refers to the link {name!r}, which does not exist")
+        children: list[int] = []
+        for index, visual in enumerate(link.findall("visual")):
+            geometry = visual.find("geometry")
+            if geometry is None:
+                continue
+            mesh = builder.mesh(*_geometry(geometry, path.parent, roots), material_of(visual))
+            children.append(builder.node({"name": f"{name}_visual_{index}", "mesh": mesh, **Origin.parse(visual.find("origin")).node()}))
+        for joint in children_of.get(name, []):
+            joint_name, kind = joint.get("name", ""), joint.get("type", "")
+            origin = Origin.parse(joint.find("origin")).node()
+            child = joint.find("child")
+            assert child is not None
+            if kind == "fixed":
+                children.append(build_link(child.get("link", ""), origin))
+                continue
+            children.append(builder.node({"name": joint_name, **origin, "children": [build_link(child.get("link", ""), {})]}))
+            axis_element = joint.find("axis")
+            axis = np.array(_floats(axis_element.get("xyz") if axis_element is not None else None, 3, (1.0, 0.0, 0.0)))
+            length = float(np.linalg.norm(axis))
+            if length == 0:
+                raise UrdfImportError(f"joint {joint_name!r} has a zero axis")
+            entry: dict[str, Any] = {"name": joint_name, "node": joint_name, "type": kind, "axis": _clean(tuple(axis / length))}
+            if kind != "continuous":
+                limit = joint.find("limit")
+                entry["limit"] = {
+                    "lower": float(limit.get("lower", 0)) if limit is not None else 0.0,
+                    "upper": float(limit.get("upper", 0)) if limit is not None else 0.0,
+                }
+            mimic = joint.find("mimic")
+            if mimic is not None:
+                entry["mimic"] = {"joint": mimic.get("joint", ""), "multiplier": float(mimic.get("multiplier", 1)), "offset": float(mimic.get("offset", 0))}
+            table.append(entry)
+        node: dict[str, Any] = {"name": name, **transform}
+        if children:
+            node["children"] = children
+        return builder.node(node)
+
+    root = build_link(root_links[0], {})
+    # URDF is Z-up, glTF Y-up: the root is turned once, and every frame below it follows.
+    upright = (-math.sqrt(0.5), 0.0, 0.0, math.sqrt(0.5))
+    existing = tuple(builder.nodes[root].get("rotation", (0.0, 0.0, 0.0, 1.0)))
+    builder.nodes[root]["rotation"] = _clean(_multiply(upright, existing))
+
+    # The table is in document order, not in the order the tree was walked.
+    order = {joint.get("name", ""): index for index, joint in enumerate(joints)}
+    table.sort(key=lambda entry: order[entry["name"]])
+    extras = {"arkitekt": {"version": 1, "joints": table, "source": "sha256:" + hashlib.sha256(text.encode("utf-8")).hexdigest()}}
+    return builder.glb(root, extras)
+
+
+def with_joints(data: bytes, joints: list[dict[str, Any]]) -> bytes:
+    """A copy of a GLB with ``joints`` as its joint table, for models that were not imported from URDF."""
+    magic, version, _length = struct.unpack_from("<III", data, 0)
+    json_length, json_type = struct.unpack_from("<II", data, 12)
+    if magic != 0x46546C67 or version != 2 or json_type != 0x4E4F534A:
+        raise UrdfImportError("the file is not a GLB")
+    document = json.loads(data[20 : 20 + json_length])
+    extras = document.setdefault("extras", {})
+    extras["arkitekt"] = {"version": 1, "joints": joints}
+    payload = json.dumps(document, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+    payload += b" " * (-len(payload) % 4)
+    rest = data[20 + json_length :]
+    body = struct.pack("<II", len(payload), 0x4E4F534A) + payload + rest
+    return struct.pack("<III", 0x46546C67, 2, 12 + len(body)) + body

kulisse-1.0.1/kulisse/validate.py

@@ -0,0 +1,449 @@
+"""What a GLB must be to be a model, checked on its bytes.
+
+The rule table ``KULISSE.md`` states: what a server holds a model to before it enters a
+``KulisseStore`` (arkitekt-datalayer's own reader of the format) and what every viewer runs
+before it shows one, plus the check only a client can make: texture sizes live in the binary chunk, which
+the server measures but never decodes. An author runs it here first, so a model that
+would be refused is never published.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+import re
+import struct
+from dataclasses import dataclass, field
+from typing import Any
+
+GLB_MAGIC = 0x46546C67  # "glTF"
+CHUNK_JSON = 0x4E4F534A  # "JSON"
+CHUNK_BIN = 0x004E4942  # "BIN\0"
+
+REF_PATTERN = re.compile(r"sha256:[0-9a-f]{64}")
+NODE_NAME_PATTERN = re.compile(r"[a-z0-9_]+")
+
+JOINT_TYPES = frozenset({"revolute", "continuous", "prismatic"})
+
+_COMPONENT_BYTES = {5120: 1, 5121: 1, 5122: 2, 5123: 2, 5125: 4, 5126: 4}
+_TYPE_COMPONENTS = {"SCALAR": 1, "VEC2": 2, "VEC3": 3, "VEC4": 4, "MAT2": 4, "MAT3": 9, "MAT4": 16}
+
+DEFAULT_EXTENSIONS = frozenset(
+    {
+        "KHR_lights_punctual",
+        "KHR_materials_emissive_strength",
+        "KHR_materials_variants",
+        "KHR_texture_transform",
+        "KHR_mesh_quantization",
+        "EXT_meshopt_compression",
+        "KHR_draco_mesh_compression",
+    }
+)
+
+
+@dataclass(frozen=True)
+class ModelPolicy:
+    """The limits a model is held to when it is created."""
+
+    max_size: int = 50 * 1024 * 1024
+    max_json: int = 4 * 1024 * 1024
+    max_nodes: int = 10_000
+    max_triangles: int = 2_000_000
+    max_texture_size: int = 4096
+    max_texture_memory: int = 256 * 1024 * 1024
+    max_animations: int = 64
+    extensions: frozenset[str] = DEFAULT_EXTENSIONS
+
+
+class ModelRefused(ValueError):
+    """A model that may not enter the store, with the code clients switch on."""
+
+    def __init__(self, code: str, message: str) -> None:
+        """A refusal: ``code`` is what clients switch on, ``message`` what a person reads."""
+        super().__init__(message)
+        self.code = code
+        self.message = message
+
+
+@dataclass(frozen=True)
+class ModelStats:
+    """What a model contains, counted from its JSON."""
+
+    nodes: int
+    triangles: int
+    textures: int
+    animations: int
+
+
+@dataclass(frozen=True)
+class ModelReport:
+    """What validation learned about an accepted model."""
+
+    ref: str
+    size: int
+    nodes: list[str]
+    stats: ModelStats
+    warnings: list[str] = field(default_factory=list)
+    joints: list[dict[str, Any]] = field(default_factory=list)
+
+
+def model_ref(data: bytes) -> str:
+    """The reference of these exact bytes."""
+    return "sha256:" + hashlib.sha256(data).hexdigest()
+
+
+def check_ref_format(ref: str) -> None:
+    """Refuse a reference that is not ``sha256:`` and 64 lowercase hex digits."""
+    if not REF_PATTERN.fullmatch(ref):
+        raise ModelRefused("bad_reference", f"a model reference is 'sha256:' and 64 lowercase hex characters, not {ref!r}")
+
+
+def validate_model(data: bytes, ref: str, policy: ModelPolicy | None = None) -> ModelReport:
+    """Check ``data`` against ``ref`` and ``policy``; return what it contains or raise ``ModelRefused``."""
+    policy = policy or ModelPolicy()
+    check_ref_format(ref)
+    if len(data) > policy.max_size:
+        raise ModelRefused("too_large", f"the model is {len(data)} bytes, over the limit of {policy.max_size}")
+    actual = model_ref(data)
+    if actual != ref:
+        raise ModelRefused("hash_mismatch", f"the stored bytes are {actual}, not {ref}")
+
+    document, binary_length = _read_chunks(data, policy)
+    warnings: list[str] = []
+    _check_self_contained(document)
+    _check_extensions(document, policy, warnings)
+    _check_bounds(document, binary_length)
+    node_names = _node_names(document, warnings)
+    _check_extras(document, node_names)
+    stats = _stats(document)
+    _check_counts(stats, policy)
+    _check_textures(document, data, policy, warnings)
+    return ModelReport(ref=ref, size=len(data), nodes=sorted(node_names), stats=stats, warnings=warnings, joints=_joints(document))
+
+
+def _read_chunks(data: bytes, policy: ModelPolicy) -> tuple[dict[str, Any], int]:
+    """The parsed JSON chunk and the length of the binary chunk (0 when there is none)."""
+    if len(data) < 20:
+        raise ModelRefused("bad_header", "the file is shorter than a GLB header and one chunk header")
+    magic, version, declared = struct.unpack_from("<III", data, 0)
+    if magic != GLB_MAGIC:
+        raise ModelRefused("bad_header", "the file does not start with the glTF magic; only binary glTF (.glb) is stored")
+    if version != 2:
+        raise ModelRefused("bad_header", f"the container version is {version}, only 2 is supported")
+    if declared != len(data):
+        raise ModelRefused("bad_header", f"the header declares {declared} bytes but the file has {len(data)}")
+
+    json_length, json_type = struct.unpack_from("<II", data, 12)
+    if json_type != CHUNK_JSON:
+        raise ModelRefused("bad_structure", "the first chunk is not the JSON chunk")
+    if json_length > policy.max_json:
+        raise ModelRefused("bad_structure", f"the JSON chunk is {json_length} bytes, over the limit of {policy.max_json}")
+    json_end = 20 + json_length
+    if json_end > len(data):
+        raise ModelRefused("bad_structure", "the JSON chunk runs past the end of the file")
+    try:
+        document = json.loads(data[20:json_end].decode("utf-8"))
+    except (UnicodeDecodeError, ValueError) as error:
+        raise ModelRefused("bad_structure", f"the JSON chunk does not parse: {error}") from error
+    if not isinstance(document, dict):
+        raise ModelRefused("bad_structure", "the JSON chunk is not an object")
+    asset = document.get("asset")
+    if not isinstance(asset, dict) or asset.get("version") != "2.0":
+        raise ModelRefused("bad_structure", "asset.version must be '2.0'")
+
+    binary_length = 0
+    if json_end < len(data):
+        if json_end + 8 > len(data):
+            raise ModelRefused("bad_structure", "a chunk header is cut off after the JSON chunk")
+        binary_length, binary_type = struct.unpack_from("<II", data, json_end)
+        if binary_type != CHUNK_BIN:
+            raise ModelRefused("bad_structure", "the chunk after the JSON chunk is not the binary chunk")
+        if json_end + 8 + binary_length > len(data):
+            raise ModelRefused("bad_structure", "the binary chunk runs past the end of the file")
+    return document, binary_length
+
+
+def _items(document: dict[str, Any], key: str) -> list[dict[str, Any]]:
+    value = document.get(key, [])
+    if not isinstance(value, list) or not all(isinstance(item, dict) for item in value):
+        raise ModelRefused("bad_structure", f"'{key}' must be a list of objects")
+    return value
+
+
+def _check_self_contained(document: dict[str, Any]) -> None:
+    for key in ("buffers", "images"):
+        for index, item in enumerate(_items(document, key)):
+            if "uri" in item:
+                raise ModelRefused("external_reference", f"{key}[{index}] has a uri; a model carries all its data in its binary chunk")
+
+
+def _check_extensions(document: dict[str, Any], policy: ModelPolicy, warnings: list[str]) -> None:
+    required = document.get("extensionsRequired", [])
+    used = document.get("extensionsUsed", [])
+    if not isinstance(required, list) or not isinstance(used, list):
+        raise ModelRefused("bad_structure", "extensionsRequired and extensionsUsed must be lists")
+    refused = sorted(set(required) - policy.extensions)
+    if refused:
+        raise ModelRefused("unsupported_extension", f"the model requires extensions that are not allowed: {refused}")
+    ignored = sorted(set(used) - set(required) - policy.extensions)
+    if ignored:
+        warnings.append(f"extensions used but not supported are ignored by viewers: {ignored}")
+
+
+def _is_fallback_buffer(buffer: dict[str, Any]) -> bool:
+    """A meshopt fallback buffer has a length but no data in the file."""
+    extension = buffer.get("extensions", {}).get("EXT_meshopt_compression")
+    return isinstance(extension, dict) and extension.get("fallback") is True
+
+
+def _span(item: dict[str, Any], what: str) -> tuple[int, int]:
+    offset, length = item.get("byteOffset", 0), item.get("byteLength")
+    if not isinstance(offset, int) or not isinstance(length, int) or offset < 0 or length < 0:
+        raise ModelRefused("bad_structure", f"{what} needs a non-negative integer byteOffset and byteLength")
+    return offset, length
+
+
+def _check_bounds(document: dict[str, Any], binary_length: int) -> None:
+    buffers = _items(document, "buffers")
+    views = _items(document, "bufferViews")
+    for index, buffer in enumerate(buffers):
+        if _is_fallback_buffer(buffer):
+            continue
+        if index != 0:
+            raise ModelRefused("bad_structure", f"buffers[{index}] has no data: only the first buffer is the binary chunk")
+        _, length = _span(buffer, "buffers[0]")
+        if length > binary_length:
+            raise ModelRefused("bad_structure", f"buffers[0] declares {length} bytes but the binary chunk has {binary_length}")
+
+    def check_view(what: str, source: dict[str, Any]) -> None:
+        buffer_index = source.get("buffer")
+        if not isinstance(buffer_index, int) or not 0 <= buffer_index < len(buffers):
+            raise ModelRefused("bad_structure", f"{what} names a buffer that does not exist")
+        offset, length = _span(source, what)
+        if offset + length > _span(buffers[buffer_index], f"buffers[{buffer_index}]")[1]:
+            raise ModelRefused("bad_structure", f"{what} runs past the end of buffers[{buffer_index}]")
+
+    for index, view in enumerate(views):
+        check_view(f"bufferViews[{index}]", view)
+        compressed = view.get("extensions", {}).get("EXT_meshopt_compression")
+        if isinstance(compressed, dict):
+            check_view(f"bufferViews[{index}] (compressed)", compressed)
+
+    for index, accessor in enumerate(_items(document, "accessors")):
+        count = accessor.get("count")
+        if not isinstance(count, int) or count < 0:
+            raise ModelRefused("bad_structure", f"accessors[{index}] needs a non-negative integer count")
+        view_index = accessor.get("bufferView")
+        if view_index is None:
+            continue
+        if not isinstance(view_index, int) or not 0 <= view_index < len(views):
+            raise ModelRefused("bad_structure", f"accessors[{index}] names a bufferView that does not exist")
+        component_type = accessor.get("componentType")
+        kind = accessor.get("type")
+        component = _COMPONENT_BYTES.get(component_type) if isinstance(component_type, int) else None
+        components = _TYPE_COMPONENTS.get(kind) if isinstance(kind, str) else None
+        if component is None or components is None:
+            raise ModelRefused("bad_structure", f"accessors[{index}] has an unknown componentType or type")
+        element = component * components
+        view = views[view_index]
+        stride = view.get("byteStride", element)
+        offset = accessor.get("byteOffset", 0)
+        if not isinstance(stride, int) or not isinstance(offset, int) or stride < 0 or offset < 0:
+            raise ModelRefused("bad_structure", f"accessors[{index}] has an invalid byteOffset or byteStride")
+        needed = offset + (stride * (count - 1) + element if count else 0)
+        if needed > _span(view, f"bufferViews[{view_index}]")[1]:
+            raise ModelRefused("bad_structure", f"accessors[{index}] runs past the end of bufferViews[{view_index}]")
+
+
+def _node_names(document: dict[str, Any], warnings: list[str]) -> set[str]:
+    """The names bindings can address. Unnamed nodes are fine; a repeated name is not addressable."""
+    names: set[str] = set()
+    repeated: set[str] = set()
+    unconventional: set[str] = set()
+    for node in _items(document, "nodes"):
+        name = node.get("name")
+        if not isinstance(name, str) or not name:
+            continue
+        if name in names:
+            repeated.add(name)
+        names.add(name)
+        if not NODE_NAME_PATTERN.fullmatch(name):
+            unconventional.add(name)
+    if repeated:
+        warnings.append(f"node names used more than once cannot be bound reliably: {sorted(repeated)}")
+    if unconventional:
+        warnings.append(f"node names outside [a-z0-9_]+: {sorted(unconventional)}")
+    return names
+
+
+def _number(value: object) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool) and math.isfinite(value)
+
+
+def _check_extras(document: dict[str, Any], node_names: set[str]) -> None:
+    """``extras.arkitekt``, if present, is the joint table of this schema version."""
+    extras = document.get("extras")
+    arkitekt = extras.get("arkitekt") if isinstance(extras, dict) else None
+    if arkitekt is None:
+        return
+
+    def fail(message: str) -> ModelRefused:
+        return ModelRefused("bad_extras", f"extras.arkitekt: {message}")
+
+    if not isinstance(arkitekt, dict):
+        raise fail("must be an object")
+    if arkitekt.get("version") != 1:
+        raise fail(f"version {arkitekt.get('version')!r} is not supported, only 1")
+    joints = arkitekt.get("joints", [])
+    if not isinstance(joints, list):
+        raise fail("joints must be a list")
+    source = arkitekt.get("source")
+    if source is not None and not (isinstance(source, str) and REF_PATTERN.fullmatch(source)):
+        raise fail("source must be a sha256: reference")
+
+    joint_names: set[str] = set()
+    driven: set[str] = set()
+    for index, joint in enumerate(joints):
+        where = f"joints[{index}]"
+        if not isinstance(joint, dict):
+            raise fail(f"{where} must be an object")
+        name, node, kind, axis = joint.get("name"), joint.get("node"), joint.get("type"), joint.get("axis")
+        if not isinstance(name, str) or not name:
+            raise fail(f"{where} needs a name")
+        if name in joint_names:
+            raise fail(f"joint {name!r} is defined twice")
+        joint_names.add(name)
+        if node not in node_names:
+            raise fail(f"joint {name!r} drives node {node!r}, which the model does not have")
+        if node in driven:
+            raise fail(f"node {node!r} is driven by more than one joint")
+        driven.add(node)
+        if kind not in JOINT_TYPES:
+            raise fail(f"joint {name!r} has type {kind!r}; supported are {sorted(JOINT_TYPES)}")
+        if not (isinstance(axis, list) and len(axis) == 3 and all(_number(component) for component in axis)):
+            raise fail(f"joint {name!r} needs an axis of three numbers")
+        if abs(math.sqrt(sum(component * component for component in axis)) - 1.0) > 1e-3:
+            raise fail(f"the axis of joint {name!r} is not a unit vector")
+        limit = joint.get("limit")
+        if kind == "continuous":
+            if limit is not None:
+                raise fail(f"continuous joint {name!r} has no limit")
+        else:
+            if not (isinstance(limit, dict) and _number(limit.get("lower")) and _number(limit.get("upper"))):
+                raise fail(f"joint {name!r} needs a limit with lower and upper")
+            if limit["lower"] > limit["upper"]:
+                raise fail(f"the limit of joint {name!r} has lower above upper")
+
+    for joint in joints:
+        mimic = joint.get("mimic")
+        if mimic is None:
+            continue
+        if not (isinstance(mimic, dict) and _number(mimic.get("multiplier", 1.0)) and _number(mimic.get("offset", 0.0))):
+            raise fail(f"the mimic of joint {joint['name']!r} needs a numeric multiplier and offset")
+        if mimic.get("joint") not in joint_names or mimic.get("joint") == joint["name"]:
+            raise fail(f"joint {joint['name']!r} mimics {mimic.get('joint')!r}, which is not another joint of this model")
+
+
+def _stats(document: dict[str, Any]) -> ModelStats:
+    accessors = _items(document, "accessors")
+
+    def count_of(index: object) -> int:
+        if not isinstance(index, int) or not 0 <= index < len(accessors):
+            raise ModelRefused("bad_structure", "a mesh primitive names an accessor that does not exist")
+        return int(accessors[index].get("count", 0))
+
+    triangles = 0
+    for mesh in _items(document, "meshes"):
+        primitives = mesh.get("primitives", [])
+        if not isinstance(primitives, list):
+            raise ModelRefused("bad_structure", "mesh primitives must be a list")
+        for primitive in primitives:
+            if not isinstance(primitive, dict):
+                raise ModelRefused("bad_structure", "a mesh primitive must be an object")
+            mode = primitive.get("mode", 4)
+            if mode not in (4, 5, 6):
+                continue
+            attributes = primitive.get("attributes", {})
+            if "indices" in primitive:
+                vertices = count_of(primitive["indices"])
+            elif isinstance(attributes, dict) and "POSITION" in attributes:
+                vertices = count_of(attributes["POSITION"])
+            else:
+                continue
+            triangles += vertices // 3 if mode == 4 else max(vertices - 2, 0)
+
+    return ModelStats(
+        nodes=len(_items(document, "nodes")),
+        triangles=triangles,
+        textures=len(_items(document, "images")),
+        animations=len(_items(document, "animations")),
+    )
+
+
+def _check_counts(stats: ModelStats, policy: ModelPolicy) -> None:
+    for what, value, limit in (
+        ("nodes", stats.nodes, policy.max_nodes),
+        ("triangles", stats.triangles, policy.max_triangles),
+        ("animation clips", stats.animations, policy.max_animations),
+    ):
+        if value > limit:
+            raise ModelRefused("over_budget", f"the model has {value} {what}, over the limit of {limit}")
+
+
+def _joints(document: dict[str, Any]) -> list[dict[str, Any]]:
+    extras = document.get("extras")
+    arkitekt = extras.get("arkitekt") if isinstance(extras, dict) else None
+    return list(arkitekt.get("joints", [])) if isinstance(arkitekt, dict) else []
+
+
+def image_size(data: bytes) -> tuple[int, int] | None:
+    """Width and height from a PNG, JPEG or WebP header; ``None`` for anything else."""
+    if len(data) >= 24 and data[:8] == b"\x89PNG\r\n\x1a\n":
+        return struct.unpack(">II", data[16:24])
+    if len(data) >= 4 and data[:2] == b"\xff\xd8":
+        offset = 2
+        while offset + 9 < len(data):
+            if data[offset] != 0xFF:
+                return None
+            marker = data[offset + 1]
+            (length,) = struct.unpack(">H", data[offset + 2 : offset + 4])
+            if 0xC0 <= marker <= 0xCF and marker not in (0xC4, 0xC8, 0xCC):
+                height, width = struct.unpack(">HH", data[offset + 5 : offset + 9])
+                return width, height
+            offset += 2 + length
+        return None
+    if len(data) >= 30 and data[:4] == b"RIFF" and data[8:12] == b"WEBP":
+        kind = data[12:16]
+        if kind == b"VP8X":
+            return 1 + int.from_bytes(data[24:27], "little"), 1 + int.from_bytes(data[27:30], "little")
+        if kind == b"VP8 ":
+            width, height = struct.unpack("<HH", data[26:30])
+            return width & 0x3FFF, height & 0x3FFF
+        if kind == b"VP8L":
+            (bits,) = struct.unpack("<I", data[21:25])
+            return 1 + (bits & 0x3FFF), 1 + ((bits >> 14) & 0x3FFF)
+    return None
+
+
+def _check_textures(document: dict[str, Any], data: bytes, policy: ModelPolicy, warnings: list[str]) -> None:
+    """Texture sizes, read from the image headers in the binary chunk."""
+    json_length = struct.unpack_from("<I", data, 12)[0]
+    binary_offset = 20 + json_length + 8
+    views = _items(document, "bufferViews")
+    memory = 0
+    for index, image in enumerate(_items(document, "images")):
+        view_index = image.get("bufferView")
+        if not isinstance(view_index, int) or not 0 <= view_index < len(views):
+            raise ModelRefused("bad_structure", f"images[{index}] names a bufferView that does not exist")
+        offset, length = _span(views[view_index], f"bufferViews[{view_index}]")
+        size = image_size(data[binary_offset + offset : binary_offset + offset + length])
+        if size is None:
+            warnings.append(f"images[{index}] is not a PNG, JPEG or WebP whose size can be read")
+            continue
+        width, height = size
+        if max(width, height) > policy.max_texture_size:
+            raise ModelRefused("over_budget", f"images[{index}] is {width} x {height}, over the limit of {policy.max_texture_size} px per side")
+        memory += width * height * 4
+    if memory > policy.max_texture_memory:
+        raise ModelRefused("over_budget", f"textures decode to {memory} bytes, over the limit of {policy.max_texture_memory}")

kulisse-1.0.1/pyproject.toml

@@ -0,0 +1,90 @@
+[project]
+name = "kulisse"
+dynamic = ["version"]
+description = "device and scene models for arkitekt: self-contained binary glTF with a joint table, authored from URDF and checked before upload"
+authors = [{ name = "jhnnsrs", email = "jhnnsrs@gmail.com" }]
+requires-python = ">=3.11"
+readme = "README.md"
+license = "MIT"
+# Checking a model, its reference and its blok snippet need nothing but the standard library:
+# a viewer, a CI job or a server-side tool can hold a GLB to the rules without numpy.
+dependencies = []
+
+[project.urls]
+Repository = "https://github.com/arkitektio/kulisse"
+Specification = "https://github.com/arkitektio/kulisse/blob/main/KULISSE.md"
+
+[project.optional-dependencies]
+# Importing a URDF or Xacro: trimesh builds the primitives and loads mesh files (pycollada for
+# .dae), numpy carries the transforms, xacro expands macros.
+urdf = ["numpy>=1.26", "pycollada>=0.8", "trimesh>=4", "xacro>=2"]
+complete = ["numpy>=1.26", "pycollada>=0.8", "trimesh>=4", "xacro>=2"]
+
+[project.scripts]
+kulisse = "kulisse.cli:main"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.3.5",
+    "pytest-cov>=6.1.1",
+    "python-semantic-release>=9.21.0",
+    "ruff>0.11",
+    "basedpyright>=1.21",
+]
+
+[tool.hatch.build.targets.sdist]
+include = ["kulisse"]
+
+[tool.hatch.build.targets.wheel]
+include = ["kulisse"]
+
+[tool.basedpyright]
+include = ["kulisse"]
+exclude = ["**/__pycache__", "tests"]
+typeCheckingMode = "strict"
+# trimesh and xacro ship no type information, so values that come back through them are Unknown
+# whatever kulisse annotates; every other strict rule stays on.
+reportUnknownMemberType = false
+reportUnknownArgumentType = false
+reportUnknownVariableType = false
+reportUnknownParameterType = false
+reportMissingTypeStubs = false
+
+[tool.ruff.lint]
+extend-select = ["ANN", "D1"]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["ANN001", "ANN201", "ANN202", "ANN206", "ANN401", "D1", "RUF100"]
+
+[tool.ruff]
+line-length = 140
+
+[tool.semantic_release]
+# Tag-only releases, as fabriks: the version lives in the git tag, hatch-vcs reads it at build
+# time, and PSR is told the new version explicitly so the build is not a .devN local version.
+build_command = """
+    python -m pip install 'uv>=0.7.12'
+    export SETUPTOOLS_SCM_PRETEND_VERSION="$NEW_VERSION"
+    uv build
+"""
+
+[tool.semantic_release.branches.main]
+match = "main"
+prerelease = false
+
+[tool.semantic_release.branches.next]
+match = "next"
+prerelease = true
+prerelease_token = "rc"
+
+[tool.semantic_release.branches.maintenance]
+match = '^\d+\.x$'
+prerelease = false
+
+[build-system]
+requires = ["hatchling", "hatch-vcs"]
+build-backend = "hatchling.build"
+
+[tool.hatch.version]
+source = "vcs"
+fallback-version = "0.0.0"