Investigate blown-out MToon/unlit colours in usdview (front bangs)

[snkmcb]

Observed

The converted USD appears noticeably overexposed in usdview compared with the source VRM rendered in a VRM web viewer. The discrepancy is especially visible on the front bangs: their strand-level shading/colour variation is mostly lost and becomes nearly white/yellow.

Reference captures from the report:

• VRM web viewer:

• converted USD in usdview:

Expected

The USD should preserve the source VRM's visible material colour variation closely enough that the bangs do not clip to a bright, nearly uniform colour in usdview.

Initial investigation

Two likely contributing gaps are present in the current converter:

1. Vertex colour support appears absent. The USD authorer creates normal and st primvars, but does not author a colour primvar (displayColor / primvars:...), and the reader has no apparent COLOR_0 handling. If this asset uses vertex colours to modulate hair shading, that modulation is currently dropped.
2. Unlit materials are represented by putting baseColor directly into UsdPreviewSurface.inputs:emissiveColor. For textured unlit materials, the base-colour texture replaces that input. The implementation notes that glTF factor x texture multiplication is only approximated, and MToon is retained as metadata rather than mapped to a dedicated graph. This can change energy/colour handling in Hydra/usdview and may explain the blown-out result.

Relevant code:

• plugins/usdVrmFileFormat/src/usd/UsdVrmAuthorer.cpp -- unlit base-colour -> emissive conversion and texture connections
• plugins/usdVrmFileFormat/src/io/CgltfVrmDocumentReader.cpp -- material import; no COLOR_0 import found

Investigation / acceptance criteria

• Inspect the source VRM/glTF for COLOR_0 and determine its interpolation and intended material modulation.
• Author the corresponding USD colour primvar and connect/multiply it in the material graph where required.
• Verify the unlit/MToon mapping in usdview does not overdrive emissive output; preserve base-colour factor x texture semantics.
• Add a focused fixture/regression test for vertex-colour and unlit/emissive material output.
• Compare source VRM and converted USD using the same camera and neutral lighting, with the front bangs as the primary visual check.

Notes

The captures make this a renderer-visible discrepancy, but the exact target asset and its source .vrm have not yet been added to the repository. Attach or reference it before implementing the regression fixture.

[snkmcb]

Investigation update (2026-08-12)

The supplied reproduction asset is AliciaSolid.vrm. It opens through the OST usdview session (with the schema and package-resolver bundles), and the front-bang discrepancy remains after the generic glTF fix below.

Findings from the source asset:

• No primitive has COLOR_0; vertex colours are not the cause for this avatar.
• The hair materials are VRM 0.x VRM/MToon entries, including Alicia_hair, Alicia_hair_trans, and their z-write variants.
• Alicia_hair uses _MainTex = 5 and _ShadeTexture = 5, with _Color = (1,1,1,1) and _ShadeColor = (1,0.779,0.762,1). The transparent variants also use _ALPHABLEND_ON; their alpha is preserved, which explains why cutout/transparent strands remain visible while the intended colour gradient is missing.
• The current importer deliberately stores VRM 0.x materialProperties[] as vrm:mtoon:raw metadata. The authored UsdPreviewSurface only uses glTF PBR base colour (for unlit, texture RGB is connected directly to emissiveColor). It does not evaluate _ShadeTexture, _ShadeColor, _ShadeShift, _ShadeToony, or the MToon blend/render state.

Conclusion: the high-probability root cause is missing MToon shading semantics, rather than vertex colour or base-colour factor multiplication. A simple unlit/emissive UsdPreviewSurface approximation cannot recreate this asset's main-vs-shade texture/color selection. The follow-up should define and test a renderer-supported MToon approximation, preferably MaterialX if it is reliably consumed by Hydra/usdview, or a documented UsdShade node graph fallback. It must at least model the main/shade colour path, alpha blend/cutoff mode, and define the expected neutral-lighting appearance for the front bangs.

