Add Blender texture graph fidelity

[Ahmed-Hindy]

Summary

• add Blender graph support for UV Map and Separate Color nodes
• preserve image Vector/Alpha sockets and resolve Blender-relative texture paths during ingest
• add MaterialX/OpenPBR USD mappings for texture coordinates and packed-channel extraction
• translate generic connection socket names back to renderer/USD socket names when authoring USD shader links

Review Notes

• The new USD mappings are scoped to MaterialX-family targets where the node definitions are known.
• Arnold/Redshift support for these Blender utility nodes is intentionally not claimed in this slice.

Validation

• uv --native-tls run pytest -m blender
• uv --native-tls run ruff check src/materials_processor/mappings.py src/materials_processor/dcc/blender/traverser.py src/materials_processor/usd/graph_builder.py src/materials_processor/usd/mappings.py tests/test_blender_support.py tests/test_usd_json_conversion.py tests/test_blender_runtime.py
• uv --native-tls build

Full local pytest result: 128 passed, 21 skipped, 1 xfailed.

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds support for UV mapping and color-separation shader nodes in Blender and USD material workflows by enhancing socket type detection, extending renderer-specific node and parameter mappings, and validating the feature with comprehensive end-to-end tests.

Changes

UV Mapping and Color Separation Feature

Layer / File(s)	Summary
Blender socket type mapping and image path resolution src/materials_processor/dcc/blender/traverser.py	Added _socket_generic_type to map Blender socket types to generic parameter types with node/socket-specific handling, and _resolve_blender_image_path to convert image paths via bpy.path.abspath with safe fallback. Updated _convert_parms_to_dict and output parameter construction to use these helpers.
Generic type and parameter mappings src/materials_processor/mappings.py	Extended REGULAR_NODE_TYPES_TO_GENERIC for UV mapping (ND_geompropvalue_vector2 / ShaderNodeUVMap → GENERIC::uvmap) and color separation (ND_separate3_color3 / ShaderNodeSeparateColor → GENERIC::separate_color) under mtlx and openpbr. Extended REGULAR_PARAM_NAMES_TO_GENERIC with image node (texcoord, out), UV, and color-separation channel parameter mappings.
USD graph builder parameter translation src/materials_processor/usd/graph_builder.py	Added _nodeinfo_by_path, _renderer_parm_name, and _connection_parm_name helpers to translate generic parameter names to renderer-specific USD socket names. Updated set_shader_connections to compute src_parm / dst_parm via these helpers, including fallback source endpoint remapping.
USD renderer node type and attribute support src/materials_processor/usd/mappings.py	Added GENERIC::uvmap and GENERIC::separate_color entries to GENERIC_NODE_TYPES_TO_REGULAR_USD as Shader prims with mtlx/openpbr info_id. Extended _ATTRIB_TYPE_CASTERS for vector2, vector3, and vector4 USD conversions.
Blender traverser and mock node test coverage tests/test_blender_support.py	Extended FakeNode to mock ShaderNodeUVMap. Added helpers _link, _iter_nodeinfos, _make_packed_texture_fake_blender_material for linked mock graphs. Updated and added assertions for UV/color-separation mappings. Added test_blender_traverser_preserves_packed_texture_graph to validate packed-texture traversal with correct parameter values, types, connection paths, and no mapping warnings.
Blender runtime and USD recreation integration tests tests/test_blender_runtime.py, tests/test_usd_json_conversion.py	Added Blender runtime test to extract material graph data from a local .blend file and validate node types, outputs, and absolute texture paths. Added USD recreation test to build and recreate a UV/color-separation node graph via USDMaterialRecreator, validating shader IDs and USD connection paths.

Sequence Diagram

sequenceDiagram
  participant BlenderTraverser
  participant MappingTable
  participant USDGraphBuilder
  participant USDRenderer
  
  BlenderTraverser->>BlenderTraverser: _socket_generic_type detects UV/separation socket
  BlenderTraverser->>MappingTable: query REGULAR_NODE_TYPES_TO_GENERIC
  MappingTable-->>BlenderTraverser: GENERIC::uvmap or GENERIC::separate_color
  BlenderTraverser->>BlenderTraverser: extract parameters for identified node type
  
  BlenderTraverser-->>USDGraphBuilder: NodeInfo with generic type
  USDGraphBuilder->>MappingTable: _renderer_parm_name via REGULAR_PARAM_NAMES_TO_GENERIC
  MappingTable-->>USDGraphBuilder: renderer-specific parameter names
  USDGraphBuilder->>USDGraphBuilder: _connection_parm_name computes src/dst parameters
  USDGraphBuilder->>USDRenderer: set_shader_connections with mapped parameters
  
  USDRenderer->>MappingTable: GENERIC_NODE_TYPES_TO_REGULAR_USD lookup
  MappingTable-->>USDRenderer: USD Shader prim info_id
  USDRenderer->>USDRenderer: create Shader nodes and wire connections

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Ahmed-Hindy/Materials-Processor#26: Modifies src/materials_processor/usd/graph_builder.py's shader connection wiring and parameter name mapping logic, directly related to this PR's generic-to-renderer parameter translation.
• Ahmed-Hindy/Materials-Processor#42: Introduced the Blender shader traversal logic in src/materials_processor/dcc/blender/traverser.py that this PR extends with socket-type mapping and image-path resolution.

Poem

🐰 Through shaders woven, textures flow,
UV maps guide the pixels' dance,
Colors split and rejoin below,
From Blender's nodes to USD's expanse. ✨

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 25.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and concisely summarizes the main change: adding support for Blender texture graph fidelity through UV Map and Separate Color nodes with proper path resolution and USD mappings.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch codex/blender-texture-graph-fidelity

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}