Add Blender USD export CLI

[Ahmed-Hindy]

Summary

• add materials-processor-blender export-usd for headless Blender material export
• export Blender scene node materials to MaterialX and/or OpenPBR USD files
• write blender_material_graphs.json and export_report.json alongside the USD outputs
• add a script wrapper at scripts/export_blender_materials_to_usd.py

Review Notes

Changed-code review found and fixed one CLI behavior bug before publishing: --target originally defaulted to all even when a single explicit target was passed, so --target openpbr still exported MaterialX. The PR now defaults only when no target is provided and has regression coverage for single-target aliases.

Validation

• uv --native-tls run pytest tests/test_blender_cli.py tests/test_blender_runtime.py tests/test_usd_json_conversion.py
• uv --native-tls run ruff check
• uv --native-tls run pytest
• Real-scene CLI export:
  • uv --native-tls run materials-processor-blender export-usd "G:\Projects\AYON_PROJECTS\mo_ashraf\Mojar_01\sh_001\work\lighting\mo_sh_001_lighting_v005.blend" --out-dir <temp> --target openpbr --timeout 300
  • confirmed single-target export reports only OpenPBR, with 11 material prims and no read failures

Remaining Known Limitations

• The real scene still reports unsupported Blender ShaderNodeGroup nodes for felt_fabric_03 and old_gold_04.
• Marble.012 still references two missing external BlenderKit texture files under C:\PROJECT\BlenderKit\....

Summary by CodeRabbit

Release Notes

• New Features
  • Added command-line tool for exporting Blender materials to USD MaterialX and OpenPBR formats.
  • Supports headless processing of Blender scene materials.
  • Generates industry-standard shader definitions for multiple target renderers.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

This PR adds a complete CLI pipeline for exporting Blender materials to USD MaterialX/OpenPBR formats. The implementation extracts material node graphs from Blender scenes via headless execution, converts them into USD stages for each target renderer, and exposes the workflow through a command-line interface with runtime discovery and target selection.

Changes

Blender Material Export CLI

Layer / File(s)	Summary
Blender Graph Extraction Pipeline src/materials_processor/dcc/blender/cli.py (constants, embedded script, extraction)	Defines target aliases, helper functions to rebuild graph objects from JSON, generates an embedded Blender Python script that reads materials and collects metadata, and implements extraction function that spawns headless Blender with configurable timeout and parses the returned JSON payload.
USD Export Pipeline and Validation Tests src/materials_processor/dcc/blender/cli.py (build & orchestration), tests/test_blender_cli.py (fixtures, build/export tests)	Converts extracted JSON graphs into USD stages for each renderer target, writes materials and validates readability, collects shader-ID counts and material prim paths, wraps the full export with intermediary JSON and final report generation, and validates USD output and orchestration via test fixtures and assertions.
CLI Interface, Dispatch, and Target Resolution src/materials_processor/dcc/blender/cli.py (argument parsing, main dispatcher), tests/test_blender_cli.py (integration tests)	Parses export-usd command arguments with target selection, runtime discovery flags, and timeout; maps target aliases and "all" to de-duplicated renderer tuples; implements main entry point that resolves runtime, orchestrates export, prints JSON report, and returns exit codes; validates target expansion and CLI dispatch behavior.
Console Entry Point Registration pyproject.toml, scripts/export_blender_materials_to_usd.py	Registers materials-processor-blender console script pointing to the CLI main function in pyproject.toml and provides a standalone wrapper script that invokes the CLI via SystemExit.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Poem

🐰 Through Blender's nodes, a rabbit hops with glee,
Extracting graphs to MaterialX and OpenPBR decree,
USD stages bloom where materials grow,
CLI flags guide the export flow,
From blend to stage, our craft runs free!

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 35.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
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title 'Add Blender USD export CLI' clearly and concisely summarizes the main change: adding a new CLI command for exporting Blender materials to USD 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-cli-export

---

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