Docs / Format mappings / usd

OpenUSD

A host is Rig when it emits entities with POD components keyed by schema ids it supports (honors). OpenUSD stages (.usda, .usdc, .usd, .usdz) are encodings. The OpenUSD library, Hydra, and a writer that merges over opinions back onto a layer are fulfillment - not this catalog.

Unlike OpenBIM, there is no rig.usd.* layer. Portable meaning is spatial / geometry / render / animation / simulation. Product names stay out of schema ids (same rule as rig.music.clock). USD-only fields travel as x.usd.*.

The document is the composed stage. Sublayers, references, payloads, variant sets, inherits, specializes, and list-editing stay in the USD file. A host composes that file, then writes ordinary entities. Two hosts that never linked OpenUSD can exchange the picture. Switching a variant means composing the USD file again.

Map

OpenUSD idea Rig
Stage / defaultPrim Unparented rig.spatial.vertex
Xform rig.spatial.transform + rig.spatial.relationship parent
Scope rig.spatial.group
Prim name / path rig.meta.named (name, stableId)
UsdGeomMesh rig.geometry.mesh. faceVertexCounts / faceVertexIndices are loopSizes / loops. Triangle tessellation is indices
One GeomSubset material bind One mesh entity - rig.render.material composes on the drawable
UsdPreviewSurface That material: diffuseColor / metallic / roughness / emissiveColor to albedoRgb / metallic / roughness / emissive. Copy a shared bind onto each mesh
primvars:st / normals Mesh texcoords / normals
UsdGeomCamera rig.spatial.camera. Focal length and apertures become fovYDegrees and aspect. Both look along local -Z
DistantLight rig.render.light directional
Point-like SphereLight Same light, point
ShapingAPI cone Same light, spot (innerConeDegrees / outerConeDegrees)
DomeLight rig.render.environment + rig.media.asset_ref (kind image)
Cubic basis curves rig.geometry.path3d
NURBS curves rig.geometry.spline3d
NurbsPatch rig.geometry.nurbs_surface
Skeleton / bind / skin rig.anim.skeleton / bind / skin
Skel animation rig.anim.clip + rig.anim.track. TimeCodes become seconds
Same-document reference or expanded point instancer rig.spatial.instance
External reference left unexpanded rig.media.asset_ref kind model
Rigid body / collider rig.sim.rigidbody / rig.sim.collider
Fixed / revolute / prismatic / spherical / distance joint rig.sim.joint fixed / hinge / slider / ball / distance
Composed invisible rig.render.visibility on that entity (Rig hide does not inherit)
Source stage One asset_ref (kind model) a writer merges over opinions onto

Axis, unit, time, and quaternion conversion sit at the edge. 3D is right-handed, +Y up (document Axes). upAxis = Z converts to that. metersPerUnit becomes document.defaultUnit (1 is "m", 0.01 is "cm", 0.001 is "mm"). USD's fallback is centimetres. xformOp stacks bake into one transform (position / rotation / scale / shear). Extent caches stay out.

GfQuat is real, i, j, k (w, x, y, z). Rig rotation is [x, y, z, w]. Animation timeCodes / timeCodesPerSecond is seconds (timeCodesPerSecond fallback 24).

rig.anim.skin is four influences per vertex. A host that reads a vertex with more keeps the four heaviest weights and renormalizes - same rule as spine.md.

Photometric light intensity, active variant, purpose, kind, subdivision scheme, and double-sided travel as x.usd.*. Rect, disk, and cylinder lights stay in the USD file - rig.render.light has no area lights. A D6 joint stays in the USD file.

Sketch

A world, a cube with a material, sitting on y = 0:

{
  "entities": [
    {
      "id": "world",
      "components": {
        "rig.meta.named": { "name": "World", "stableId": "World" },
        "rig.spatial.vertex": {}
      }
    },
    {
      "id": "body",
      "components": {
        "rig.meta.named": { "name": "Body", "stableId": "World/Body" },
        "rig.spatial.relationship": { "parent": "world" },
        "rig.spatial.transform": { "position": [0, 50, 0] },
        "rig.geometry.mesh": {
          "positions": [
            -50, -50, -50, 50, -50, -50, 50, 50, -50, -50, 50, -50,
            -50, -50, 50, 50, -50, 50, 50, 50, 50, -50, 50, 50
          ],
          "indices": [
            0, 1, 2, 0, 2, 3, 4, 7, 6, 4, 6, 5, 0, 4, 5, 0, 5, 1,
            1, 5, 6, 1, 6, 2, 2, 6, 7, 2, 7, 3, 3, 7, 4, 3, 4, 0
          ],
          "loops": [
            0, 1, 2, 3, 4, 7, 6, 5, 0, 4, 5, 1, 1, 5, 6, 2, 2, 6, 7, 3, 3, 7, 4, 0
          ],
          "loopSizes": [4, 4, 4, 4, 4, 4],
          "mode": "triangles"
        },
        "rig.render.material": {
          "albedoRgb": [0.82, 0.78, 0.72],
          "roughness": 0.45
        }
      }
    }
  ]
}

(Wrap in a full document with "rig" set to the current VERSION before validating.)

Stay out

Stay out Why
Sublayers, references as arcs, payloads Composition stays in the USD file. The .rig is the composed picture
Variant sets, inherits, specializes, list-editing Same. Switching a variant re-composes the USD file
Hydra, MaterialX, shader graphs Presenters and networks are fulfillment
Blend shapes, creases, extra UV sets Mesh morphs and extra primvars stay encoding until a second host stores them
Primvars other than one UV set plus per-vertex normals One texcoords / normals packing on the mesh
Unexpanded point instancers Expand to spatial.instance, or leave them in the USD file
Area lights, D6 joints Leave them in the USD file
rig.usd.* Product names stay out of schema ids

Encodings (fulfillment)

Surface Role
.usda / .usdc / .usd Compose, then map the result into the table above
.usdz Packaged stage; textures and payloads travel in the zip. Sidecars that leave with a .rig go in .rigz data/
Source asset_ref kind model; a writer merges authored transforms and visibility back as over opinions, same bargain as kicad.md
x.usd.* Active variant, purpose, kind, subdivision scheme, double-sided, photometric intensity - travel; do not port

Example: examples/usd-stage.json.