Skip to main content

USD Specification

Draft specification

This specification is version 1.0 and subject to change. Based on Pixar USD 23.x / OpenUSD 24.x.

The Miris USD Specification defines the standardized subset of OpenUSD accepted for rendering and streaming. Compliant files may contain geometry, materials, scene assembly, animation, and lighting. Simulation, physics, and renderer-specific extensions are not supported.

Scope​

IncludedExcluded
Geometry (meshes, curves, points)Procedural geometry, volumes
Materials (UsdPreviewSurface, MaterialX)Renderer-specific shaders (Arnold, Redshift, Karma, Omniverse)
Scene hierarchy, references, variant sets with defaultPhysics, dynamics, collisions
Transform and skeletal animationConstraints, IK, simulations
Lights (UsdLux schema)Proprietary light types
Metadata for units and orientationRenderProducts, AOV definitions
Custom metadata unrelated to content

Accepted Formats​

FormatNotes
.usdcBinary — preferred for performance
.usdaASCII — acceptable for interchange and debugging
.usdzArchive — acceptable for self-contained assets

Required Metadata​

Every compliant USD file must include the following stage-level metadata:

#usda 1.0
(
    metersPerUnit = 1
    upAxis = "Y"
    defaultPrim = "Root"
)
FieldValueDescription
metersPerUnit11 USD unit = 1 meter
upAxis"Y"Y-up coordinate system
defaultPrim"Root"Name of the scene root prim
note

Timing metadata (startTimeCode, endTimeCode, timeCodesPerSecond) is only required for animated files. See Animation.

Default Prim​

Each compliant file must define a defaultPrim at the root of the scene hierarchy. All geometry, lights, and cameras must be organized under this prim. Materials are an exception — they live at the top level under a separate /Materials scope (see Materials).

Scene Structure​

note

Detailed documentation for this section is coming soon.

Composition Arcs​

references, sublayers, and variants are all supported. All referenced files must also conform to this specification.

def Xform "Character" (
    prepend references = @./Character/character_geo.usd@
)

Geometry​

Supported Schemas​

SchemaDescription
UsdGeomMeshPolygonal mesh
UsdGeomBasisCurvesCurves
UsdGeomPointsPoint clouds
UsdGeomSubsetMaterial subsets
UsdGeomXformTransform hierarchy
UsdGeomScopeLogical grouping
caution

Procedural and volumetric prims are not supported. They will be ignored or cause validation errors on import.

Materials​

All materials must be defined under a /Materials scope at the top level of the file — not nested under the defaultPrim.

def Scope "Materials"
{
    def Material "Wood"
    {
        token outputs:surface.connect = </Materials/Wood/PreviewSurface.outputs:surface>

        def Shader "PreviewSurface"
        {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor.connect = </Materials/Wood/BaseColorTex.outputs:rgb>
            float inputs:roughness = 0.4
            token outputs:surface
        }

        def Shader "BaseColorTex"
        {
            uniform token info:id = "UsdUVTexture"
            asset inputs:file = @./Textures/wood_basecolor.png@
            token inputs:sourceColorSpace = "sRGB"
            float2 inputs:st.connect = </Materials/Wood/TexCoordReader.outputs:result>
            float3 outputs:rgb
        }

        def Shader "TexCoordReader"
        {
            uniform token info:id = "UsdPrimvarReader_float2"
            string inputs:varname = "st"
            float2 outputs:result
        }
    }
}

Supported Shader Types​

Schemainfo:idDescription
UsdPreviewSurfaceUsdPreviewSurfaceStandard PBR material
UsdUVTextureUsdUVTextureTexture sampling
UsdPrimvarReader_float2UsdPrimvarReader_float2UV coordinate reader — required to feed st into UsdUVTexture
OpenPBR SurfaceMaterialXMaterialX OpenPBR (requires MaterialX v1.38.10-OpenPBR or v1.39+)

Texture Rules​

  • All texture paths must be relative (e.g. @./Textures/basecolor.png@)
  • Supported texture channels: BaseColor, Roughness, Metallic, Normal, Emission

Scene Assembly​

note

Detailed documentation for this section is coming soon.

Variants​

Miris currently uses the default variant for each variant set.

note

Detailed documentation for this section is coming soon.

Lighting​

