USD layout

Every USD export GroomLab makes writes the same layout: Maya's GroomLab > Export > USD..., groomLabExportUsd and groomlab.export_usd, the app's USD export, Blender's Export USD, groomlab-cli eval hair.groom -o hair.usda and the core's groomlab_core.UsdCurvesWriter. Each writes one text layer (.usda) of BasisCurves, plus meshes and point instancers when the groom has scales or instances. This page describes layout version 1, so that viewers, pipeline tools and other hosts can read GroomLab grooms without guessing.

These details are not part of the contract: the text of the layer's doc, number formatting, whitespace and attribute order, and the name of the root prim (read defaultPrim). Read the files with a USD library (pxr, or any reader that follows the .usda grammar) rather than by matching text.

Checking the versionCopy Anchor Link

The layer's customLayerData and the root prim's customData both hold a groomlab dictionary:

The layer's copy is easiest to read from the file itself. The prim's copy survives when the layer is referenced into another stage, where customLayerData is out of reach.

from pxr import Sdf, Usd

layer = Sdf.Layer.FindOrOpen("hair.usda")
assert layer.customLayerData["groomlab"]["layoutVersion"] == 1

stage = Usd.Stage.Open("shot.usda")                # a stage referencing the groom
groom = stage.GetPrimAtPath("/shot/hair")          # where the groom's root prim landed
assert groom.GetCustomDataByKey("groomlab:layoutVersion") == 1

Files written before layout version 1 have no groomlab dictionary; treat them as unversioned.

Layer metadataCopy Anchor Link

Units, up axis and root name per exporterCopy Anchor Link

GroomLab never rescales: points and widths are in the groom's own units. Multiply by metersPerUnit to get meters.

No prim has a transform (xformOp). Points are in the groom's object space: in Maya, the groom transform's own matrix is not applied, so parent the imported layer under the same transform if it was moved.

PrimsCopy Anchor Link

/<root>                          Xform, kind "component", customData {groomlab}: the default prim
    strands                      BasisCurves: always
    instances                    PointInstancer: Instance node instances, when there are some
        prototypes               Scope
            <prototype>          Mesh, or an empty Xform placeholder
    scales                       Mesh: Scales node scales, as a bent mesh
    scaleInstances               PointInstancer: Scales node scales, as instances
        prototypes               Scope
            <prototype>          Mesh, or an empty Xform placeholder

The root prim has no attributes.

strands: BasisCurvesCopy Anchor Link

One curve per strand, root first.

Attribute primvarsCopy Anchor Link

Every attribute the strands carry at the Output node becomes a float[] primvar: per-strand ones uniform, per-point ones vertex. Which ones exist depends on the graph; the full list is in Strand attributes. Common ones:

Names are made valid USD identifiers, and unique:

• Characters other than letters, digits and _ become _; a leading digit gets a _ prefix.
• st, strandId, displayColor, displayOpacity, widths, points and normals are reserved: an attribute with one of these names gets a suffix.
• A name already taken gets _2, _3, ... Per-strand attributes are named first (sorted by name), then per-point ones (sorted), so a per-point attribute that shares a per-strand one's name gets _2. That is why HairColor's per-point RGB is colorR_2. Check a primvar's interpolation rather than relying on the suffix.

instances: PointInstancerCopy Anchor Link

Instance nodes' instances (leaves, plates, any prototype placed along strands).

All but prototypes are time-sampled. This instancer has no primvars.

PrototypesCopy Anchor Link

prototypes (a Scope) holds one prim per prototype the groom names, the name made a valid identifier and unique (a-b and a_b become a_b and a_b_2; groomlab:scale becomes groomlab_scale). Its doc metadata holds the original name.

• A Mesh when GroomLab has the geometry: the built-in plates (groomlab:...) and scene meshes the groom file stores (or, in Maya, the scene has). Its attributes are plain values, not time-sampled: subdivisionScheme (uniform token, "none"), faceVertexCounts (int[], all 3: triangles), faceVertexIndices (int[]), points (point3f[]), extent (float3[]), and when the mesh has them normals (normal3f[], vertex) and primvars:st (texCoord2f[], vertex).
• An empty Xform otherwise, whose doc says to reference the geometry in there.

Prototypes are modelled 1 unit long along +Y, with their base at the origin.

scales: MeshCopy Anchor Link

The Scales node's scales as one mesh, each scale bent onto the skin exactly as the viewport and Arnold show it. Triangles; no vertex is shared between two scales.

All but subdivisionScheme are time-sampled.

scaleInstances: PointInstancerCopy Anchor Link

The same scales as instances of their prototypes, each placed by its scale's frame (tilted and raised as in the mesh, but not bent onto the skin): light, and editable in an engine (Unreal's USD importer makes instanced static meshes of it). It has the attributes of instances and its own prototypes (the Scales node's, every one of them), plus a primvar per instance (vertex interpolation, USD's convention for per-instance primvars on a PointInstancer):

Frames and time samplesCopy Anchor Link

