feat: visualize manipulation obstacles

[TomCC7]

Contribution path

• Linked issue or discussion: none (OpenSpec change: visualize-manipulation-obstacles)

Problem

Planner-world obstacles were not visible in the external Viser visualization. Existing obstacle identity also leaked from Obstacle.name instead of being owned by the planning world.

Solution

• Add a generic visualization obstacle lifecycle to VisualizationSpec; Viser renders it and native Meshcat implements no-ops because it already synchronizes internally.
• Coordinate accepted add/remove/clear mutations through WorldMonitor, including initialization during world finalization before startup obstacles are added.
• Make WorldSpec.add_obstacle() return the native world-owned obstacle ID or None when insertion is not accepted.
• Render planner-parity geometry in Viser with a local visibility toggle and mesh-failure proxy.

How to Test

Automated:

uv run pytest dimos/manipulation/planning/monitor/test_world_monitor.py dimos/manipulation/visualization/viser/test_viser_visualization.py dimos/manipulation/test_roboplan_world.py dimos/manipulation/visualization/test_factory.py

Manual Viser check:

1. Start a manipulation blueprint configured with ViserVisualizationConfig in the foreground, then open http://127.0.0.1:8095.
2. In another terminal, run uv run python -i -m dimos.manipulation.planning.examples.manipulation_client.
3. In the REPL, run obstacle_id = add_box("manual-box", 0.5, 0, 0.2); verify it appears in Viser, then run remove(obstacle_id) and verify it disappears. Toggle Scene → manipulation.obstacles to verify layer visibility.

AI assistance

OpenAI Codex with gpt-5.6-terra; used extensively for implementation, testing, and review coordination.

Checklist

• I have read and approved the CLA.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟢 Ready	View Preview	Jul 21, 2026, 6:07 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dimensional	🟡 Building	–	Jul 21, 2026, 6:06 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

[codecov]

Codecov Report

❌ Patch coverage is 53.33333% with 140 lines in your changes missing coverage. Please review.
✅ All tests successful. No failed tests found.

Files with missing lines	Patch %	Lines
dimos/manipulation/visualization/viser/scene.py	46.40%	61 Missing and 6 partials ⚠️
...ulation/planning/monitor/world_obstacle_monitor.py	4.34%	22 Missing ⚠️
...mos/manipulation/planning/monitor/world_monitor.py	51.51%	14 Missing and 2 partials ⚠️
...mos/manipulation/visualization/viser/visualizer.py	16.66%	15 Missing ⚠️
dimos/manipulation/visualization/test_factory.py	84.74%	9 Missing ⚠️
dimos/manipulation/planning/world/drake_world.py	36.36%	6 Missing and 1 partial ⚠️
...anipulation/planning/monitor/test_world_monitor.py	90.00%	2 Missing ⚠️
...imos/manipulation/planning/world/roboplan_world.py	50.00%	1 Missing and 1 partial ⚠️

@@            Coverage Diff             @@
##             main    #3108      +/-   ##
==========================================
+ Coverage   73.37%   73.59%   +0.22%     
==========================================
  Files        1071     1068       -3     
  Lines      100406    99680     -726     
  Branches     9136     9863     +727     
==========================================
- Hits        73672    73363     -309     
+ Misses      24279    23712     -567     
- Partials     2455     2605     +150     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	66.95% <59.23%> (-0.01%)	⬇️
OS-ubuntu-latest	68.95% <51.33%> (-0.05%)	⬇️
Py-3.10	68.94% <51.33%> (-0.05%)	⬇️
Py-3.11	68.95% <51.33%> (-0.04%)	⬇️
Py-3.12	68.94% <51.33%> (-0.05%)	⬇️
Py-3.13	68.93% <51.33%> (-0.06%)	⬇️
Py-3.14	68.94% <51.33%> (-0.05%)	⬇️
Py-3.14t	68.94% <51.33%> (-0.06%)	⬇️
SelfHosted-Large	29.66% <19.93%> (-0.59%)	⬇️
SelfHosted-Linux	36.55% <22.97%> (-0.05%)	⬇️
SelfHosted-macOS	35.48% <22.97%> (-0.08%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
dimos/manipulation/manipulation_module.py	55.46% <100.00%> (-7.57%)	⬇️
dimos/manipulation/planning/spec/protocols.py	100.00% <100.00%> (ø)
dimos/manipulation/test_roboplan_world.py	97.79% <100.00%> (+<0.01%)	⬆️
...anipulation/planning/monitor/test_world_monitor.py	90.84% <90.00%> (+0.63%)	⬆️
...imos/manipulation/planning/world/roboplan_world.py	78.68% <50.00%> (+0.09%)	⬆️
dimos/manipulation/planning/world/drake_world.py	47.77% <36.36%> (-0.19%)	⬇️
dimos/manipulation/visualization/test_factory.py	77.58% <84.74%> (+2.99%)	⬆️
...mos/manipulation/visualization/viser/visualizer.py	67.82% <16.66%> (-9.36%)	⬇️
...mos/manipulation/planning/monitor/world_monitor.py	62.37% <51.51%> (-9.36%)	⬇️
...ulation/planning/monitor/world_obstacle_monitor.py	13.24% <4.34%> (-0.32%)	⬇️
... and 1 more

... and 28 files with indirect coverage changes

🚀 New features to boost your workflow:

• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[greptile-apps]

Greptile Summary

This PR adds planner obstacle rendering to the external Viser visualization. The main changes are:

• Adds obstacle add, remove, and clear methods to the visualization interface.
• Routes accepted world mutations through WorldMonitor.
• Returns world-owned obstacle IDs from the planning backends.
• Renders Viser obstacle geometry with visibility controls and fallback proxies.
• Initializes visualization before startup obstacles are added.

Confidence Score: 5/5

This looks safe to merge.

• No blocking issues were found in the updated code.

Important Files Changed

Filename	Overview
dimos/manipulation/planning/monitor/world_monitor.py	Coordinates accepted obstacle mutations with visualization and initializes the visualization during world finalization.
dimos/manipulation/planning/monitor/world_obstacle_monitor.py	Routes monitored obstacle changes through the shared world and visualization lifecycle.
dimos/manipulation/visualization/viser/scene.py	Adds obstacle geometry, visibility controls, fallback proxies, and cleanup to the Viser scene.
dimos/manipulation/visualization/viser/visualizer.py	Forwards obstacle lifecycle operations to the active Viser scene.

_{Reviews (2): Last reviewed commit: "[autofix.ci] apply automated fixes" | Re-trigger Greptile}

[greptile-apps]

Optional Backend Import Can Fail

When an installed viser version does not export SceneNodeHandle at its package root, this import raises ImportError. The nearby handler only catches ModuleNotFoundError, so selecting the Viser backend can fail while loading the module instead of reporting an unavailable or incompatible optional backend.