Add direct Blender camera framing tool

[Ker102]

Summary

• Add frame_camera_to_targets to both ViperMesh Blender addon copies.
• Wire the tool into the LangChain tool list, registry, filtering, system prompt, and lighting guide.
• Add focused regression coverage for camera reframing tool exposure, selection, prompt docs, and agent wiring.

Validation

• npx tsx scripts/test/test-blender-camera-framing-tool.ts
• python -m py_compile desktop/assets/vipermesh-addon.py public/downloads/vipermesh-addon.py
• npx tsx scripts/test/test-tool-guide-trigger-coverage.ts
• npx tsx scripts/test/test-blender-capability-inventory.ts
• npx tsc --noEmit --incremental false
• npm run lint (passes; existing baseline-browser-mapping age warning)
• git diff --check (passes; Windows line-ending warnings only)

Summary by CodeRabbit

• New Features

  • Added a camera framing tool that automatically repositions cameras toward target meshes to achieve desired composition and frame fill.
  • Supports configurable frame margins, distance constraints, and optional depth-of-field focus automation.

• Documentation

  • Updated lighting guide with revised validation workflow, including explicit framing steps and remediation guidance.
  • Updated system documentation to reflect the new camera framing capability in tool references.

[coderabbitai]

Caution

Review failed

Pull request was closed or merged during review

📝 Walkthrough

Walkthrough

A new frame_camera_to_targets command is added to BlenderMCPServer in both addon distributions, projecting target mesh bounding-box corners into camera view and repositioning the camera along its view ray to reach a configurable frame fill. The command is wired through the TypeScript agent, tool registry, filter categories, agent system prompt, and lighting guide, with test scripts asserting both implementation details and orchestration surface.

Changes

frame_camera_to_targets full-stack feature

Layer / File(s)	Summary
Blender addon: core Python implementation desktop/assets/vipermesh-addon.py, public/downloads/vipermesh-addon.py	Adds frame_camera_to_targets to BlenderMCPServer in both addon files: resolves studio bounds, projects bounding-box corners via world_to_camera_view, moves camera along view ray to desired_frame_fill, clamps to distance multipliers, optionally sets active camera and DOF focus. Dispatch entries added to _execute_command_internal in both files.
TypeScript tool wrapper and orchestration wiring lib/ai/agents.ts, lib/orchestration/tool-registry.ts, lib/orchestration/tool-filter.ts	Adds Zod-validated frameCameraToTargets tool wrapping executeMcpCommand, registered in ALL_TOOLS. Adds ToolMetadata entry under lighting category in TOOL_REGISTRY. Extends CATEGORY_GROUPS to include the tool in lighting and camera, and broadens the camera keyword regex.
System prompt, lighting guide, and capability inventory lib/orchestration/prompts/blender-agent-system.md, data/tool-guides/lighting-guide.md, docs/blender-mcp-capability-inventory.md	Adds frame_camera_to_targets(...) to the agent system prompt tool list and "When to Use Which Tool" table. Revises lighting guide workflow to direct reframing via frame_camera_to_targets with desired_frame_fill/frame_margin. Updates capability inventory command count to 90.
Test scripts scripts/test/test-blender-camera-framing-tool.ts, scripts/test/test-tool-guide-trigger-coverage.ts	New test script asserts Python method body contains expected identifiers and confirms the tool appears in orchestration surface (filter, prompt, agent source, lighting guide). Coverage test extended to require the tool in requiredGuidedTools.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• Ker102/ViperMesh#70: Shares the same tool-surface wiring points (tool-registry.ts, tool-filter.ts, agent allowlists) for registering camera-related MCP tools.
• Ker102/ViperMesh#81: Also extends BlenderMCPServer with a new camera command (aim_camera_at) using the same _execute_command_internal dispatch and matching TS/prompt/registry plumbing.
• Ker102/ViperMesh#85: Integrates new Blender MCP tools through the same shared orchestration wiring and extends the same requiredGuidedTools coverage assertion.

Suggested labels

documentation, backend, desktop, scripts

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 53.33% 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 accurately summarizes the main change: adding a direct Blender camera framing tool to the project.
Description check	✅ Passed	The description provides a clear summary, validation steps, and addresses the core purpose, though it deviates from the template structure by using a custom format instead of the specified sections.
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 feature/blender-camera-framing-tool

Warning

There were issues while running some tools. Please review the errors and either fix the tool's configuration or disable the tool if it's a critical failure.

🔧 ESLint

If the error stems from missing dependencies, add them to the package.json file. For unrecoverable errors (e.g., due to private dependencies), disable the tool in the CodeRabbit configuration.

ESLint install failed: dependency version conflict. Check your lock file or package.json.

---

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