simready-forge 0.1.0__py3-none-any.whl

simready_forge/kit.py

@@ -0,0 +1,1047 @@
+"""The asset model: build123d shapes and generated scans become rigid bodies with materials, physics materials,
+colliders, mass and joints, saved as an NVIDIA SimReady (Robotics-Prop 4.0.0) USD package and exported to URDF and GLB.
+
+    from simready_forge import Asset
+    asset = Asset('desk_lamp', 'simready_assets', label='desk lamp', qcode='Q3216816', units='mm')
+    steel = asset.material('steel', color=(0.12, 0.12, 0.13), metallic=1.0, roughness=0.35,
+                           friction=(0.6, 0.5), restitution=0.2, density=7850, nonvisual=('steel', 'paint'))
+    base, arm = asset.body('base'), asset.body('arm')
+    asset.add(base, 'disc', base_shape, steel)
+    asset.add(arm, 'link', link_shape, steel)
+    asset.revolute('shoulder', base, arm, anchor=(0, 0, 40), axis='Y', limits=(-30, 75))
+    asset.save()                       # formats=('usd', 'urdf', 'glb') by default
+
+Layout under out_dir: <name>/usd/<name>.usda is the SimReady package (textures and thumbnail beside it);
+<name>_exports/ holds the URDF and GLB; <name>_reports/ holds structure.json and the validator, review and cost reports.
+"""
+
+import datetime
+import json
+import math
+import re
+import shutil
+import sys
+from pathlib import Path
+
+import numpy as np
+
+from .scan import UNITS
+
+AXES = ("X", "Y", "Z")
+G = 9.81  # m/s^2
+HULL_POINTS = 64  # PhysX's default vertex limit for a convex hull
+DEFAULT_COLOUR = (0.7, 0.7, 0.7)
+COLLIDERS = ("convex_hull", "convex_decomposition", "box", "none")
+FORMATS = ("usd", "urdf", "glb")
+PROJECTIONS = ("box", "fit", "cylinder")
+PROFILE, PROFILE_VERSION = "Robotics-Prop", "4.0.0"
+# NVIDIA's non-visual (sensor) material tokens, from the SimReady FET_007 requirements
+METAL_BASES = frozenset(  # the sensor bases (all in NONVISUAL_BASES) that are metals
+    {"aluminum", "steel", "oxidized_steel", "iron", "oxidized_iron", "silver", "brass", "bronze", "tin"}
+    | {"oxidized_Bronze_Patina"}
+)
+NONVISUAL_BASES = frozenset(
+    {
+        "aluminum",
+        "steel",
+        "oxidized_steel",
+        "iron",
+        "oxidized_iron",
+        "silver",
+        "brass",
+        "bronze",
+        "oxidized_Bronze_Patina",
+        "tin",
+        "plastic",
+        "fiberglass",
+        "carbon_fiber",
+        "vinyl",
+        "plexiglass",
+        "pvc",
+        "nylon",
+        "polyester",
+        "clear_glass",
+        "frosted_glass",
+        "one_way_mirror",
+        "mirror",
+        "ceramic_glass",
+        "asphalt",
+        "concrete",
+        "leaf_grass",
+        "dead_leaf_grass",
+        "rubber",
+        "wood",
+        "bark",
+        "cardboard",
+        "paper",
+        "fabric",
+        "skin",
+        "fur_hair",
+        "leather",
+        "marble",
+        "brick",
+        "stone",
+        "gravel",
+        "dirt",
+        "mud",
+        "water",
+        "salt_water",
+        "snow",
+        "ice",
+        "calibration_lambertian",
+    }
+)
+NONVISUAL_COATINGS = frozenset({"none", "paint", "clearcoat", "paint_clearcoat"})
+
+
+def ident(name):
+    """A valid USD prim name."""
+    name = re.sub(r"[^A-Za-z0-9_]", "_", str(name)) or "prim"
+    return "_" + name if name[0].isdigit() else name
+
+
+class Material:
+    def __init__(self, name, **kw):
+        self.name = ident(name)
+        self.color = tuple(kw["color"])
+        self.metallic, self.roughness, self.opacity, self.ior = (
+            kw["metallic"],
+            kw["roughness"],
+            kw["opacity"],
+            kw["ior"],
+        )
+        self.texture, self.uv_scale, self.lengthwise = kw["texture"], kw["uv_scale"], kw.get("lengthwise", False)
+        self.projection = kw.get("projection", "box")
+        self.axis = kw.get("axis", "Z")  # the axis a 'cylinder' projection wraps round
+        self.friction, self.restitution, self.density = tuple(kw["friction"]), kw["restitution"], kw["density"]
+        self.label, self.nonvisual = kw["label"], kw["nonvisual"]
+        self.metal_rough_texture = self.normal_texture = None
+        self.map_metallic = True  # take metallic from the metal_rough map's B channel, not only roughness
+        self.files = {}  # texture files save() wrote, for the exporters
+
+
+class Body:
+    def __init__(self, name, label, mass, com=None):
+        self.name, self.label, self.mass, self.com, self.parts = ident(name), label, mass, com, []
+
+
+class Asset:
+    def __init__(
+        self,
+        name,
+        out_dir,
+        label,
+        qcode,
+        units="mm",
+        description="",
+        category="prop",
+        author="simready-forge",
+        license="Proprietary",
+    ):
+        if units not in UNITS:
+            raise ValueError(f"units must be one of {list(UNITS)}")
+        if not re.fullmatch(r"Q\d+", qcode or ""):
+            raise ValueError("qcode must look like 'Q12345' (simready-forge qcode \"<object>\")")
+        self.name, self.label, self.qcode, self.scale = ident(name), label, qcode, UNITS[units]
+        self.description, self.category, self.author, self.license = description, category, author, license
+        self.out_dir = Path(out_dir)
+        self.root = self.out_dir / self.name
+        self.reports = self.out_dir / f"{self.name}_reports"
+        self.exports = self.out_dir / f"{self.name}_exports"
+        self.materials, self.bodies, self.joints, self.scans = [], [], [], []
+
+    # ------------------------------------------------------------------ declaring the asset
+    def material(
+        self,
+        name,
+        color=DEFAULT_COLOUR,
+        metallic=0.0,
+        roughness=0.5,
+        opacity=1.0,
+        ior=1.5,
+        texture=None,
+        uv_scale=1.0,
+        friction=(0.5, 0.4),
+        restitution=0.1,
+        density=1000.0,
+        label=None,
+        nonvisual=None,
+        lengthwise=False,
+        projection="box",
+        axis="Z",
+    ):
+        """Visual (UsdPreviewSurface) and physics material. density in kg/m^3, friction = (static, dynamic).
+
+        texture: an image path, PIL image or HxWx3 uint8 array for the base colour; uv_scale = repeats per metre.
+        lengthwise: the texture's width (u) runs along each part's longer side on every face, as grain runs along a
+        board; otherwise u follows the first axis across the face (X, else Y).
+        projection: 'box' repeats the texture every 1/uv_scale metres, projected from the asset's position (wood,
+        metal, fabric); 'fit' maps it once across each face of each part (a dial face, a sign, a decal); 'cylinder'
+        wraps it once round each part about Z and once up it (a bottle's label, a can, a drum), the image's centre
+        facing the front (-Y) and its edges meeting at the back, its ends mapped as with 'fit'. For 'cylinder' draw
+        the image as wide as the part's circumference is to its height. axis: what 'cylinder' wraps round: 'Z', or
+        'X' (a drum on its side: the image's middle still faces the front) or 'Y' (a lens ring: its middle faces up);
+        the image's width goes round the part and its height along the axis.
+        nonvisual: (base, coating) for sensor simulation, e.g. ('steel', 'paint'); see NONVISUAL_BASES.
+        """
+        if projection not in PROJECTIONS:
+            raise ValueError(f"projection must be one of {PROJECTIONS}")
+        if axis not in ("X", "Y", "Z"):
+            raise ValueError("axis must be 'X', 'Y' or 'Z'")
+        if nonvisual is not None and (nonvisual[0] not in NONVISUAL_BASES or nonvisual[1] not in NONVISUAL_COATINGS):
+            raise ValueError(
+                f"nonvisual={nonvisual!r}: base must be one of NONVISUAL_BASES, "
+                f"coating one of {sorted(NONVISUAL_COATINGS)}"
+            )
+        material = Material(
+            name,
+            color=color,
+            metallic=metallic,
+            roughness=roughness,
+            opacity=opacity,
+            ior=ior,
+            texture=texture,
+            uv_scale=uv_scale,
+            lengthwise=lengthwise,
+            projection=projection,
+            axis=axis,
+            friction=friction,
+            restitution=restitution,
+            density=density,
+            label=label or name,
+            nonvisual=nonvisual,
+        )
+        self.materials.append(material)
+        return material
+
+    def scan_material(
+        self,
+        scan,
+        name,
+        friction=(0.5, 0.4),
+        restitution=0.1,
+        density=1000.0,
+        label=None,
+        nonvisual=None,
+        opacity=1.0,
+        color=None,
+        metallic=None,
+        roughness=None,
+        ior=1.5,
+        textured=True,
+        normal=True,
+    ):
+        """A material for a scan's faces. By default it keeps the scan's own PBR textures (base colour, metallic and
+        roughness, normal map).
+
+        textured=False drops the base-colour texture for a flat `color` (the texture's average when None): for a
+        frosted shade, glass or a paint the generator baked its lighting into. A number for metallic or roughness
+        replaces the scan's metallic-roughness map with these values (the other one 0, or 0.5 for roughness).
+        normal=False drops the scan's normal map: a generated mesh's surface noise makes clear plastic or glass refract
+        like crumpled foil.
+        """
+        base = scan.images.get("base")
+        if color is None:
+            color = _linear(_mean_colour(base)) if base is not None and not textured else DEFAULT_COLOUR
+        material = self.material(
+            name,
+            color=color,
+            metallic=metallic if metallic is not None else 0.0,
+            roughness=roughness if roughness is not None else 0.5,
+            opacity=opacity,
+            ior=ior,
+            texture=base if textured else None,
+            friction=friction,
+            restitution=restitution,
+            density=density,
+            label=label,
+            nonvisual=nonvisual,
+        )
+        own_maps = metallic is None and roughness is None
+        material.metal_rough_texture = scan.images.get("metal_rough") if own_maps else None
+        # TRELLIS.2 often writes metallic ~1 everywhere: only a metal keeps the map's metallic, the rest keep its
+        # roughness and take metallic 0 (or the value given)
+        material.map_metallic = metallic is None and nonvisual is not None and nonvisual[0] in METAL_BASES
+        material.normal_texture = scan.images.get("normal") if normal else None
+        return material
+
+    def body(self, name, label=None, mass=None, com=None):
+        """A rigid body. mass in kg; when None it is the sum of part volume x material density.
+
+        com: its centre of mass (model units, asset frame); when None, the volume x density weighted centre of its
+        visible parts, so a part with no collider (a bulb, a socket) still counts.
+        """
+        com = None if com is None else np.array(com, dtype=float) * self.scale
+        body = Body(name, label or name, mass, com)
+        self.bodies.append(body)
+        return body
+
+    def add(
+        self, body, name, shape, material, collider="convex_hull", label=None, tolerance=None, visible=True, angular=0.2
+    ):
+        """Add a build123d shape (model units, assembled pose) to a body.
+
+        collider: convex_hull (default), convex_decomposition (concave parts: bins, cups, frames, hooks), box, none.
+        visible=False: a collider only, never rendered or exported as a visual (a drum's flat-bottomed rim, a wheel's
+        polygon): the material still gives it friction and density.
+        tolerance: how far the triangles may stray from the surface (model units; 0.4 mm by default); angular: the
+        most a curve turns between two triangles' edges, in radians, which sets the segments round a large tube.
+        """
+        if collider not in COLLIDERS:
+            raise ValueError(f"collider must be one of {COLLIDERS}")
+        if not visible and collider == "none":
+            raise ValueError(f"part {name}: an invisible part with no collider is nothing")
+        verts, tris = shape.tessellate(tolerance or 0.0004 / self.scale, angular)
+        points = np.array([[v.X, v.Y, v.Z] for v in verts], dtype=float) * self.scale
+        tris = np.array(tris, dtype=int).reshape(-1, 3)
+        if not len(tris):
+            raise ValueError(f"part {name} tessellated to nothing")
+        body.parts.append(
+            {
+                "name": ident(name),
+                "points": points,
+                "tris": tris,
+                "material": material,
+                "volume": abs(float(shape.volume)) * self.scale**3,
+                "collider": collider,
+                "label": label or name,
+                "uv": None,
+                "normals": None,
+                "visible": visible,
+            }
+        )
+
+    def add_scan(self, body, name, scan, faces, material, collider="convex_hull", label=None):
+        """Add the selected faces (a mask from scan.faces_in or scan.remaining) of a scan to a body.
+
+        collider: convex_hull (default; split a concave part into several add_scan calls instead), box, none, or
+        convex_decomposition for a small concave piece (slow, minutes or more, on a large generated mesh).
+        """
+        import trimesh
+
+        faces = np.asarray(faces, dtype=bool)
+        if not faces.any():
+            raise ValueError(f"scan part {name}: no faces selected (check the box against scan.views())")
+        scan.used |= faces
+        if scan not in self.scans:
+            self.scans.append(scan)
+        used, inverse = np.unique(scan.tris[faces], return_inverse=True)
+        points, local = scan.points[used] * scan.scale, inverse.reshape(-1, 3)
+        piece = trimesh.Trimesh(points, local, process=False)
+        volume = abs(piece.volume) if piece.is_watertight else 0.6 * piece.convex_hull.volume
+        uv = scan.uv.reshape(-1, 3, 2)[faces].reshape(-1, 2) if scan.uv is not None else None
+        body.parts.append(
+            {
+                "name": ident(name),
+                "points": points,
+                "tris": local,
+                "material": material,
+                "volume": volume,
+                "collider": collider,
+                "label": label or name,
+                "uv": uv,
+                "normals": scan.normals[used],
+                "estimated_volume": not piece.is_watertight,
+            }
+        )
+
+    def _joint(self, kind, name, body0, body1, anchor, axis, limits, drive, label):
+        if axis not in AXES:
+            raise ValueError("axis must be 'X', 'Y' or 'Z' (asset frame)")
+        if limits[0] >= limits[1]:
+            raise ValueError(f"joint {name}: lower limit must be below the upper limit")
+        if drive["stiffness"] is not None and drive["hold"] is not None:
+            raise ValueError(f"joint {name}: give stiffness or hold, not both")
+        self.joints.append(
+            {
+                "kind": kind,
+                "name": ident(name),
+                "body0": body0,
+                "body1": body1,
+                "anchor": np.array(anchor, dtype=float) * self.scale,
+                "axis": axis,
+                "limits": limits,
+                "given": drive,
+                "label": label or name,
+            }
+        )
+
+    def revolute(
+        self, name, body0, body1, anchor, axis, limits, damping=None, stiffness=None, hold=None, loose=False, label=None
+    ):
+        """Hinge about the asset-frame axis through anchor (model units). limits in degrees from the modelled pose,
+        within one turn (PhysX wraps a drive target past 360 degrees); None for a free spin (a wheel, a free knob).
+
+        hold (degrees): the joint holds its pose, sagging at most this far under gravity in any pose: the kit springs
+        it back to the modelled pose with a stiffness sized to the load it carries (its child body and everything
+        jointed beyond it). Or give stiffness (N*m/deg) yourself. Without either the joint swings free.
+        damping (N*m*s/deg): sized to the load when None, so a push the size of the load's own weight turns it fast.
+        loose=True: it swings free on purpose (a lace end, a pendulum, a chain link), so no warning that gravity takes
+        it to a limit.
+        """
+        drive = {"damping": damping, "stiffness": stiffness, "hold": hold, "loose": loose}
+        limits = (-math.inf, math.inf) if limits is None else limits
+        self._joint("revolute", name, body0, body1, anchor, axis, limits, drive, label)
+
+    def prismatic(
+        self, name, body0, body1, anchor, axis, limits, damping=None, stiffness=None, hold=None, loose=False, label=None
+    ):
+        """Slide along the asset-frame axis. limits in model units from the modelled pose.
+
+        hold (model units): the slide holds its pose, sagging at most this far under gravity. Or give stiffness (N/m),
+        such as a button's return spring. damping (N*s/m): sized to the load when None.
+        """
+        limits = (limits[0] * self.scale, limits[1] * self.scale)
+        hold = None if hold is None else hold * self.scale
+        drive = {"damping": damping, "stiffness": stiffness, "hold": hold, "loose": loose}
+        self._joint("prismatic", name, body0, body1, anchor, axis, limits, drive, label)
+
+    # ------------------------------------------------------------------ writing
+    def save(self, formats=FORMATS):
+        """Write the SimReady package and the requested exports; return the .usda path."""
+        unknown = set(formats) - set(FORMATS)
+        if unknown:
+            raise ValueError(f"unknown formats {sorted(unknown)}; choose from {FORMATS}")
+        path, model, warnings = self._write_usd()
+        self.reports.mkdir(parents=True, exist_ok=True)
+        files: dict[str, object] = {"usd": str(path.resolve())}
+        if "urdf" in formats or "glb" in formats:
+            from . import export
+
+            if "urdf" in formats:
+                files["urdf"] = [str(p) for p in export.urdf(model, self.exports / "urdf", warnings)]
+            if "glb" in formats:
+                files["glb"] = str(export.glb(model, self.exports / f"{self.name}.glb"))
+        structure = {
+            "name": self.name,
+            "label": self.label,
+            "qcode": self.qcode,
+            "description": self.description,
+            "size_m": model["size_m"],
+            "mass_kg": model["mass_kg"],
+            "triangles": model["triangles"],
+            "bodies": [
+                {
+                    "name": b["name"],
+                    "label": b["label"],
+                    "mass_kg": round(b["mass"], 4),
+                    "parts": [p["name"] for p in b["parts"]],
+                    # 'box' and 'convex_hull' are written as convex mesh colliders (PhysicsMeshCollisionAPI convexHull)
+                    "colliders": {p["name"]: p["collider"] for p in b["parts"]},
+                    "hidden": [p["name"] for p in b["parts"] if not p.get("visible", True)],  # colliders only
+                    "materials": {p["name"]: p["material"].name for p in b["parts"]},
+                }
+                for b in model["bodies"]
+            ],
+            "joints": [
+                {
+                    "name": j["name"],
+                    "kind": j["kind"],
+                    "parent": j["body0"].name,
+                    "child": j["body1"].name,
+                    "axis": j["axis"],
+                    "anchor_m": np.round(j["anchor"], 5).tolist(),
+                    "limits": [x if math.isfinite(x) else None for x in j["limits"]],  # None: free
+                    "limit_units": "deg" if j["kind"] == "revolute" else "m",
+                    **j["drive"],
+                }
+                for j in self.joints
+            ],
+            "materials": [
+                {
+                    "name": m.name,
+                    "label": m.label,
+                    "color": list(m.color),
+                    # a scan's metallic-roughness map, when bound, wins over the numbers
+                    "metallic": "texture" if m.metal_rough_texture is not None and m.map_metallic else m.metallic,
+                    "roughness": "texture" if m.metal_rough_texture is not None else m.roughness,
+                    "normal_map": m.normal_texture is not None,
+                    "opacity": m.opacity,
+                    "ior": m.ior,
+                    "textured": m.texture is not None,
+                    "friction": list(m.friction),
+                    "restitution": m.restitution,
+                    "density": m.density,
+                    "nonvisual": list(m.nonvisual) if m.nonvisual else None,
+                }
+                for m in self.materials
+            ],
+            "files": files,
+            "warnings": warnings,
+        }
+        (self.reports / "structure.json").write_text(json.dumps(structure, indent=1, default=str), encoding="utf-8")
+        print(
+            json.dumps(
+                {
+                    "usd": files["usd"],
+                    "size_m": structure["size_m"],
+                    "mass_kg": structure["mass_kg"],
+                    "bodies": {b["name"]: len(b["parts"]) for b in structure["bodies"]},
+                    "joints": [
+                        f"{j['name']} ({j['kind']} {j['axis']}, {j['parent']}->{j['child']})"
+                        for j in structure["joints"]
+                    ],
+                    "triangles": structure["triangles"],
+                    "warnings": warnings,
+                },
+                indent=1,
+            )
+        )
+        return path
+
+    def _write_usd(self):
+        from pxr import Gf, Sdf, Usd, UsdGeom, UsdPhysics, UsdShade, Vt
+
+        from .preview import thumbnail
+
+        T = Sdf.ValueTypeNames
+        usd_dir = self.root / "usd"
+        shutil.rmtree(
+            usd_dir / "textures", ignore_errors=True
+        )  # the kit's own folder: no texture of an old build ships
+        (usd_dir / "textures").mkdir(parents=True, exist_ok=True)
+        (usd_dir / ".thumbs" / "256x256").mkdir(parents=True, exist_ok=True)
+        path = usd_dir / f"{self.name}.usda"
+        warnings: list[str] = []
+
+        def vec(a):
+            return Gf.Vec3f(*[float(x) for x in a])
+
+        def labels(prim, **values):
+            for instance, value in values.items():
+                prim.AddAppliedSchema(f"SemanticsLabelsAPI:{instance}")
+                prim.CreateAttribute(f"semantics:labels:{instance}", T.TokenArray).Set([str(value)])
+
+        def display_colour(gprim, rgb):
+            gprim.CreateDisplayColorPrimvar(UsdGeom.Tokens.constant).Set(Vt.Vec3fArray([vec(rgb[:3])]))
+
+        stage = Usd.Stage.CreateInMemory()
+        UsdGeom.SetStageUpAxis(stage, UsdGeom.Tokens.z)
+        UsdGeom.SetStageMetersPerUnit(stage, 1.0)
+        stage.SetMetadata("kilogramsPerUnit", 1.0)
+        root = UsdGeom.Xform.Define(stage, f"/{self.name}")
+        stage.SetDefaultPrim(root.GetPrim())
+        root.GetPrim().SetMetadata("kind", "component")
+        labels(root.GetPrim(), **{"class": self.label, "wikidata_qcode": self.qcode})
+        if self.joints:
+            UsdPhysics.ArticulationRootAPI.Apply(root.GetPrim())
+
+        UsdGeom.Scope.Define(stage, f"/{self.name}/Looks")
+        shaders, swatches = {}, {}
+        for m in self.materials:
+            mat = UsdShade.Material.Define(stage, f"/{self.name}/Looks/{m.name}")
+            labels(mat.GetPrim(), material=m.label)
+            phys = UsdPhysics.MaterialAPI.Apply(mat.GetPrim())
+            phys.CreateStaticFrictionAttr(float(m.friction[0]))
+            phys.CreateDynamicFrictionAttr(float(m.friction[1]))
+            phys.CreateRestitutionAttr(float(m.restitution))
+            phys.CreateDensityAttr(float(m.density))
+            if m.restitution >= 0.5:  # bouncy: PhysX averages by default, halving it against a dead floor
+                mat.GetPrim().AddAppliedSchema("PhysxMaterialAPI")
+                mat.GetPrim().CreateAttribute("physxMaterial:restitutionCombineMode", T.Token).Set("max")
+            if m.nonvisual:
+                prim = mat.GetPrim()
+                prim.CreateAttribute("omni:simready:nonvisual:base", T.Token, custom=True).Set(m.nonvisual[0])
+                prim.CreateAttribute("omni:simready:nonvisual:coating", T.Token, custom=True).Set(m.nonvisual[1])
+                prim.CreateAttribute("omni:simready:nonvisual:attributes", T.TokenArray, custom=True).Set(
+                    list(m.nonvisual[2]) if len(m.nonvisual) > 2 else ["none"]
+                )
+            surface = UsdShade.Shader.Define(stage, f"{mat.GetPath()}/PreviewSurface")
+            surface.CreateIdAttr("UsdPreviewSurface")
+            surface.CreateInput("useSpecularWorkflow", T.Int).Set(0)
+            surface.CreateInput("opacity", T.Float).Set(float(m.opacity))
+            surface.CreateInput("ior", T.Float).Set(float(m.ior))
+            swatches[m.name] = m.color
+            textures = _TextureNodes(stage, mat, m, usd_dir / "textures", T)
+            if m.texture is not None:
+                surface.CreateInput("diffuseColor", T.Color3f).ConnectToSource(
+                    textures.add("base_color", m.texture, "sRGB", "rgb", T.Float3)
+                )
+                swatches[m.name] = _linear(_mean_colour(m.files["base_color"]))  # displayColor is linear
+                if m.color == DEFAULT_COLOUR:  # viewers that drop textures (URDF, some GLB) show the texture's average
+                    m.color = swatches[m.name]
+            else:
+                surface.CreateInput("diffuseColor", T.Color3f).Set(vec(m.color))
+            if m.metal_rough_texture is not None:  # glTF packing: G = roughness, B = metallic
+                surface.CreateInput("roughness", T.Float).ConnectToSource(
+                    textures.add("metal_rough", m.metal_rough_texture, "raw", "g", T.Float)
+                )
+                if m.map_metallic:
+                    metal = UsdShade.Shader.Get(stage, f"{mat.GetPath()}/metal_rough_texture").CreateOutput(
+                        "b", T.Float
+                    )
+                    surface.CreateInput("metallic", T.Float).ConnectToSource(metal)
+                else:
+                    surface.CreateInput("metallic", T.Float).Set(float(m.metallic))
+            else:
+                surface.CreateInput("metallic", T.Float).Set(float(m.metallic))
+                surface.CreateInput("roughness", T.Float).Set(float(m.roughness))
+            if m.normal_texture is not None:
+                surface.CreateInput("normal", T.Normal3f).ConnectToSource(
+                    textures.add("normal", m.normal_texture, "raw", "rgb", T.Float3, ((2, 2, 2, 1), (-1, -1, -1, 0)))
+                )
+            mat.CreateSurfaceOutput().ConnectToSource(surface.CreateOutput("surface", T.Token))
+            shaders[m.name] = mat
+
+        origins, boxes, preview, model_bodies, total_mass, triangles = {}, {}, [], [], 0.0, 0
+        for body in self.bodies:
+            if not body.parts:
+                raise ValueError(f"body {body.name} has no parts")
+            allpts = np.vstack([p["points"] for p in body.parts])
+            lo, hi = allpts.min(0), allpts.max(0)
+            origin = (lo + hi) / 2
+            origins[body.name], boxes[body.name] = origin, (lo, hi)
+            xf = UsdGeom.Xform.Define(stage, f"/{self.name}/{body.name}")
+            xf.AddTranslateOp().Set(Gf.Vec3d(*[float(x) for x in origin]))
+            labels(xf.GetPrim(), **{"class": body.label})
+            UsdPhysics.RigidBodyAPI.Apply(xf.GetPrim())
+            mass = (  # a collider-only part stands in for geometry the visible parts already weigh
+                body.mass
+                if body.mass is not None
+                else sum(p["volume"] * p["material"].density for p in body.parts if p.get("visible", True))
+            )
+            if mass <= 0:
+                raise ValueError(f"body {body.name} has no mass")
+            if body.mass is None and any(p.get("estimated_volume") for p in body.parts):
+                warnings.append(
+                    f"body {body.name}: mass {mass:.3f} kg estimated from a non-watertight scan; "
+                    f"pass body(..., mass=kg) with the real mass"
+                )
+            mass_api = UsdPhysics.MassAPI.Apply(xf.GetPrim())
+            mass_api.CreateMassAttr(float(mass))
+            # PhysX would place the centre of mass from the colliders alone, missing collider-less parts
+            com = body.com if body.com is not None else _centre_of_mass(body.parts)
+            if com is not None:
+                mass_api.CreateCenterOfMassAttr(vec(com - origin))
+            total_mass += mass
+            model_parts = []
+            for part in body.parts:
+                m = part["material"]
+                if part["uv"] is None:  # CAD part: smooth shading and box-projected UVs
+                    pts, tris, normals = _smooth(part["points"] - origin, part["tris"])
+                    uv = _uv(pts + origin, tris, m)
+                else:  # scan part: keeps its own UVs and normals, one per triangle corner as for CAD parts
+                    pts, tris, uv = part["points"] - origin, np.asarray(part["tris"]), part["uv"]
+                    normals = np.asarray(part["normals"])[tris].reshape(-1, 3)
+                tris = np.asarray(tris)
+                if part.get("visible", True):  # an invisible part is a collider only
+                    triangles += len(tris)
+                    mesh = UsdGeom.Mesh.Define(stage, f"{xf.GetPath()}/{part['name']}")
+                    labels(mesh.GetPrim(), **{"class": part["label"]})
+                    mesh.CreateSubdivisionSchemeAttr("none")
+                    mesh.CreatePointsAttr(Vt.Vec3fArray([vec(p) for p in pts]))
+                    mesh.CreateFaceVertexCountsAttr(Vt.IntArray([3] * len(tris)))
+                    mesh.CreateFaceVertexIndicesAttr(Vt.IntArray(tris.reshape(-1).tolist()))
+                    mesh.CreateNormalsAttr(Vt.Vec3fArray([vec(n) for n in normals]))
+                    mesh.SetNormalsInterpolation(UsdGeom.Tokens.faceVarying)
+                    UsdGeom.PrimvarsAPI(mesh).CreatePrimvar("st", T.TexCoord2fArray, UsdGeom.Tokens.faceVarying).Set(
+                        Vt.Vec2fArray([Gf.Vec2f(float(u), float(v)) for u, v in uv])
+                    )
+                    mesh.CreateExtentAttr(Vt.Vec3fArray([vec(pts.min(0)), vec(pts.max(0))]))
+                    display_colour(mesh, swatches[m.name])
+                    UsdShade.MaterialBindingAPI.Apply(mesh.GetPrim()).Bind(shaders[m.name])
+                    preview.append((pts + origin, tris, swatches[m.name], m.opacity))
+                hulls = _colliders(part["points"] - origin, part["tris"], part["collider"])
+                for k, (hull_pts, hull_tris) in enumerate(hulls):
+                    col = UsdGeom.Mesh.Define(stage, f"{xf.GetPath()}/{part['name']}_collider{k if k else ''}")
+                    col.CreatePurposeAttr(UsdGeom.Tokens.guide)
+                    col.CreatePointsAttr(Vt.Vec3fArray([vec(p) for p in hull_pts]))
+                    col.CreateFaceVertexCountsAttr(Vt.IntArray([3] * len(hull_tris)))
+                    col.CreateFaceVertexIndicesAttr(Vt.IntArray(np.asarray(hull_tris).reshape(-1).tolist()))
+                    col.CreateExtentAttr(Vt.Vec3fArray([vec(hull_pts.min(0)), vec(hull_pts.max(0))]))
+                    display_colour(col, swatches[m.name])
+                    labels(col.GetPrim(), **{"class": part["label"]})
+                    UsdPhysics.CollisionAPI.Apply(col.GetPrim())
+                    UsdPhysics.MeshCollisionAPI.Apply(col.GetPrim()).CreateApproximationAttr("convexHull")
+                    col.GetPrim().AddAppliedSchema("NewtonCollisionAPI")  # the Newton runtime's mesh collider
+                    col.GetPrim().AddAppliedSchema("NewtonMeshCollisionAPI")
+                    binding = UsdShade.MaterialBindingAPI.Apply(col.GetPrim())
+                    binding.Bind(shaders[m.name])
+                    binding.Bind(shaders[m.name], UsdShade.Tokens.weakerThanDescendants, "physics")
+                model_parts.append(
+                    {
+                        "name": part["name"],
+                        "points": pts,
+                        "tris": tris,
+                        "normals": normals,
+                        "uv": uv,
+                        "material": m,
+                        "hulls": hulls,
+                        "collider": part["collider"],
+                        "visible": part.get("visible", True),
+                    }
+                )
+            model_bodies.append(
+                {"name": body.name, "label": body.label, "origin": origin, "mass": mass, "parts": model_parts}
+            )
+        for scan in self.scans:
+            left = int((~scan.used).sum())
+            if left > 0.01 * len(scan.tris):
+                warnings.append(
+                    f"{left} of {len(scan.tris)} faces of {Path(scan.path).name} are in no body "
+                    f"(dropped): add them with scan.remaining()"
+                )
+
+        if self.joints:
+            UsdGeom.Scope.Define(stage, f"/{self.name}/Joints")
+        loads = _loads(model_bodies, self.joints)
+        for j in self.joints:
+            load_mass, centre, moment = loads[j["name"]]
+            j["drive"] = _drive(j, load_mass, centre, moment, warnings)
+            b0, b1 = j["body0"].name, j["body1"].name
+            across = [i for i in range(3) if i != AXES.index(j["axis"])]  # the anchor may sit anywhere along the axis
+            for b in (b0, b1):
+                lo, hi = boxes[b]
+                pad = 0.1 * (hi - lo).max() + 0.002
+                a = j["anchor"]
+                if np.any(a[across] < lo[across] - pad) or np.any(a[across] > hi[across] + pad):
+                    warnings.append(f"joint {j['name']}: anchor {np.round(a, 4).tolist()} m is outside body {b}")
+            cls = UsdPhysics.RevoluteJoint if j["kind"] == "revolute" else UsdPhysics.PrismaticJoint
+            joint = cls.Define(stage, f"/{self.name}/Joints/{j['name']}")
+            labels(joint.GetPrim(), **{"class": j["label"]})
+            joint.CreateAxisAttr(j["axis"])
+            joint.CreateBody0Rel().SetTargets([Sdf.Path(f"/{self.name}/{b0}")])
+            joint.CreateBody1Rel().SetTargets([Sdf.Path(f"/{self.name}/{b1}")])
+            joint.CreateLocalPos0Attr(vec(j["anchor"] - origins[b0]))
+            joint.CreateLocalPos1Attr(vec(j["anchor"] - origins[b1]))
+            joint.CreateLocalRot0Attr(Gf.Quatf(1, 0, 0, 0))
+            joint.CreateLocalRot1Attr(Gf.Quatf(1, 0, 0, 0))
+            joint.CreateLowerLimitAttr(float(j["limits"][0]))
+            joint.CreateUpperLimitAttr(float(j["limits"][1]))
+            joint.CreateCollisionEnabledAttr(False)
+            drive = UsdPhysics.DriveAPI.Apply(joint.GetPrim(), "angular" if j["kind"] == "revolute" else "linear")
+            drive.CreateTypeAttr("force")
+            drive.CreateStiffnessAttr(float(j["drive"]["stiffness"]))
+            drive.CreateDampingAttr(float(j["drive"]["damping"]))
+            drive.CreateTargetPositionAttr(0.0)
+        if len(self.bodies) > 1 and len(self.joints) < len(self.bodies) - 1:
+            warnings.append(
+                f"{len(self.bodies)} bodies but {len(self.joints)} joints: unjointed bodies are loose parts"
+            )
+
+        allpts = np.vstack([pts for pts, _, _, _ in preview])
+        lo, hi = allpts.min(0), allpts.max(0)
+        UsdGeom.ModelAPI(root).SetExtentsHint(Vt.Vec3fArray([vec(lo), vec(hi)]))
+        today = datetime.date.today().isoformat()
+        metadata = {
+            "asset_name": self.name,
+            "asset_type": "prop",
+            "author": self.author,
+            "asset_license": self.license,
+            "category": self.category,
+            "description": self.description,
+            "qcode": self.qcode,
+            "usd_date_generated": today,
+            "source_file": Path(sys.argv[0]).name,
+            "rigid_body_count": len(self.bodies),
+            "joint_count": len(self.joints),
+            "mass": round(total_mass, 4),
+            "asset_extents": vec(hi - lo),
+            "validation": {"profile": PROFILE, "profile_version": PROFILE_VERSION},
+        }
+        stage.GetRootLayer().customLayerData = {
+            "SimReady_Metadata": metadata,
+            "asset_name": self.name,
+            "asset_type": "prop",
+            "source_file": metadata["source_file"],
+            "usd_date_generated": today,
+        }
+        stage.GetRootLayer().documentation = self.description or self.label
+        stage.GetRootLayer().Export(str(path))
+        thumbnail(preview, usd_dir / ".thumbs" / "256x256" / f"{self.name}.usda.png")
+        model = {
+            "name": self.name,
+            "bodies": model_bodies,
+            "joints": self.joints,
+            "size_m": np.round(hi - lo, 4).tolist(),
+            "mass_kg": round(total_mass, 3),
+            "triangles": triangles,
+            "preview": preview,
+        }
+        return path, model, warnings
+
+
+def _loads(bodies, joints):
+    """Each joint's load: the mass of its child body and everything jointed beyond it, that mass's centre (m, asset
+    frame) and its moment of inertia about the joint's axis (kg*m^2)."""
+    from .export import inertia
+
+    centres = {}
+    for b in bodies:
+        com, tensor = inertia(b)
+        centres[b["name"]] = (b["mass"], b["origin"] + com, tensor)
+    children = {}
+    for j in joints:
+        children.setdefault(j["body0"].name, []).append(j["body1"].name)
+    out = {}
+    for j in joints:
+        todo, seen = [j["body1"].name], []
+        while todo:
+            body = todo.pop()
+            if body not in seen:
+                seen.append(body)
+                todo += children.get(body, [])
+        mass = sum(centres[b][0] for b in seen)
+        centre = sum(centres[b][0] * centres[b][1] for b in seen) / mass
+        axis = np.eye(3)[AXES.index(j["axis"])]
+        moment = 0.0
+        for b in seen:
+            m, c, tensor = centres[b]
+            arm = c - j["anchor"]
+            moment += float(axis @ tensor @ axis) + m * float(arm @ arm - (arm @ axis) ** 2)
+        out[j["name"]] = (mass, centre, moment)
+    return out
+
+
+def _drive(j, mass, centre, moment, warnings):
+    """The drive the joint is written with: stiffness and damping as given, or sized to its load. Revolute values are
+    per degree (N*m/deg, N*m*s/deg), as UsdPhysics writes them; prismatic per metre (N/m, N*s/m)."""
+    given, weight = j["given"], mass * G
+    axis = np.eye(3)[AXES.index(j["axis"])]
+    arm = centre - j["anchor"]
+    reach = float(np.linalg.norm(arm - (arm @ axis) * axis))  # the load's centre from the axis
+    stiffness = given["stiffness"] if given["stiffness"] is not None else 0.0
+    if j["kind"] == "revolute":
+        tilt = float(np.sqrt(max(0.0, 1.0 - axis[2] ** 2)))  # 0 for a vertical axis: gravity cannot turn it
+        load = weight * reach * tilt  # the most gravity can turn it by in any pose, N*m
+        lever = max(reach, 0.01)
+        per = math.degrees(1.0)  # degrees per radian
+        if given["hold"] is not None:
+            stiffness = load / given["hold"]
+        critical = 2.0 * math.sqrt(stiffness * per * moment) / per
+        damping = given["damping"] if given["damping"] is not None else max(weight * lever / 90.0, 0.5 * critical)
+        push = max(weight * lever, 0.1)  # N*m: the load's weight at its reach, or a light twist of a hand at least
+        speed = push / max(damping, 1e-12)  # deg/s
+        rest = abs(float(np.cross(arm, (0.0, 0.0, -weight)) @ axis))
+        sag, units, slow, free = (rest / stiffness if stiffness else None), "deg", speed < 10.0, load > weight * 0.002
+    else:
+        load = weight * abs(float(axis[2]))
+        if given["hold"] is not None:
+            stiffness = load / given["hold"]
+        critical = 2.0 * math.sqrt(stiffness * mass)
+        damping = given["damping"] if given["damping"] is not None else max(weight, 0.5 * critical)
+        push = max(weight, 1.0)  # N: the load's weight, or a light push of a finger at least
+        speed = push / max(damping, 1e-12)  # m/s
+        sag, units, slow, free = (load / stiffness if stiffness else None), "m", speed < 0.02, abs(axis[2]) > 0.1
+    lo, hi = j["limits"]
+    if j["kind"] == "revolute" and math.isfinite(hi - lo) and (hi - lo > 360 or max(abs(lo), abs(hi)) > 360):
+        warnings.append(
+            f"joint {j['name']}: limits {lo:g} to {hi:g} deg pass one turn, and PhysX wraps a drive target past 360 "
+            f"degrees, so it cannot be driven there: keep it within one turn, or limits=None for a free spin"
+        )
+    if slow and given["damping"] is not None:  # the kit's own sizing is fast enough by construction
+        warnings.append(
+            f"joint {j['name']}: damping {damping:.4g} nearly locks it: a light push moves it only "
+            f"{speed:.3g} {units}/s; leave damping=None to have it sized"
+        )
+    if free and not stiffness and not given.get("loose"):
+        warnings.append(
+            f"joint {j['name']}: gravity pulls its load along it and nothing holds it, so it falls to a limit; "
+            f"pass hold= if it should hold its pose"
+        )
+    return {
+        "stiffness": round(float(stiffness), 6),
+        "damping": round(float(damping), 6),
+        "sized": "hold"
+        if given["hold"] is not None
+        else "given"
+        if given["stiffness"] is not None
+        else "loose"
+        if given.get("loose")
+        else "free",
+        "damping_sized": given["damping"] is None,
+        "load_kg": round(mass, 4),
+        "rest_sag": None if sag is None else round(float(sag), 6),
+        "sag_units": units,
+    }
+
+
+class _TextureNodes:
+    """The UsdUVTexture nodes of one material, sharing one primvar reader."""
+
+    def __init__(self, stage, mat, material, folder, value_types):
+        self.stage, self.mat, self.material, self.folder, self.T = stage, mat, material, folder, value_types
+        self.reader = None
+
+    def add(self, key, image, colour_space, output, value_type, scale_bias=None):
+        from pxr import Gf, Sdf, UsdShade
+
+        T = self.T
+        if self.reader is None:
+            self.reader = UsdShade.Shader.Define(self.stage, f"{self.mat.GetPath()}/st_reader")
+            self.reader.CreateIdAttr("UsdPrimvarReader_float2")
+            self.reader.CreateInput("varname", T.String).Set("st")
+            self.reader.CreateOutput("result", T.Float2)
+        file = _save_texture(image, self.folder, f"{self.material.name}_{key}.png")
+        self.material.files[key] = self.folder / file
+        node = UsdShade.Shader.Define(self.stage, f"{self.mat.GetPath()}/{key}_texture")
+        node.CreateIdAttr("UsdUVTexture")
+        node.CreateInput("file", T.Asset).Set(Sdf.AssetPath(f"./textures/{file}"))
+        node.CreateInput("sourceColorSpace", T.Token).Set(colour_space)
+        node.CreateInput("wrapS", T.Token).Set("repeat")
+        node.CreateInput("wrapT", T.Token).Set("repeat")
+        node.CreateInput("st", T.Float2).ConnectToSource(self.reader.GetOutput("result"))
+        if scale_bias:
+            node.CreateInput("scale", T.Float4).Set(Gf.Vec4f(*scale_bias[0]))
+            node.CreateInput("bias", T.Float4).Set(Gf.Vec4f(*scale_bias[1]))
+        return node.CreateOutput(output, value_type)
+
+
+def _smooth(points, tris, angle=30.0):
+    """Welded points and one normal per triangle corner. A corner averages only the faces around its point that lie
+    within `angle` of its own face. Smoothing groups by connectivity merged two faces at 90 degrees wherever a fillet
+    joined them somewhere else, and shaded their hard edge dark."""
+    import trimesh
+
+    mesh = trimesh.Trimesh(points, tris, process=True)
+    pts, faces = np.asarray(mesh.vertices), np.asarray(mesh.faces)
+    face_normals = np.asarray(mesh.face_normals)
+    weighted = face_normals * np.asarray(mesh.area_faces)[:, None]
+    flat = faces.reshape(-1)
+    order = np.argsort(flat, kind="stable")  # corners grouped by their point
+    counts = np.bincount(flat, minlength=len(pts))
+    starts = np.concatenate([[0], np.cumsum(counts)[:-1]])
+    group = counts[flat[order]]
+    corner = np.repeat(order, group)  # every corner, paired with every corner around the same point
+    offset = np.arange(group.sum()) - np.repeat(np.cumsum(group) - group, group)
+    other = order[np.repeat(starts[flat[order]], group) + offset]
+    near = np.einsum("ij,ij->i", face_normals[corner // 3], face_normals[other // 3]) >= np.cos(np.radians(angle))
+    summed = np.zeros((len(flat), 3))
+    np.add.at(summed, corner[near], weighted[other[near] // 3])
+    length = np.linalg.norm(summed, axis=1, keepdims=True)
+    normals = np.where(length > 1e-12, summed / np.maximum(length, 1e-12), face_normals[np.arange(len(flat)) // 3])
+    return pts, faces, normals
+
+
+def _uv(points, tris, material):
+    """A part's UVs, one pair per triangle corner, as the material's projection says."""
+    if material.projection == "box":
+        return _box_uv(points, tris, material.uv_scale, material.lengthwise)
+    if material.projection == "fit":
+        return _box_uv(points, tris, 1.0, material.lengthwise, fit=True)
+    return _cylinder_uv(_axis_onto_z(points, material.axis), tris)
+
+
+def _axis_onto_z(points, axis):
+    """The points turned so a cylinder's axis lies along Z. About X the front (-Y) stays the front; about Y (a lens
+    pointing out of the front) the top (+Z) becomes it."""
+    x, y, z = points[:, 0], points[:, 1], points[:, 2]
+    if axis == "X":
+        return np.stack([-z, y, x], axis=1)
+    if axis == "Y":
+        return np.stack([x, -z, y], axis=1)
+    return points
+
+
+def _cylinder_uv(points, tris):
+    """Wrapped once round the part about Z (u, its middle at -Y, growing anticlockwise seen from above) and once up it
+    (v); faces
+    that look along Z (a can's ends) get the part's box fitted, as 'fit' does."""
+    lo, hi = points.min(0), points.max(0)
+    centre = (lo + hi) / 2
+    corners = points[tris]
+    normal = np.cross(corners[:, 1] - corners[:, 0], corners[:, 2] - corners[:, 0])
+    normal /= np.maximum(np.linalg.norm(normal, axis=1, keepdims=True), 1e-12)
+    side = np.abs(normal[:, 2]) < 0.7
+    angle = np.arctan2(corners[..., 0] - centre[0], -(corners[..., 1] - centre[1]))  # 0 at -Y, the front
+    u = (angle / (2 * np.pi) + 0.5) % 1.0  # the image's centre faces the front; its edges meet at the back
+    wrap = side[:, None] & (u.max(1, keepdims=True) - u > 0.5)  # a triangle across the seam: unwrap its low corners
+    u = np.where(wrap, u + 1.0, u)
+    v = (corners[..., 2] - lo[2]) / max(hi[2] - lo[2], 1e-9)
+    uv = np.stack([u, v], axis=-1)
+    ends = _box_uv(points, tris, 1.0, fit=True).reshape(-1, 3, 2)
+    return np.where(side[:, None, None], uv, ends).reshape(-1, 2)
+
+
+def _box_uv(points, tris, scale, lengthwise=False, fit=False):
+    """Box-projected UVs, one pair per triangle corner: each triangle takes the two axes across its normal."""
+    corners = points[tris]
+    normal = np.abs(np.cross(corners[:, 1] - corners[:, 0], corners[:, 2] - corners[:, 0]))
+    keep = np.array([[1, 2], [0, 2], [0, 1]])[normal.argmax(1)]
+    extent = points.max(0) - points.min(0)
+    if lengthwise:  # u along the part's longer side of the two
+        keep = np.where((extent[keep[:, 1]] > extent[keep[:, 0]])[:, None], keep[:, ::-1], keep)
+    if fit:  # once across the part's box on each face
+        corners, scale = (corners - points.min(0)) / np.maximum(extent, 1e-9), 1.0
+    uv = np.take_along_axis(corners, np.repeat(keep[:, None, :], 3, axis=1), axis=2)
+    return uv.reshape(-1, 2) * scale
+
+
+def _colliders(points, tris, kind):
+    import trimesh
+
+    if kind == "none":
+        return []
+    if kind == "box":
+        box = trimesh.creation.box(bounds=[points.min(0), points.max(0)])
+        return [(np.asarray(box.vertices), np.asarray(box.faces))]
+    if kind == "convex_decomposition":
+        import coacd
+
+        coacd.set_log_level("error")
+        mesh = trimesh.Trimesh(points, tris, process=True)
+        parts = coacd.run_coacd(coacd.Mesh(mesh.vertices, mesh.faces), threshold=0.05, max_convex_hull=16)
+        return [_within_limit(np.asarray(v), np.asarray(f)) for v, f in parts]
+    hull = trimesh.Trimesh(points, tris, process=True).convex_hull
+    return [_within_limit(np.asarray(hull.vertices), np.asarray(hull.faces))]
+
+
+def _within_limit(vertices, faces):
+    """A hull of at most HULL_POINTS points, as PhysX would cut it: the farthest-spread points, hulled again. A
+    finely tessellated round part (a filleted disc made 1134) keeps its shape to within a fraction of a millimetre."""
+    import trimesh
+
+    if len(vertices) <= HULL_POINTS:
+        return vertices, faces
+    keep = [int(np.argmax(np.linalg.norm(vertices - vertices.mean(0), axis=1)))]
+    distance = np.linalg.norm(vertices - vertices[keep[0]], axis=1)
+    while len(keep) < HULL_POINTS:
+        keep.append(int(np.argmax(distance)))
+        distance = np.minimum(distance, np.linalg.norm(vertices - vertices[keep[-1]], axis=1))
+    hull = trimesh.Trimesh(vertices[keep]).convex_hull
+    return np.asarray(hull.vertices), np.asarray(hull.faces)
+
+
+def _save_texture(texture, folder, name):
+    from PIL import Image
+
+    if isinstance(texture, (str, Path)):
+        image = Image.open(texture)
+    elif isinstance(texture, np.ndarray):
+        image = Image.fromarray(texture.astype(np.uint8))
+    else:
+        image = texture
+    image.convert("RGB").save(folder / name)
+    return name
+
+
+def _linear(rgb):
+    """An sRGB colour (0-1) as the linear colour UsdPreviewSurface and displayColor take."""
+    return tuple(float(c) ** 2.2 for c in rgb)
+
+
+def _centre_of_mass(parts):
+    """The volume x density weighted centre of a body's visible parts (asset frame), or None."""
+    import trimesh
+
+    total, moment = 0.0, np.zeros(3)
+    for part in parts:
+        if not part.get("visible", True):
+            continue
+        mesh = trimesh.Trimesh(part["points"], part["tris"], process=True)
+        solid = mesh if mesh.is_watertight and mesh.volume > 0 else mesh.convex_hull
+        weight = part["volume"] * part["material"].density
+        if weight > 0 and solid.volume > 0:
+            total += weight
+            moment += weight * np.asarray(solid.center_mass)
+    return moment / total if total > 0 else None
+
+
+def _mean_colour(image):
+    """The average colour of a texture: a path, a PIL image or an HxWx3 uint8 array."""
+    from PIL import Image
+
+    if isinstance(image, (str, Path)):
+        image = Image.open(image)
+    pixels = np.asarray(image.convert("RGB") if hasattr(image, "convert") else image, dtype=float)[..., :3] / 255
+    return tuple(float(x) for x in pixels.reshape(-1, 3).mean(0))