Change review: I discarded an initial COLOR_0 import attempt because it only authored displayColor / displayOpacity primvars without multiplying them into the bound material graph. That would preserve data but not implement glTF's required base-colour modulation or change the viewer result. The retained generic correction preserves glTF baseColorFactor x baseColorTexture semantics through UsdUVTexture.inputs:scale, including alpha factor; it has a focused regression assertion and passes the OST smoke suite. Alicia has the default (1,1,1,1) factor, so this correct behavior does not affect the reproduction asset.

[snkmcb]

Update (2026-08-14): P5 Step 2 has landed for unlit materials (unreleased). It moves this issue and removes two of its five candidates, but it does not close it.

What changed

Every KHR_materials_unlit material now carries a second realization at /Asset/mtl/<name>/mtlx, reached through outputs:mtlx:surface. Storm advertises the mtlx render context, and UsdShadeMaterial::ComputeSurfaceSource takes the first advertised context that is connected — so usdview now draws the MaterialX network, and /preview becomes the path for consumers that do not speak MaterialX. On AliciaSolid.vrm that is 12 of 12 materials.

What it fixes here

Candidate 2 from the investigation list (the emissive/unlit approximation) was a real contributor, and the defect it caused was not only colour.

/preview draws this asset's alpha-blended hair and eyelashes as opaque quads: at the forehead the front bang strands come out as hard rectangular blocks, and the eyelash geometry sits on the face as a solid shape. /mtlx composites them. Rendered offscreen with usdrecord at the same camera, preview-only vs MaterialX, the difference is concentrated exactly on the bangs and the lash line.

The reason /preview looks like that is UsdPreviewSurface's unlit routing: base colour goes to emissiveColor, and the alpha that should blend it never gets the material tagged as translucent in a way that survives the toon geometry. The MaterialX realization states glTF alpha coverage natively (alpha_mode / alpha_cutoff), so the renderer performs the blend or the cutout itself.

What is now ruled out, with measurements rather than reasoning

• Colour management is not the cause. The base-colour texture is decoded from sRGB in both realizations, and alpha is not decoded with the colour. Measured on the pinned runtime with a texture whose alpha is exactly 128/255 = 0.502: it survives a MASK cutoff of 0.45 and is discarded at 0.55, and the srgb_texture and raw renders are identical for both MASK and BLEND. A gamma-decoded alpha would have landed near 0.216 and failed the 0.45 cutoff. MaterialX's own srgb_texture_to_lin_rec709_color4 agrees: it converts RGB and passes the fourth channel through untouched.
• COLOR_0 — already established as absent on every primitive of this asset (comment above).
• Base-colour factor × texture — landed earlier; Alicia's factor is the default (1,1,1,1), so it does not affect this reproduction either way.

What remains

The shade path. _ShadeTexture, _ShadeColor, _ShadeShift and _ShadeToony are still preserved only as vrm:mtoon:raw, and no realization reads them. The 2026-08-12 conclusion therefore stands — the remaining blown-out appearance is the missing main-vs-shade selection — with two of its confounders now removed and the alpha defect that was sitting on top of it gone.

That work is P5 Step 3 (the typed VrmMToonAPI) plus the MToon follow-up in material policy §7.2, not something Step 2 was scoped to do.

A note on the node choice, because it reads backwards

The MaterialX terminal is gltf_pbr with its lit response zeroed (base_color = 0, specular = 0) and the colour on emissive — not MaterialX's own surface_unlit. That looks like the PreviewSurface workaround this issue is about, so here is what was measured on OpenUSD 26.08 / MaterialX 1.39.5 before choosing it:

Terminal	Result in Storm
ND_surface_unlit	fails to compile — GLSL references undeclared u_envRadianceMips / u_envLightIntensity / u_envMatrix; the prim then draws as hdSt's flat grey fallback
ND_convert_color4_surfaceshader	fails to compile, same undeclared uniforms
ND_surface + EDF, no BSDF	compiles and renders, but opacity has no effect — which would put the hair straight back to solid
ND_surface + EDF + a black BSDF	works, opacity included
ND_gltf_pbr_surfaceshader	works, and its alpha is read as glTF defines it