Compliant files must include at least one light. All lights must use UsdLux schemas.

Supported Light Types​

SchemaDescription
UsdLuxDistantLightDirectional light
UsdLuxSphereLightOmni / point light
UsdLuxRectLightArea light
UsdLuxDomeLightEnvironment / sky light (HDR)

Light Attributes​

AttributeTypeDescription
inputs:colorcolor3fLight color
inputs:intensityfloatIntensity multiplier (dimensionless)
inputs:exposurefloatExposure offset
inputs:texture:fileassetDome light environment map path
xformOpstransformsLight position and orientation

Animation​

Transform Animation​

def Xform "Cube"
{
    double3 xformOp:translate.timeSamples = {
        0: (0, 0, 0),
        24: (10, 0, 0)
    }
    uniform token[] xformOpOrder = ["xformOp:translate"]
}

Attribute Animation​

Any numeric or color attribute may use timeSamples for animation.

Skeletal Animation​

The following schemas are supported for skeletal animation:

  • UsdSkelRoot
  • UsdSkeleton
  • UsdSkelAnimation
  • UsdSkelBindingAPI — applied to skinned mesh prims to define joint weights and indices

Timing Metadata​

Animated files must include the following stage-level metadata:

FieldExampleDescription
startTimeCode1First frame
endTimeCode240Last frame
timeCodesPerSecond24Time codes per second of real time — controls playback rate (defaults to 24 if omitted)

Supported Metadata​

MetadataRequired
metersPerUnit✅ Always
upAxis✅ Always
defaultPrim✅ Always
startTimeCode, endTimeCodeAnimated files only
timeCodesPerSecondAnimated files only (defaults to 24)
customLayerDataOptional — accepted for provenance
customData:defaultCameraOptional

Unsupported Metadata​

The following metadata is ignored or will cause validation errors:

  • Renderer-specific settings (renderSettings:*)
  • Physics data (physx:*, rigidBody:*)
  • Simulation metadata

Conformance​

A USD file is compliant with this specification if it:

  • Defines a single root prim named in defaultPrim
  • Contains only prims and attributes listed in this specification
  • Uses relative paths for all asset references (textures, sublayers, references)
  • Includes at least one light using a supported UsdLux schema
  • Uses only supported USD schemas

Validation​

Validate your file before uploading using usdchecker:

usdchecker yourfile.usd

Appendix A — Complete Example​

#usda 1.0
(
    metersPerUnit = 1
    upAxis = "Y"
    defaultPrim = "Root"
)

def Xform "Root"
{
    def Mesh "Cube"
    {
        point3f[] points = [
            (0,0,0), (1,0,0), (1,1,0), (0,1,0),
            (0,0,1), (1,0,1), (1,1,1), (0,1,1)
        ]
        int[] faceVertexCounts = [4, 4, 4, 4, 4, 4]
        int[] faceVertexIndices = [
            0, 3, 2, 1,
            4, 5, 6, 7,
            0, 1, 5, 4,
            1, 2, 6, 5,
            2, 3, 7, 6,
            3, 0, 4, 7
        ]
        rel material:binding = </Materials/Gray>
    }

    def Scope "Cameras"
    {
        def Camera "MainCam"
        {
            float focalLength = 35
            float horizontalAperture = 36
            float verticalAperture = 24
            matrix4d xformOp:transform = ( (1,0,0,0), (0,1,0,0), (0,0,1,0), (0,2,5,1) )
            uniform token[] xformOpOrder = ["xformOp:transform"]
        }
    }

    def Scope "Lights"
    {
        def DistantLight "KeyLight"
        {
            color3f inputs:color = (1, 0.9, 0.8)
            float inputs:intensity = 3.0
        }
        def DomeLight "SkyLight"
        {
            asset inputs:texture:file = @./Textures/sky.exr@
            float inputs:intensity = 0.5
        }
    }
}

def Scope "Materials"
{
    def Material "Gray"
    {
        token outputs:surface.connect = </Materials/Gray/Shader.outputs:surface>
        def Shader "Shader"
        {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor = (0.5, 0.5, 0.5)
            token outputs:surface
        }
    }
}

Further Reading​

This specification describes the subset of OpenUSD accepted by Miris. For the full OpenUSD specification and schema reference, see the official documentation at openusd.org: