[Render] Python renderer produces different results from C++ MaterialXTest for procedural/convolution/color_mgmt materials

[ppenenko]

Description

When comparing Python pytest renders against C++ MaterialXTest baselines (both using the same _options.mtlx scope), several material categories produce visually different results. These failures occur identically in both TestRenderStdlibMaterials (no overrides) and TestRenderMetashadePassthru, confirming they are Python/C++ renderer differences, not Metashade override issues.

Failing materials

Material	Subtest	Mean FLIP	Category
standard_surface_onyx_hextiled	M_OnyxHextiled	0.1813	Non-deterministic procedural
flake	test_flake2d	0.0742	Non-deterministic procedural
blur	blur_cellnoise/out	0.3178	Convolution
heighttonormal	vec_out	0.1496	Convolution / normals
heighttonormal	ss_out	0.0997	Convolution / normals
heighttonormal	usd	0.0623	Convolution / normals
color3_vec3_cm_test	height_to_normal_cm/out	0.1338	Color management

Observations from visual inspection

• heighttonormal subtests show what appears to be inverted or flipped normals relative to the C++ baseline
• hextiled and flake show random pattern differences (likely non-deterministic seeds)
• blur_cellnoise shows a completely different noise pattern
• color3_vec3_cm_test failure is in the height_to_normal_cm subtest (same normal issue)

Potential causes

1. Convolution / heighttonormal: fileTextureVerticalFlip or coordinate convention difference between Python mxrenderer.py and C++ ShaderRenderTester
2. Procedurals (flake, hextiled): GPU-side random seeds differ between render sessions — inherently non-deterministic
3. Color management: may involve unsupported color space transforms (C++ logs show "Unsupported color space transform" warnings)

Note on add_additional_test_streams

The Python implementation of add_additional_test_streams differs from C++ in 10/11 stream fill algorithms, but none of the failing materials use those streams. They only depend on i_texcoord_0 from the OBJ loader. The stream differences would affect geompropvalue.mtlx and streams.mtlx (not in _options.mtlx scope).

Related

• [Render] Metashade override library loading breaks UsdPreviewSurface rendering #26 — separate issue where Metashade overrides cause UsdPreviewSurface to render black

[ppenenko]

Investigation: texcoordVerticalFlip mismatch

Root cause analysis

The Python renderer (mxrenderer.py:269) had texcoordVerticalFlip hardcoded to false, while C++ (RenderGlsl.cpp:325) sets it to true for sphere.obj and plane.obj:

# Python (before fix)
texcoordVerticalFlip = False  # True if mx.FilePath(fileName).getExtension() == 'obj' else False

// C++ (RenderGlsl.cpp, RenderSlang.cpp, RenderMsl.mm)
bool texcoordVerticalFlip = baseName == "sphere.obj" || baseName == "plane.obj";

Stream analysis

None of the five failing materials use streams from add_additional_test_streams (those synthetic streams only matter for streams.mtlx, geompropvalue.mtlx, and struct_texcoord). All five materials use built-in UV0 via texcoord_0, and some (heighttonormal/ss_out, heighttonormal/usd, flake) additionally use Nworld/Tworld/Bworld mesh streams.

For heighttonormal specifically, the node computes its tangent frame entirely from screen-space derivatives (dFdx/dFdy of UV), not from mesh normal/tangent streams. Flipped UVs directly invert derivative signs, explaining the inverted-normal appearance.

Fix attempt: branch metashade/vflip-fix

Applied the one-line fix to match C++ behavior:

baseName = mx.FilePath(fileName).getBaseName()
texcoordVerticalFlip = baseName in ("sphere.obj", "plane.obj")

Results: mixed — fix made things worse overall

Subtest	Before fix	After fix	Change
height_to_normal_cm/out	0.1338	0.1262	slightly better
heighttonormal/vec_out	0.1496	0.1535	slightly worse
heighttonormal/ss_out	0.0997	0.1281	worse
heighttonormal/usd	0.0623	0.0789	worse
M_OnyxHextiled	0.1813	0.1817	same
blur_cellnoise/out	0.3178	passed	fixed
blur_color3/out etc.	passed	~0.35	6 new failures
normalmap_cm/out	passed	0.5138	new failure
hextiled subtests	passed	failing	new failures

The fix resolved blur_cellnoise/out but introduced new failures in blur, hextiled, and normalmap subtests that were previously passing.

Hypothesis: double flip interaction

Both texcoordVerticalFlip (geometry UV flip) and fileTextureVerticalFlip (shader gen option, set to true on mxrenderer.py:569) are active. With both enabled:

• Texture-sampled materials (blur, hextiled, normalmap) get a double flip — geometry flips V, then shader gen flips it again during sampling — changing the net UV orientation vs. before
• Derivative-based materials (heighttonormal) see flipped raw UV in derivatives, but texture samples cancel out

The C++ test presumably has a different interaction between these two flips, or sets fileTextureVerticalFlip differently.

Next steps

1. Compare fileTextureVerticalFlip setting between C++ test harness and Python
2. Investigate whether C++ cancels out the double flip internally
3. Visual inspection of heatmaps to understand the nature of the new failures
4. Consider whether fileTextureVerticalFlip should be false in Python (relying solely on geometry V-flip)