The common factor in the failures is a surface with no BSDF; a dome light does not help. hdSt picks the material tag from the terminal node's family, with dedicated rules for UsdPreviewSurface, standard_surface, open_pbr_surface and gltf_pbr — which is why standard_surface handles opacity correctly even though its own implementation graph ends in the same surface node that fails here.

Worth knowing for anything downstream: there is no fallback. A material whose MaterialX terminal cannot be built does not revert to /preview — it draws as hdSt's default surface, a flat grey, so the failure arrives looking like an untextured asset rather than like an error. The full table and the note to revisit it when the runtime moves are in material policy §5.2.1.

Acceptance criteria

• Inspect the source VRM/glTF for COLOR_0 — absent on every primitive.
• Author the corresponding USD colour primvar — not applicable to this asset; deliberately not authored, since a displayColor that no material graph multiplies would preserve data without changing the result.
• Verify the unlit/MToon mapping does not overdrive emissive — unlit half done. The realization no longer drives base colour through a PreviewSurface emissive input, and factor × texture semantics are preserved. The MToon half (shade colour/texture) is untouched.
• Add a focused fixture/regression test — a UnlitCutout fixture material (unlit + textured + alpha-masked, the combination an avatar is actually made of) covering sampled alpha, the factor multiply, the sRGB decode and the sampler wrap-mode translation; plus a check that every info:id inside /mtlx resolves in the Sdr registry, since a misspelled ND_* id is silent at author time and fatal at render time.
• Compare source VRM and converted USD under the same camera — done between the two realizations (fixed camera, offscreen usdrecord), not yet against the VRM web viewer. That comparison is the right acceptance gate for the shade path and should be made there.

Baseline note: the frozen baselines gained the MaterialX networks and nothing else. Across all 28 inputs, no /preview shader, graph output or universal terminal moved or changed value — verified mechanically rather than by eye, so nothing this issue previously measured against has shifted underneath it.

[snkmcb]

hdStorm defects found while doing the above

Splitting these out from the Step 2 update because they are renderer defects rather than importer ones, and because both were only found by trying the obvious thing first and watching it not work. Both reduce to a single self-contained stage, included below, and are written to be liftable into an upstream report as-is.

Environment: OpenUSD 26.08 (PXR_VERSION 2608), MaterialX 1.39.5, Storm / HgiGL, Windows x86-64. Every image below is usdrecord --renderer Storm --camera /Root/Cam, so no interactive session and no window capture is involved — the two stages in a pair differ only in the terminal node.

Common shape: both defects appear only on a MaterialX surface shader with no BSDF. That is exactly the shape of an unlit material, which is what makes them expensive for a toon/VRM pipeline: the whole reason to reach for MaterialX here was to stop expressing unlit as "PBR with the lighting zeroed", and these are why we could not.

---

A. Surface shaders with no BSDF fail to compile

ND_surface_unlit and ND_convert_color4_surfaceshader both produce a fragment shader referencing environment-lighting uniforms that were never declared. The program fails to link, and the prim is then drawn with hdSt's default surface — a flat grey. It is not skipped, and it does not fall back to the material's universal outputs:surface terminal, so the failure arrives looking like an untextured asset rather than like an error.

> ND_surface_unlit renders flat grey; ND_gltf_pbr_surfaceshader renders correctly

Failed to compile shader (FRAGMENT_SHADER): 0(2147) : error C1503: undefined variable "u_envRadianceMips"
0(2159) : error C1503: undefined variable "u_envLightIntensity"
0(2235) : error C1503: undefined variable "u_envMatrix"
0(2905) : error C1503: undefined variable "u_envRadianceMips"
0(2919) : error C1503: undefined variable "u_envMatrix"
0(2920) : error C1503: undefined variable "u_envLightIntensity"
0(2925) : error C1503: undefined variable "u_envMatrix"
0(2926) : error C1503: undefined variable "u_envLightIntensity"

Failed to compile shader for prim /Root/Test.

