Skip to content

Add direct camera aim tool#81

Merged
Ker102 merged 2 commits into
mainfrom
feature/camera-aim-tool
May 31, 2026
Merged

Add direct camera aim tool#81
Ker102 merged 2 commits into
mainfrom
feature/camera-aim-tool

Conversation

@Ker102
Copy link
Copy Markdown
Owner

@Ker102 Ker102 commented May 31, 2026

Summary

  • Add aim_camera_at to both Blender addon bundles.
  • Aim cameras at an object bounds center or explicit world-space point without generated Euler-rotation Python.
  • Optionally set the camera active and update DoF focus distance to the target.
  • Wire agent schema, registry/filter metadata, system prompt, camera guide, and test-pipeline allowlist.

Validation

  • python -m py_compile desktop/assets/vipermesh-addon.py public/downloads/vipermesh-addon.py
  • npx tsx scripts/test/test-blender-camera-aim-tool.ts
  • npx tsx scripts/test/test-camera-light-render-tool-registry.ts
  • npx tsx scripts/test/test-direct-tool-surface-coverage.ts
  • npx tsx scripts/test/test-tool-guide-trigger-coverage.ts
  • npx tsc --noEmit --incremental false
  • npm run lint (passes with existing baseline-browser-mapping freshness warning)

Summary by CodeRabbit

  • New Features

    • Added camera aiming capability, allowing cameras to point at target objects or world-space coordinates with optional depth-of-field focus adjustment and active camera selection.
  • Documentation

    • Updated camera guides with guidance on using the new aiming functionality and avoiding manual rotation methods.
  • Tests

    • Added comprehensive tests validating camera aiming behavior, tool integration, and documentation coverage.

@github-actions github-actions Bot added documentation Improvements or additions to documentation backend desktop scripts labels May 31, 2026
@coderabbitai
Copy link
Copy Markdown

coderabbitai Bot commented May 31, 2026

Review Change Stack

Warning

Review limit reached

@Ker102, we couldn't start this review because you've reached your PR review rate limit.

More reviews will be available in 43 minutes and 33 seconds. Learn how PR review limits work.

Your organization has run out of usage credits. Purchase more in the billing tab.

⌛ How to resolve this issue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

We recommend that you space out your commits to avoid hitting the rate limit.

🚦 How do rate limits work?

CodeRabbit enforces hourly rate limits for each developer per organization.

Our paid plans include higher PR review limits than trial, open-source, and free plans. In all cases, reviews become available again over time. During sustained high-volume PR review activity, CodeRabbit may temporarily slow when the next review becomes available.

Please see our Fair Usage Limits Policy for further information.

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: f9b53793-dbc9-4c22-ac6e-1ec4180fb040

📥 Commits

Reviewing files that changed from the base of the PR and between c61cf96 and 85522a3.

📒 Files selected for processing (6)
  • desktop/assets/vipermesh-addon.py
  • lib/ai/agents.ts
  • lib/orchestration/prompts/blender-agent-system.md
  • lib/orchestration/tool-registry.ts
  • public/downloads/vipermesh-addon.py
  • scripts/test/test-blender-camera-aim-tool.ts
📝 Walkthrough

Walkthrough

This PR introduces the aim_camera_at MCP tool, enabling the Blender agent to orient an existing camera toward either a target object or explicit world-space point. The implementation spans the Blender add-on command layer, TypeScript agent tooling, orchestration configuration, documentation, and test coverage.

Changes

Camera aiming MCP tool

Layer / File(s) Summary
Blender add-on command implementation
desktop/assets/vipermesh-addon.py, public/downloads/vipermesh-addon.py
Registers aim_camera_at in the MCP command dispatch table and implements the method to validate camera type, compute target coordinates from object bounding-box centroid or explicit location, apply rotation via _look_at, and optionally set DOF focus and active camera.
Agent tool wrapper and registration
lib/ai/agents.ts
Defines aimCameraAt tool wrapper with Zod schema requiring either target_name or target_location, routes through executeMcpCommand("aim_camera_at", ...), and adds to ALL_TOOLS for agent inclusion.
Tool orchestration: registry, filtering, and prompt guidance
lib/orchestration/tool-registry.ts, lib/orchestration/tool-filter.ts, lib/orchestration/prompts/blender-agent-system.md
Adds registry entry under lighting category, includes tool in camera filter group, documents in system prompt with full signature, and routes camera-aiming operations to the new tool.
Tool documentation and camera guide
data/tool-guides/camera-guide.md
Updates front-matter tags and triggered_by metadata, revises product-shot rotation guidance to use aim_camera_at, and updates common mistakes to warn against manual rotation_euler.
Test pipeline integration and validation
app/api/test-pipeline/route.ts, scripts/test/test-blender-camera-aim-tool.ts, scripts/test/test-camera-light-render-tool-registry.ts, scripts/test/test-tool-guide-trigger-coverage.ts
Adds tool to MCP_TOOLS allowlist, introduces end-to-end validation test for addon/agent/documentation consistency, and updates registry and guide coverage assertions.

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

  • Ker102/ViperMesh#50: Extends the same tool orchestration pipeline to add new Blender MCP tools (inspect_viewport_areas, focus_viewport_on_objects).
  • Ker102/ViperMesh#43: Modifies the shared MCP tool orchestration infrastructure to add camera-related tools (setup_studio_scene, validate_studio_scene).

