Add Blender reader writer adapters

[Ahmed-Hindy]

Summary

• add BlenderMaterialReader and BlenderMaterialWriter implementations for the core adapter contracts
• route the Blender addon and headless runtime smoke through ConversionService
• sanitize USD material and shader prim names using OpenUSD identifier rules so Blender names with spaces can build USD prims
• expand Blender 4.x Principled BSDF parameter mappings
• add unit coverage for Blender reader/writer conversion and USD-safe prim names

Real asset check

Tested against copied local asset Tie Defender.blend, material T_TieDefender_01_CS_Mat:

• Blender ingestion succeeds
• USD creation now succeeds for mtlx, arnold, and openpbr targets
• remaining known gaps are ShaderNodeUVMap, ShaderNodeSeparateColor, image alpha/vector mapping, and texture path packaging

Validation

• uv --native-tls run pytest tests/test_blender_support.py tests/test_usd_json_conversion.py
• uv --native-tls run pytest tests/test_blender_support.py tests/test_blender_runtime.py tests/test_usd_json_conversion.py tests/test_public_imports.py tests/test_core_conversion.py
• uv --native-tls run pytest -m blender
• uv --native-tls run python scripts/validate_blender_runtime.py --smoke-material --timeout 120
• uv --native-tls run ruff check src tests scripts
• uv --native-tls run pytest
• uv --native-tls build

Summary by CodeRabbit

Release Notes

• New Features

  • Enhanced Blender material conversion support with improved adapter integration
  • Expanded Principled BSDF parameter mapping for more complete material capture

• Bug Fixes

  • Improved material and shader identifier handling in USD exports for safer naming

• Tests

  • Added comprehensive tests for material conversion and round-tripping
  • Enhanced validation for material prim name sanitization

[coderabbitai]

📝 Walkthrough

Walkthrough

The PR introduces a Blender material adapter framework to standardize conversion workflows and adds USD identifier safety for collision-free prim naming. New BlenderMaterialReader and BlenderMaterialWriter classes replace inlined material traversal in addon and runtime code. Principled BSDF parameter coverage expands significantly. USD graph builder now sanitizes DCC names and detects naming collisions using Tf utilities.

Changes

Blender Material Adapter Framework

Layer / File(s)	Summary
Blender adapter module and core classes src/materials_processor/dcc/blender/adapters.py	BlenderMaterialReader.read() traverses Blender material nodes, standardizes them, extracts material name, and returns MaterialGraph. BlenderMaterialWriter.write() resolves target material context (existing object, mapping, string, or None), recreates the graph via BlenderNodeRecreator, raises RuntimeError on failure, and returns result. Helpers handle target resolution and enforce Blender context requirements.
Adapter integration in addon and runtime src/materials_processor/dcc/blender/addon.py, src/materials_processor/dcc/blender/runtime.py	Addon ingestion refactored from inlined traverser→standardizer→MaterialData pipeline to single BlenderMaterialReader().read() call. Embedded smoke-test script updated to read source material, convert via ConversionService, and compute metrics from converted graph instead of manual traversal/standardization/recreation.
Extended Principled BSDF parameter mapping src/materials_processor/mappings.py	REGULAR_PARAM_NAMES_TO_GENERIC['ShaderNodeBsdfPrincipled'] mapping expanded from small subset (base color, metallic/roughness, IOR, alpha, normal, emission, coat, sheen) to comprehensive set including subsurface, anisotropy/tangent, transmission, sheen roughness/tint, thin-film, coat tint/normal, and BSDF surface output routing.
Adapter and integration test coverage tests/test_blender_support.py, tests/test_public_imports.py	Test helper _make_simple_fake_blender_material() constructs minimal fake Blender materials. New adapter tests validate BlenderMaterialReader producing correct MaterialGraph, BlenderMaterialWriter reconstructing target, and ConversionService round-tripping. Expanded Principled BSDF test covers larger input set and verifies no unsupported-parameter warnings. Public imports test includes new adapters module.

USD Prim Naming Safety