Adding a DomeLight to the stage does not help. ND_gltf_pbr_surfaceshader, ND_UsdPreviewSurface_surfaceshader, and ND_surface with a BSDF all compile on the same stage, so this is not a lighting-setup problem in the scene.

The reading that fits: the generated MaterialX code calls into the environment-radiance path unconditionally, while the glslfx that declares u_env* is only mixed in for terminals hdSt treats as lit.

---

B. ND_surface without a BSDF silently drops opacity

ND_surface does compile and render. But with only an EDF connected, opacity has no effect whatsoever — not attenuated, not mis-scaled, simply absent. The surface is drawn fully opaque.

> ND_surface with only an EDF ignores opacity; adding a black BSDF restores it

Rendered against an empty background instead of the backdrop, opacity = 0.25, sampling the centre pixel as RGBA:

Terminal	opacity / alpha	Centre RGBA
ND_surface, EDF only	0.25	(255, 0, 0, 255) — opaque, full intensity
ND_surface, EDF + a black oren_nayar_diffuse_bsdf	0.25	(137, 0, 0, 64)
ND_gltf_pbr_surfaceshader, alpha_mode = 2	0.25	(137, 0, 0, 64)

Framebuffer alpha is 1.0 in the first row and 0.251 in the other two, so the surface went through the opaque pass rather than being blended incorrectly. Authoring opacity as a plain value and connecting it to a node behave identically — both are ignored. Adding a BSDF that contributes nothing (color = (0, 0, 0)) is enough to restore correct behaviour, which is what makes this look like a defect rather than a semantic.

On a real asset this is the whole difference between hair that reads as hair and hair that reads as cardboard:

> AliciaSolid rendered with each terminal: solid strands versus alpha-blended ones

Where this probably lives. pxr/imaging/hdSt/materialXFilter.cpp: _GetMaterialTag dispatches on the terminal node's family, with dedicated rules for UsdPreviewSurface, standard_surface, open_pbr_surface, and gltf_pbr, and a generic fallback (_IsTransparentShader → _AddStrippedSurfaceNode → mx::isTransparentSurface) for everything else. On paper the generic path should reach the right answer here — _AddStrippedSurfaceNode carries float parameters and connections through, DEFAULT_INPUT_PAIR_LIST includes opacity, and 0.25 != 1.0 — so I did not isolate whether the tag comes out wrong, or the tag is right and the generated shader never writes the alpha. Someone with the codegen in front of them will get there faster than I did from the outside.

That dispatch also answers something that looks contradictory: standard_surface handles opacity correctly even though its own implementation nodegraph terminates in the very surface node that fails here. The tag decision never looks inside the implementation graph — only at the terminal's family — so the internal surface node is invisible to it.

---

Minimal reproduction

One stage, self-contained, no external assets. A red test quad in front of a green backdrop, with its own camera so the framing is fixed:

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