• Everything that can change is written as timeSamples, also for a single frame. There are no default values, so read at a time code: attr.Get(Usd.TimeCode(frame)), or at stage.GetStartTimeCode() for a one-frame file. attr.Get() with no time returns nothing. The plain values are type, wrap, visibility, subdivisionScheme, the instancers' prototypes and the prototype meshes.
• Time codes are the exporter's frame numbers (Maya's frames; step=0.5 writes 1, 1.5, 2...).
• One frame: one sample per attribute at that frame, and startTimeCode = endTimeCode. Viewers that export a file per frame get a complete layer each time.
• A range: one sample per frame, every attribute at the same time codes.
• Strand counts and point counts may change between frames (on a deforming scalp without a rest pose). Read curveVertexCounts for every frame, and match strands by primvars:strandId.
• The first frame decides which prims and primvars the file has. A primvar missing on a later frame is written as zeros; scales missing on a later frame are written as empty arrays.

from pxr import Usd, UsdGeom

stage = Usd.Stage.Open("hair.usda")
root = stage.GetDefaultPrim()
curves = UsdGeom.BasisCurves(root.GetChild("strands"))
primvars = UsdGeom.PrimvarsAPI(curves)
for t in curves.GetPointsAttr().GetTimeSamples():   # every frame written, subframes included
    points = curves.GetPointsAttr().Get(t)            # scene units
    counts = curves.GetCurveVertexCountsAttr().Get(t)
    diameters = curves.GetWidthsAttr().Get(t)
    ids = primvars.GetPrimvar("strandId").Get(t)
    color = primvars.GetPrimvar("displayColor")       # may be absent: check IsDefined()

What changes the contentsCopy Anchor Link

• Density: exports take a density (0-1) and keep a stable subset of the strands, by ID; the kept strands keep their strandId.
• Render overrides (Maya's -renderOverrides, render_overrides=True): the groom's render density, width scale and length scale applied, as in a render. The layout stays the same.
• No render-time LOD: camera-distance thinning and culling only happen in Arnold at render time; exports never apply them.
• Motion: each sample is the groom as evaluated on that frame, its scalp's motion and scale included. There are no velocities: renderers interpolate between samples (export subframes for fast motion).

ExampleCopy Anchor Link

A two-strand groom with a scalp UV, a color and a clump ID, one frame (numbers shortened):

#usda 1.0
(
    defaultPrim = "hair"
    doc = "GroomLab 0.15.0: scene.ma |hair|hairShape"
    customLayerData = {
        dictionary groomlab = {
            int layoutVersion = 1
            string version = "0.15.0"
        }
    }
    startTimeCode = 1
    endTimeCode = 1
    framesPerSecond = 24
    timeCodesPerSecond = 24
    metersPerUnit = 0.01
    upAxis = "Y"
)

def Xform "hair" (
    customData = {
        dictionary groomlab = {
            int layoutVersion = 1
            string version = "0.15.0"
        }
    }
    kind = "component"
)
{
    def BasisCurves "strands"
    {
        uniform token type = "linear"
        uniform token wrap = "nonperiodic"
        int[] curveVertexCounts.timeSamples = {
        1: [3, 3],
        }
        point3f[] points.timeSamples = {
        1: [(0, 10, 0), (0, 12, 0.5), (0, 14, 1.5), (1, 10, 0), (1, 12, 0.5), (1, 14, 1.4)],
        }
        float3[] extent.timeSamples = {
        1: [(-0.004, 9.996, -0.004), (1.004, 14.004, 1.504)],
        }
        float[] widths (
            interpolation = "vertex"
        )
        float[] widths.timeSamples = {
        1: [0.008, 0.006, 0.002, 0.008, 0.006, 0.002],
        }
        int64[] primvars:strandId (
            interpolation = "uniform"
        )
        int64[] primvars:strandId.timeSamples = {
        1: [1052, 1053],
        }
        texCoord2f[] primvars:st (
            interpolation = "uniform"
        )
        texCoord2f[] primvars:st.timeSamples = {
        1: [(0.41, 0.73), (0.43, 0.73)],
        }
        color3f[] primvars:displayColor (
            interpolation = "uniform"
        )
        color3f[] primvars:displayColor.timeSamples = {
        1: [(0.28, 0.17, 0.09), (0.3, 0.18, 0.1)],
        }
        float[] primvars:clumpId (
            interpolation = "uniform"
        )
        float[] primvars:clumpId.timeSamples = {
        1: [4, 4],
        }
    }
}

Compared with the Alembic exportCopy Anchor Link

The Alembic export carries the same strands from the same data, under Alembic's names:

Alembic files carry no units, up axis or version marker.

For contributorsCopy Anchor Link

The writer is engine/core/src/usd_writer.cpp (UsdCurvesWriter); every exporter above calls it. tests/engine/core/test_usd_layout.cpp exports small grooms (with and without scales, one frame and a range), parses the layers and compares every prim, attribute, type, interpolation and metadata entry with this page, both ways, and checks that this page names them all. When you change the writer:

• Adding a primvar, prim or metadata entry: add it to this page and to the test. The layout version stays.
• Renaming, retyping, changing an interpolation or a meaning, or removing something: raise kUsdLayoutVersion in usd_writer.h, update this page (its version and the example) and the test, and list the change in What's new.

Version historyCopy Anchor Link

• Layout version 1: the first versioned layout. Compared with earlier, unversioned exports: the groomlab version marker is new; scaleInstances' per-instance root color is primvars:scaleRootColor (it was primvars:scaleColor, a name the scales mesh uses for the color along the scale); an attribute named normals is written as primvars:normals_2; and the standalone app's export now writes the scales and the stored prototype meshes, as the other exporters do.

NextCopy Anchor Link