Layer / File(s)	Summary
USD-safe identifier helpers and collision tracking src/materials_processor/usd/graph_builder.py	Added Tf import for USD identifier safety. New _usd_prim_name() sanitizes DCC names via Tf.MakeValidIdentifier. New _unique_child_path() generates collision-free child prim paths with per-parent _used_child_names state tracking.
USD builder method refactoring for consistent prim paths src/materials_processor/usd/graph_builder.py	_create_shader_id() uses GENERIC::null mapping fallback when generic_type is falsy. _apply_parameters() adds early return when node_type missing. create_material_prim() and set_output_connections() derive material prim path via _material_prim_path() helper. create_child_shaders() uses _unique_child_path() for USD-safe shader naming and falls back to GENERIC::null for missing node types.
USD prim name sanitization and safety tests tests/test_usd_json_conversion.py	Test imports updated to include NodeInfo and OutputConnection. New test_usd_recreator_sanitizes_material_and_shader_prim_names() creates USD stage with unsanitized names/paths, verifies resulting Material and Shader prims exist at sanitized Sdf.Path locations, and asserts shader info:id and material outputs include expected MaterialX surface output.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

• Ahmed-Hindy/Materials-Processor#42: New BlenderMaterialReader/Writer adapters and updated Blender addon/runtime integration directly replace the traverser/standardizer/recreator workflow introduced in PR #42.
• Ahmed-Hindy/Materials-Processor#26: Both PRs modify src/materials_processor/usd/graph_builder.py with overlapping edits to shader/material prim naming, id handling, and methods like _create_shader_id, _apply_parameters, create_child_shaders, create_material_prim, and set_output_connections.
• Ahmed-Hindy/Materials-Processor#41: Blender adapter and runtime/addon rewrite to read/write via adapters and route through ConversionService is directly tied to the adapter/conversion-service refactor introduced in PR #41.

Poem

🐰 Adapters bloom like carrots bright,
USD names now shine in safety's light,
Blender graphs convert with grace,
Each collision finds its proper place.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 41.38% 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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: adding Blender reader and writer adapter classes to standardize material conversion between Blender and the project's neutral MaterialGraph format.
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.

_{✏️ 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-reader-writer-adapters

---

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.}

[coderabbitai]

🧹 Nitpick comments (1)

tests/test_usd_json_conversion.py (1)

245-279: ⚡ Quick win

Consider covering the collision-suffix path.

This test exercises name sanitization, but the new _unique_child_path() collision handling (the _2, _3 suffixing) is the other half of this PR and currently has no coverage. Two sibling nodes whose names sanitize to the same identifier (e.g. "My Node" and "My/Node") would hit that branch.

A small case with two such shaders asserting both distinct prims exist would lock in the dedup behavior.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/test_usd_json_conversion.py` around lines 245 - 279, Add a second
NodeInfo whose name sanitizes to the same identifier so the _unique_child_path()
collision branch is exercised: in
test_usd_recreator_sanitizes_material_and_shader_prim_names create a second
NodeInfo (e.g., node_name="Principled/BSDF", node_path="/mat/My
Material/Principled/BSDF") alongside the existing one, include both in
nodeinfo_list passed to USDMaterialRecreator (keep the existing OutputConnection
for the output shader), run .run(), and then assert both shader prims exist
under the material (e.g., UsdShade.Shader.Get(stage,
Sdf.Path("/materials/My_Material/Principled_BSDF")) and
UsdShade.Shader.Get(stage,
Sdf.Path("/materials/My_Material/Principled_BSDF_2"))), to lock in the
collision-suffix behavior from _unique_child_path().

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@tests/test_usd_json_conversion.py`:
- Around line 245-279: Add a second NodeInfo whose name sanitizes to the same
identifier so the _unique_child_path() collision branch is exercised: in
test_usd_recreator_sanitizes_material_and_shader_prim_names create a second
NodeInfo (e.g., node_name="Principled/BSDF", node_path="/mat/My
Material/Principled/BSDF") alongside the existing one, include both in
nodeinfo_list passed to USDMaterialRecreator (keep the existing OutputConnection
for the output shader), run .run(), and then assert both shader prims exist
under the material (e.g., UsdShade.Shader.Get(stage,
Sdf.Path("/materials/My_Material/Principled_BSDF")) and
UsdShade.Shader.Get(stage,
Sdf.Path("/materials/My_Material/Principled_BSDF_2"))), to lock in the
collision-suffix behavior from _unique_child_path().

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 9206cf64-cad3-4f2f-9570-1ab3a273463e

📥 Commits

Reviewing files that changed from the base of the PR and between fbec92f and b53a498.

📒 Files selected for processing (8)

• src/materials_processor/dcc/blender/adapters.py
• src/materials_processor/dcc/blender/addon.py
• src/materials_processor/dcc/blender/runtime.py
• src/materials_processor/mappings.py
• src/materials_processor/usd/graph_builder.py
• tests/test_blender_support.py
• tests/test_public_imports.py
• tests/test_usd_json_conversion.py