[MAX-MAT-003] Stop leaking Max wireframe color into primvars:displayColor

[doug-smith-miris]

Summary

Stacked on top of #36 (MAX-MAT-001) and #37 (MAX-MAT-002). Until those PRs merge, this PR's diff includes their commits too — once they merge into dev, this PR's diff will collapse to just the MAX-MAT-003 changes (1 commit, 4 files).

MaxUsd::MeshConverter::ConvertToUSDMesh unconditionally authored every mesh's primvars:displayColor from the source 3ds Max node's viewport wireframe color whenever no explicit displayColor primvar had already been written. The wireframe color is a scene-graph organizational tag — a hue assigned to a node so it stands out in the viewport — and has no relationship to the surface's actual color. USD, in contrast, defines primvars:displayColor as the surface color a consumer should use when the bound UsdShadeMaterial cannot be evaluated (the "fallback" color).

On the diagnostic corpus, 6/6 meshes carry a displayColor that disagrees with their bound material:

Mesh	Bound material	displayColor (buggy)	displayColor (fixed) = material diffuse
Ground	Floor	(0.53, 0.84, 0.40)	(0.78, 0.78, 0.80)
Teapot	Gold	(0.85, 0.89, 0.68) (pale green)	(0.92, 0.71, 0.24) (gold)
Sphere	RedPlastic	(0.67, 0.38, 0.35) (muddy pink)	(0.78, 0.16, 0.16) (red)
Box	BrushedSteel	(0.77, 0.88, 0.64)	(0.71, 0.71, 0.74) (steel)
Cylinder	BlueCeramic	(0.33, 0.50, 0.08) (olive)	(0.16, 0.35, 0.78) (blue)
Torus	Copper	(0.22, 0.49, 0.44)	(0.78, 0.43, 0.27) (copper)

The bug is invisible to PBR-capable USD renderers (Hydra Storm, Karma, RenderMan) — they evaluate the bound MaterialX/UsdPreviewSurface and never read displayColor. It surfaces in fallback consumers:

• Minimal Hydra delegates and scene-graph viewers without MaterialX.
• ARKit Quick Look paths / iOS USDZ thumbnailers without MaterialX.
• The usdview "displayColor" overlay used to QA primvars.
• USDZ packagers that fall back to displayColor when shaders can't be inlined for distribution.

What changed

• src/MaxUsd/MeshConversion/MeshConverter.cpp: in the post-conversion fallback block, derive displayColor from node->GetMtl()->GetDiffuse() when a material is bound; fall back to the wireframe color only when none is. Mtl::GetDiffuse(int mtlNum = 0, BOOL backFace = FALSE) is the universal Max SDK accessor for a material's "main" diffuse and is what LastResortUSDPreviewSurfaceWriter already uses to author the bound material's inputs:diffuseColor, so the two values are round-trip-identical modulo float32 quantization. For a MultiMtl, GetDiffuse(0) returns the first sub-material's diffuse — still materially closer to the artist's intent than the wireframe color.
• doc/translation-mapping.md: adds a new Status row + Notes section + change-log entry under MAX-MAT-003.
• doc/changelog.md: adds an Unreleased fix entry.
• src/Tests/Integration/io_color_n_visibility_test.ms: adds test_display_color_uses_material_diffuse_when_bound (positive fix — a box with a green-diffuse Standard material and a red wireframe must export displayColor = green) and test_display_color_still_uses_wire_color_when_no_material (negative case — same box without a material must still export displayColor = wireframe red).

Bounds (where the fix conservatively does nothing)

• usdMesh.GetDisplayColorAttr().IsAuthored() is already true — the vertex-color → displayColor channel mapping (SetChannelPrimvarMapping 0 "displayColor") ran first and wrote the artist-authored value. We never overwrite it. The existing test_display_color_override continues to pass.
• node->GetMtl() == nullptr — no material bound. The wireframe color is the best representational color we have, so the previous behavior is preserved. The existing test_io_display_color continues to pass.

Validation

3ds Max is Windows-only and this repo builds via Visual Studio; build/run was deferred (same constraint as #36/#37). A Python validator that mirrors the C++ logic at the USD layer was run on the post-MAX-MAT-002 corpus.

Diagnostic corpus (complex_export_postfix.usda from #37): 6/6 meshes affected. The USDA diff is exactly 6 deletions + 6 additions (one primvars:displayColor line per mesh), every new value matches the bound material's UsdPreviewSurface inputs:diffuseColor verbatim. No structural changes.

PBR-path Karma renders of pre-fix and post-fix corpora are byte-identical (SHA-256 eaf38328…). This is the expected outcome and the success signal — PBR renderers don't read displayColor when a material is bound, so the fix is a no-op for the common case.

displayColor-fallback Karma renders (material:binding stripped from every mesh in both copies) ARE visually different (compare_side_by_side.png):

• Prefix: pale-green Teapot, muddy-pink Sphere, olive Cylinder, lime Box, light-green Floor — the wireframe-derived palette.
• Postfix: gold Teapot, red Sphere, blue Cylinder, grey Box, near-white Floor — the material-derived palette.

This is the observable behavior change for fallback consumers, and the visual proof that the fix is meaningful.

Reference files (validator + corpus)

Under agent/arch-builds/44966a53-f273-422c-9ce9-c1f2d7e477c1/ (outside the repo):

• normalize_display_color.py — USD-layer mirror of the C++ logic.
• strip_material_bindings.py — produces the fallback-render fixtures.
• complex_export_prefix.usda — input (post-MAX-MAT-002, pre-MAX-MAT-003).
• complex_export_postfix.usda — output (MAX-MAT-001+002+003-clean).
• complex_export_prefix_stripped.usda, complex_export_postfix_stripped.usda — material-binding-stripped fallback-render fixtures.
• render_karma_prefix.png, render_karma_postfix.png (byte-identical, PBR path).
• render_karma_prefix_stripped.png, render_karma_postfix_stripped.png (visually different, fallback path).
• render_unreal_reference.png — copy of render_karma_postfix_stripped.png (this fork targets 3ds Max, not Unreal).
• compare_side_by_side.png — labeled side-by-side fallback comparison.
• intended_example.md — detailed observable / fixture description for the auditor.

Test plan

• Reviewer confirms the C++ change is a minimal, conservative addition to the existing MeshConverter fallback (one condition added, the two pre-existing branches preserved).
• On a Windows 3ds Max install, run the geometry / color integration suite (io_color_n_visibility_test.ms) and confirm both new tests pass alongside the pre-existing test_io_display_color and test_display_color_override.
• On a Windows 3ds Max install, export a fresh scene with materials via the plugin and confirm primvars:displayColor on each mesh matches the bound material's diffuse color (and falls back to the wireframe color only on unbound meshes).

🤖 Generated with Claude Code