Walkthrough

Extended the MCP server with orthographic diagnostic rendering capabilities and object grounding verification tools. The get_viewport_screenshot method now accepts parameters to render diagnostic orthographics of specific objects, while a new verify_object_grounded method validates object placement against ground surfaces using BVH raycasting.

Changes

Sequence Diagram(s)

sequenceDiagram
    actor Client
    participant Server as Blender MCP Server
    participant Addon as addon.py
    participant Blender as Blender Engine

    rect rgb(0, 100, 200, 0.5)
    Note over Client,Addon: Orthographic Diagnostic Rendering Flow
    Client->>Server: get_viewport_screenshot(target_object="Cube", view="front")
    Server->>Addon: send_command("get_viewport_screenshot", target_object="Cube", ...)
    Addon->>Blender: Locate object in scene
    Addon->>Blender: Compute evaluated bounding box (world space)
    Addon->>Blender: Create temporary orthographic camera
    Addon->>Blender: Render with write_still to filepath
    Addon->>Blender: Remove temporary camera/data
    Addon->>Server: Return {filepath, dimensions, target, view}
    Server->>Client: Screenshot metadata + image path
    end

    rect rgb(100, 0, 100, 0.5)
    Note over Client,Addon: Object Grounding Verification Flow
    Client->>Server: verify_object_grounded(object_name="Box", ground_name="Floor")
    Server->>Addon: send_command("verify_object_grounded", object_name="Box", ...)
    Addon->>Blender: Locate both objects, validate are meshes
    Addon->>Blender: Build BVH from ground object geometry
    Addon->>Blender: Sample object vertices from lower Z slice
    Addon->>Blender: Raycast downward to ground surface
    Addon->>Blender: Aggregate gap statistics (min/max/median/mean)
    Addon->>Server: Return {gap_stats, hit_count, miss_count, hint}
    Server->>Client: Grounding verification result
    end

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• feat: add tool to get screenshot of viewport #123: Extends the same get_viewport_screenshot tool with orthographic diagnostic rendering and adds new grounding verification functionality via modified signatures and new MCP command handlers.

Suggested labels

Review effort 2/5

Poem

🐰 Whiskers twitch with diagnostic glee,
Objects rendered orthographically!
Raycasts dance 'cross ground so true,
Verifying placement through and through.
Blender's vision, crystal clear,
Grounded objects, never to fear! ✨

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

• X
• Mastodon
• Reddit
• LinkedIn

• Add verify_object_grounded() tool to measure vertical gaps between object bases and ground
  meshes using raycasting
• Extend get_viewport_screenshot() with orthographic diagnostic rendering for specific objects
  from six named view angles
• Both tools use evaluated geometry to honor Displace modifiers, shape keys, and armature
  deformations
• Provide deterministic visual verification without relying on position math that fails after
  asymmetric mesh edits

Add grounding verification and ortho diagnostic rendering

• Register verify_object_grounded handler in command dispatcher
• Extend get_viewport_screenshot() signature with target_object, view, distance_factor,
 ortho_padding parameters
• Add _render_ortho_diag() method to create temporary orthographic camera, render from six named
 axes, and restore render state
• Implement verify_object_grounded() method using BVHTree raycasting to measure vertical gaps with
 statistical analysis

addon.py

Expose visual-verification tools via MCP interface

• Extend get_viewport_screenshot() MCP tool signature with optional target object and view
 parameters
• Pass new parameters to Blender addon when target_object is provided
• Add new verify_object_grounded() MCP tool that wraps the Blender addon method
• Update docstrings to document orthographic diagnostic rendering and grounding verification
 workflows

src/blender_mcp/server.py

Description

verify_object_grounded() can crash with ZeroDivisionError when max_samples=0 and often exceeds the
intended max_samples cap due to using floor-division for the downsample step. This can lead to hard
failures or unexpectedly large numbers of raycasts (slow tool runs).

Code

addon.py[R576-578]