def Xform "Root"
{
    def Camera "Cam"
    {
        float focalLength = 50
        float2 clippingRange = (0.1, 1000)
        double3 xformOp:translate = (0, 0, 55)
        uniform token[] xformOpOrder = ["xformOp:translate"]
    }

    def Mesh "Backdrop" (
        prepend apiSchemas = ["MaterialBindingAPI"]
    )
    {
        float3[] extent = [(-12, -12, -2), (12, 12, -2)]
        int[] faceVertexCounts = [4]
        int[] faceVertexIndices = [0, 1, 2, 3]
        rel material:binding = </Root/Green>
        point3f[] points = [(-12, -12, -2), (12, -12, -2), (12, 12, -2), (-12, 12, -2)]
    }

    def Material "Green"
    {
        token outputs:surface.connect = </Root/Green/surface.outputs:surface>

        def Shader "surface"
        {
            uniform token info:id = "UsdPreviewSurface"
            color3f inputs:diffuseColor = (0, 0, 0)
            color3f inputs:emissiveColor = (0, 0.6, 0.2)
            float inputs:roughness = 1
            token outputs:surface
        }
    }

    def Mesh "Test" (
        prepend apiSchemas = ["MaterialBindingAPI"]
    )
    {
        float3[] extent = [(-5, -5, 0), (5, 5, 0)]
        int[] faceVertexCounts = [4]
        int[] faceVertexIndices = [0, 1, 2, 3]
        rel material:binding = </Root/M>
        point3f[] points = [(-5, -5, 0), (5, -5, 0), (5, 5, 0), (-5, 5, 0)]
    }

    def Material "M"
    {
        token outputs:mtlx:surface.connect = </Root/M/mtlx/surface.outputs:surface>

        def NodeGraph "mtlx"
        {
            token outputs:surface.connect = </Root/M/mtlx/surface.outputs:surface>

            # --- Defect A: fails to compile, draws flat grey. -----------------
            def Shader "surface"
            {
                uniform token info:id = "ND_surface_unlit"
                float inputs:emission = 1
                color3f inputs:emission_color = (1, 0, 0)
                float inputs:opacity = 1
                token outputs:surface
            }

            # --- Defect A control: same stage, renders red. -------------------
            # def Shader "surface"
            # {
            #     uniform token info:id = "ND_gltf_pbr_surfaceshader"
            #     color3f inputs:base_color = (0, 0, 0)
            #     color3f inputs:emissive = (1, 0, 0)
            #     float inputs:metallic = 0
            #     float inputs:roughness = 1
            #     float inputs:specular = 0
            #     float inputs:alpha = 1
            #     int inputs:alpha_mode = 0
            #     token outputs:surface
            # }

            # --- Defect B: renders, but opacity = 0.25 is ignored. ------------
            # def Shader "emission"
            # {
            #     uniform token info:id = "ND_uniform_edf"
            #     color3f inputs:color = (1, 0, 0)
            #     token outputs:out (
            #         renderType = "EDF"
            #     )
            # }
            #
            # def Shader "surface"
            # {
            #     uniform token info:id = "ND_surface"
            #     token inputs:edf (
            #         renderType = "EDF"
            #     )
            #     token inputs:edf.connect = </Root/M/mtlx/emission.outputs:out>
            #     float inputs:opacity = 0.25
            #     token outputs:surface
            # }

            # --- Defect B control: add a BSDF that contributes nothing, and
            #     the same opacity is honoured. -------------------------------
            # def Shader "diffuse"
            # {
            #     uniform token info:id = "ND_oren_nayar_diffuse_bsdf"
            #     color3f inputs:color = (0, 0, 0)
            #     token outputs:out (
            #         renderType = "BSDF"
            #     )
            # }
            #
            # def Shader "surface"
            # {
            #     uniform token info:id = "ND_surface"
            #     token inputs:bsdf (
            #         renderType = "BSDF"
            #     )
            #     token inputs:bsdf.connect = </Root/M/mtlx/diffuse.outputs:out>
            #     token inputs:edf (
            #         renderType = "EDF"
            #     )
            #     token inputs:edf.connect = </Root/M/mtlx/emission.outputs:out>
            #     float inputs:opacity = 0.25
            #     token outputs:surface
            # }
        }
    }
}

Uncomment one surface block at a time and render:

usdrecord --renderer Storm --camera /Root/Cam --imageWidth 480 repro.usda out.png

Expected in all four cases: a red (or half-transparent red) quad on a green field. Actual: flat grey for defect A, fully opaque red for defect B.

---

Why this matters beyond the two nodes

The two MaterialX constructs that say "unlit" directly are unusable, and the one generic construct that does work silently discards transparency. That is what pushed the importer to gltf_pbr with the lit response zeroed — correct for a glTF-sourced asset, and the reason the shipped graph looks like an approximation of the very thing it was trying to avoid.

There is also nothing to catch it: a consumer that authors both a MaterialX and a PreviewSurface realization gets no safety from having done so, because the broken MaterialX terminal is used anyway and simply renders grey.

Recorded in material policy §5.2.1 with a note to re-test the table when the runtime moves; if a later OpenUSD renders surface_unlit, that is the better statement of intent and the graph should change to it.