Suggested labels

documentation, backend, desktop, scripts

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Description check ⚠️ Warning The pull request provides a clear summary and comprehensive validation steps, but does not follow the repository's template structure with required sections like 'Type of Change', 'Related Issues', etc. Restructure the description to match the template: add Type of Change, Related Issues, Motivation and Context, How Has This Been Tested checkboxes, and Checklist sections.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title 'Add direct camera aim tool' clearly and concisely describes the main feature added: a new camera aiming capability.
Docstring Coverage ✅ Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
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 unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feature/camera-aim-tool

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

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

Copy link
Copy Markdown

@coderabbitai coderabbitai Bot left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 5

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

Inline comments:
In `@lib/ai/agents.ts`:
- Line 1963: The description for the schema field set_dof_focus is ambiguous
about what happens when callers omit it; update the schema and/or description to
make the behavior explicit: either (A) make it a client-side default by changing
the Zod declaration for set_dof_focus to z.boolean().optional().default(true)
and update the description to "Defaults to true (client will set true when
omitted)", or (B) keep it optional but change the description to "Optional; when
omitted the Blender add-on treats it as true" to indicate a server-side default;
modify the set_dof_focus line in the schema in lib/ai/agents.ts accordingly and
ensure any consumers of this schema (e.g., code that reads set_dof_focus) are
consistent with the chosen default policy.

In `@lib/orchestration/prompts/blender-agent-system.md`:
- Line 119: Update the `aim_camera_at` signature description to explicitly state
the default for set_dof_focus to match the schema in lib/ai/agents.ts
(referenced at the comment on agents.ts:1963); locate the `aim_camera_at(name,
target_name?, target_location?, set_active?, set_dof_focus?)` line in
lib/orchestration/prompts/blender-agent-system.md and replace the ambiguous
"defaults true in Blender" phrasing with the exact default behavior used in the
schema (e.g., "defaults to true" or "defaults to false" as defined in the
schema) so documentation and the schema for aim_camera_at are consistent.

In `@lib/orchestration/tool-registry.ts`:
- Around line 385-386: The planner-facing parameters string in
lib/orchestration/tool-registry.ts currently marks both target_name and
target_location as optional but the tool contract requires at least one target
selector; update the "parameters" declaration (the parameters string) to state
that at least one of target_name or target_location is required (e.g., add “(at
least one of target_name or target_location required)”) and add a runtime
validation where the tool contract is constructed/validated (the code that reads
this parameters string in the tool registry) to throw or mark the tool invalid
when both are missing so prompt formatting and tool selection cannot produce or
call an invalid contract.

In `@public/downloads/vipermesh-addon.py`:
- Around line 5451-5456: Normalize the boolean-like inputs set_dof_focus and
set_active before applying camera side effects: add a small helper (e.g.,
normalize_bool) that treats string values like "false","0","no"
(case-insensitive) as False and "true","1","yes" as True, then call that helper
on set_dof_focus and set_active before the existing checks; use the normalized
booleans when deciding to toggle camera_obj.data.dof/use_dof, set
camera_obj.data.dof.focus_distance, and assign bpy.context.scene.camera =
camera_obj so stringy truthy values don't trigger side effects.

In `@scripts/test/test-blender-camera-aim-tool.ts`:
- Around line 18-19: The test's assertions are brittle because they require
exact variable names and operator syntax (target_obj.matrix_world @
mathutils.Vector and camera_obj.data.dof.focus_distance = focus_distance); relax
them by matching behaviorally relevant tokens instead: change the first
assertion to look for use of matrix_world together with mathutils.Vector (e.g.,
regex that allows any identifier before .matrix_world and the presence of
mathutils.Vector) and change the second to assert that some camera object's
.data.dof.focus_distance is set (e.g., match \.data\.dof\.focus_distance without
requiring camera_obj), or replace these with higher-level checks that the
exported/returned command updates DoF focus distance and computes a bounds
center value rather than exact variable names.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: b912eb19-9d40-4072-a666-f4df2e0b1139

📥 Commits

Reviewing files that changed from the base of the PR and between 78fb147 and c61cf96.

📒 Files selected for processing (11)
  • app/api/test-pipeline/route.ts
  • data/tool-guides/camera-guide.md
  • desktop/assets/vipermesh-addon.py
  • lib/ai/agents.ts
  • lib/orchestration/prompts/blender-agent-system.md
  • lib/orchestration/tool-filter.ts
  • lib/orchestration/tool-registry.ts
  • public/downloads/vipermesh-addon.py
  • scripts/test/test-blender-camera-aim-tool.ts
  • scripts/test/test-camera-light-render-tool-registry.ts
  • scripts/test/test-tool-guide-trigger-coverage.ts

Comment thread lib/ai/agents.ts Outdated
Comment thread lib/orchestration/prompts/blender-agent-system.md Outdated
Comment thread lib/orchestration/tool-registry.ts Outdated
Comment thread public/downloads/vipermesh-addon.py Outdated
Comment thread scripts/test/test-blender-camera-aim-tool.ts Outdated
@Ker102 Ker102 merged commit 6dfa5ff into main May 31, 2026
6 checks passed
@Ker102 Ker102 deleted the feature/camera-aim-tool branch May 31, 2026 14:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

backend desktop documentation Improvements or additions to documentation scripts

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant