glTF to USD Metadata Mapping Guide

Converting 3D assets from the glTF (GL Transmission Format) standard to Pixar’s Universal Scene Description (USD) requires translating metadata across scene hierarchies, geometry definitions, material schemas, and user data. This article outlines the specific mapping processes that occur during import, highlighting how glTF JSON properties are translated into USD prims, attributes, and metadata dictionaries.

Asset-Level Metadata

glTF files contain top-level asset objects that define global information. During USD import, these properties map to USD Stage Layer metadata:

  • asset.version and asset.minVersion: Written to the layer's customLayerData dictionary under keys such as gltf:version to preserve version provenance.
  • asset.generator: Mapped to the stage-level comment field or stored within customLayerData["creator"].
  • asset.copyright: Saved to the stage's documentation field or inside customLayerData["copyright"].

Node and Hierarchy Mappings

glTF structures scenes as hierarchical arrays of nodes. USD converts these nodes into typed scene graph prims:

  • Node Identification: The node.name maps directly to a USD Prim name (e.g., /Root/NodeName). If names are non-compliant with USD naming conventions (such as containing special characters), they are sanitized.
  • Transforms: glTF translation, rotation (quaternions), and scale arrays map to USD standard transform operations on UsdGeomXformable prims: xformOp:translate, xformOp:orient, and xformOp:scale. When a 4x4 matrix is used in glTF, it maps directly to xformOp:transform.

Geometry and Primitive Attributes

glTF meshes consist of primitives containing accessor references. USD imports these as UsdGeomMesh primitives:

  • Vertex Positions: glTF POSITION maps to UsdGeomMesh points.
  • Normals: glTF NORMAL maps to normals, with the interpolation set to vertex.
  • Texture Coordinates: glTF TEXCOORD_0, TEXCOORD_1, etc., map to indexed primvars named primvars:st or primvars:st_0 with faceVarying or vertex interpolation.
  • Indices: The glTF primitive index accessor maps to faceVertexIndices, while faceVertexCounts is automatically populated (typically with triangles, represented as arrays of 3s).
  • Vertex Colors: COLOR_0 maps to primvars:displayColor and primvars:displayOpacity.

PBR Material Definitions

glTF materials adhere to the PBR Metallic-Roughness workflow, which translates natively to USD's UsdPreviewSurface shading schema:

  • baseColorFactor & baseColorTexture: Map to inputs:diffuseColor and inputs:opacity on a UsdPreviewSurface shader.
  • metallicFactor & roughnessFactor: Map to inputs:metallic and inputs:roughness.
  • normalTexture: Maps to inputs:normal, often accompanied by a UsdUVTexture reading the texture with normal scale adjustments.
  • emissiveFactor & emissiveTexture: Map to inputs:emissiveColor.
  • occlusionTexture: Maps to inputs:occlusion.
  • Alpha Modes: OPAQUE, MASK, and BLEND map to the inputs:opacityThreshold attribute and USD render context metadata.

Skeletal Animation and Rigging

Rigging metadata in glTF skins is translated into USD's UsdSkel schema:

  • skin.joints: Maps to the token array attribute skel:joints on a UsdSkelSkeleton prim.
  • skin.inverseBindMatrices: Maps to skel:bindTransforms.
  • JOINTS_0 & WEIGHTS_0: Map to geometry primvars primvars:skel:jointIndices and primvars:skel:jointWeights.
  • Animations: glTF animation.samplers and animation.channels map to time-sampled attributes on UsdSkelAnimation prims (translations, rotations, scales).

Extras and Extensions

  • extras: Arbitrary user metadata found inside glTF objects is encapsulated directly into the USD object’s customData dictionary, maintaining keys and scalar/string values.
  • Extensions: Common Khronos extensions (such as KHR_materials_unlit or KHR_texture_transform) map to specialized USD shading attributes, such as bypassing the lighting calculation for unlit shaders or inserting a UsdTransform2d primvar reader for UV coordinates.