+        if len(slice_verts) > max_samples:
+            step = max(1, len(slice_verts) // max_samples)
+            slice_verts = slice_verts[::step]

Evidence

The downsampling logic divides by max_samples without validating it, and uses floor division so
counts between (max_samples, 2*max_samples) produce step=1 (no downsampling), violating the
documented ‘cap on raycasts’.

addon.py[576-578]
src/blender_mcp/server.py[388-392]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`verify_object_grounded()` intends `max_samples` to cap raycasts, but:
- `max_samples=0` causes `ZeroDivisionError`.
- The current step calculation uses floor division, so it frequently fails to downsample when `len(slice_verts)` is only slightly larger than `max_samples`.

### Issue Context
This tool may be called with arbitrary parameters via MCP, so it must be robust to edge cases and must reliably respect the `max_samples` contract.

### Fix Focus Areas
- addon.py[576-578]

### Implementation notes
- Validate inputs early (e.g., `if max_samples <= 0: return {"error": "max_samples must be > 0"}`; similarly consider `slice_height > 0`).
- Compute a downsample step using ceiling division so the resulting list length is guaranteed to be `<= max_samples`, e.g.:
 - `step = math.ceil(len(slice_verts) / max_samples)`
 - then `slice_verts = slice_verts[::step]`
- Optionally, if exact `<= max_samples` is required even after slicing, truncate (`slice_verts = slice_verts[:max_samples]`).

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

verify_object_grounded() builds a full world-space list of all object vertices before
filtering/downsampling, which can be extremely expensive for high-poly meshes even when max_samples
is small. This can freeze Blender during tool execution.

Code

addon.py[R569-575]

+        obj_mw = obj_eval.matrix_world
+        world_verts = [obj_mw @ v.co for v in obj_eval.data.vertices]
+        if not world_verts:
+            return {"error": f"Object '{object_name}' has no vertices"}
+
+        zmin = min(v.z for v in world_verts)
+        slice_verts = [v for v in world_verts if v.z <= zmin + slice_height]

Evidence

The code materializes world_verts for every vertex (obj_eval.data.vertices) and only later
reduces to a slice and applies max_samples, so large meshes pay the full transform+allocation cost
regardless of max_samples.

addon.py[569-575]
addon.py[576-579]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
`verify_object_grounded()` currently computes world-space coordinates for *all* vertices up front (`world_verts = [...]`). For dense meshes this can consume significant time/memory and negate the value of `max_samples`.

### Issue Context
The function ultimately needs only vertices within a bottom z-slice and then only up to `max_samples` raycasts.

### Fix Focus Areas
- addon.py[569-579]

### Implementation notes
Consider restructuring to avoid a full list allocation, for example:
1) First pass: compute `zmin` without storing all vertices (iterate vertices and track minimum transformed z).
2) Second pass: collect slice vertices, but cap memory by either:
  - reservoir sampling up to `max_samples`, or
  - collecting then applying a corrected downsample step + truncate.
3) Keep the current output fields the same.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Description

verify_object_grounded() raycasts from z=v.z+1000, which can start below the ground surface for
deeply buried objects or large-scale scenes, causing widespread misses and a misleading 'No ground
samples hit' error. This breaks grounding checks in valid scene configurations.

Code

addon.py[R582-589]

+        for v in slice_verts:
+            origin = mathutils.Vector((v.x, v.y, v.z + 1000.0))
+            direction = mathutils.Vector((0, 0, -1))
+            hit_loc, hit_normal, hit_idx, hit_dist = bvh.ray_cast(origin, direction)
+            if hit_loc is None:
+                missed += 1
+                continue
+            gaps.append(v.z - hit_loc.z)

Evidence

Ray origins are computed using a constant +1000 offset independent of the ground’s world-space
height/bounds. If the ground surface is higher than v.z + 1000, rays originate under the ground
and will not intersect it when cast downward.

addon.py[582-589]
addon.py[591-596]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

### Issue description
Raycasts start from `v.z + 1000.0` regardless of scene scale or ground height. In cases where the ground surface is above that origin (e.g., object is buried by >1000 units), raycasts miss and the tool returns an incorrect failure.

### Issue Context
The tool already has access to `ground_eval` and can compute a safe world-space z to start from.

### Fix Focus Areas
- addon.py[564-567]
- addon.py[582-589]

### Implementation notes
- Compute a ray start height based on the ground’s evaluated world-space bounding box, e.g. compute `ground_zmax_world` from `ground_eval.bound_box` transformed by `ground_eval.matrix_world`.
- Use `origin = Vector((v.x, v.y, ground_zmax_world + margin))` (margin like 1.0m or `slice_height + 1.0`) and keep direction `(0,0,-1)`.
- Keep the existing miss/error reporting, but it should now represent true misses (outside bounds / empty ground), not ray-origin artifacts.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools