feat(manipulation): add roboplan Cartesian planning

[TomCC7]

Contribution path

• Small, safe change that does not need a tracking issue
• Linked issue or discussion: DIM-1137 — Cartesian Planning from pre grasp to grasp

Problem

The manipulation planner contract can only request collision-free joint-space
paths. It cannot express a straight tool-center-point motion for approaches,
retreats, or interactive Cartesian moves, even though RoboPlan provides an
official Cartesian path planner.

The Viser manipulation panel also resolves its Cartesian gizmos to joint goals
and invokes free-space planning, so there is no convenient way to exercise or
preview a linear TCP path.

Solution

• Add a backend-neutral internal plan_linear_cartesian_path planner operation
  with absolute world-frame poses, relative Cartesian deltas, and the existing
  target-plus-auxiliary-group convention.
• Implement the operation using RoboPlan's official bounded-speed Cartesian
  planner, including synchronized multi-group timing and full-model start-state
  handling.
• Return combined globally named joint states with RoboPlan timestamps and
  velocities, and atomically post-validate waypoints and interpolated edges
  against the DimOS collision world.
• Return UNSUPPORTED from planner backends without linear Cartesian support;
  never substitute a free-space path for a failed linear request.
• Add typed RoboPlan Cartesian-planner configuration while retaining the legacy
  planner-name compatibility path.
• Add a Viser Planning mode selector with Free-space as the default and
  Linear Cartesian for absolute transform-control targets. Existing preview
  and synchronized execution reuse the planner-supplied trajectory directly.

The public RPC, skill, MCP, and CLI motion APIs remain unchanged.

How to Test

Run the interactive feature:

uv run dimos run xarm7-planner-coordinator -o manipulationmodule.visualization.backend=viser

Move the TCP gizmo, choose Linear Cartesian, click Plan, and then
Preview.

Automated validation performed:

uv run pytest dimos/manipulation -m 'not (self_hosted or mujoco or self_hosted_large)'
uv run pytest -m self_hosted dimos/manipulation/test_roboplan_world_integration.py
uv run mypy dimos/manipulation

Results: 360 manipulation tests passed, 2 real-RoboPlan integration tests
passed, and mypy passed across all manipulation source files.

AI assistance

OpenAI Codex with GPT-5 was extensively involved in API exploration,
implementation, tests, documentation, and validation. The design decisions and
scope were reviewed collaboratively with the author.

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 28, 2026, 5:21 AM

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

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
...imos/manipulation/planning/world/roboplan_world.py	78.97%	19 Missing and 18 partials ⚠️
dimos/manipulation/manipulation_module.py	74.35%	12 Missing and 8 partials ⚠️
dimos/manipulation/visualization/viser/gui.py	73.17%	7 Missing and 4 partials ⚠️
dimos/manipulation/planning/factory.py	63.63%	2 Missing and 2 partials ⚠️
...os/manipulation/test_roboplan_world_integration.py	94.28%	2 Missing and 2 partials ⚠️
dimos/manipulation/visualization/operator.py	84.61%	1 Missing and 1 partial ⚠️

@@            Coverage Diff             @@
##             main    #3240      +/-   ##
==========================================
+ Coverage   75.21%   75.31%   +0.10%     
==========================================
  Files        1128     1131       +3     
  Lines      107983   108661     +678     
  Branches     9751     9908     +157     
==========================================
+ Hits        81220    81842     +622     
- Misses      23951    23983      +32     
- Partials     2812     2836      +24     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	68.89% <73.80%> (+0.02%)	⬆️
OS-ubuntu-latest	71.00% <80.87%> (+0.06%)	⬆️
Py-3.10	71.00% <80.87%> (+0.07%)	⬆️
Py-3.11	70.99% <80.87%> (+0.06%)	⬆️
Py-3.12	70.99% <80.87%> (+0.06%)	⬆️
Py-3.13	70.99% <80.87%> (+0.06%)	⬆️
Py-3.14	71.00% <80.87%> (+0.06%)	⬆️
Py-3.14t	70.99% <80.87%> (+0.06%)	⬆️
SelfHosted-Large	29.01% <21.99%> (-0.08%)	⬇️
SelfHosted-Linux	35.87% <42.34%> (+0.21%)	⬆️
SelfHosted-macOS	34.95% <42.34%> (+0.23%)	⬆️

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

Files with missing lines	Coverage Δ
dimos/manipulation/planning/planners/config.py	100.00% <100.00%> (ø)
...imos/manipulation/planning/planners/rrt_planner.py	35.82% <100.00%> (+1.30%)	⬆️
...imos/manipulation/planning/planners/test_config.py	100.00% <100.00%> (ø)
...on/planning/planners/test_rrt_planner_selection.py	100.00% <100.00%> (ø)
dimos/manipulation/planning/spec/models.py	100.00% <100.00%> (ø)
dimos/manipulation/planning/spec/protocols.py	100.00% <100.00%> (ø)
...anipulation/test_generated_plan_materialization.py	100.00% <100.00%> (ø)
dimos/manipulation/test_manipulation_module.py	100.00% <100.00%> (ø)
dimos/manipulation/test_manipulation_unit.py	100.00% <ø> (ø)
dimos/manipulation/test_planning_factory.py	98.03% <100.00%> (+0.12%)	⬆️
... and 10 more

... and 4 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.

[mintlify]

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

Project	Status	Preview	Updated (UTC)
dimensional	🟡 Building	–	Jul 28, 2026, 5:20 AM

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

[sea-bass]

FYI we just did a big overhaul of the Cartesian planner in roboplan, based on some testing we did for a demo. It also changes some of the options slightly, so it will be a breaking change.

This is not yet on PyPi, but will be available in the upcoming 0.6.0 release. Or you can try building a wheel from the latest version for now.

Ref: open-planning/roboplan#277

[TomCC7]

FYI we just did a big overhaul of the Cartesian planner in roboplan, based on some testing we did for a demo. It also changes some of the options slightly, so it will be a breaking change.

This is not yet on PyPi, but will be available in the upcoming 0.6.0 release. Or you can try building a wheel from the latest version for now.

Ref: open-planning/roboplan#277

Thanks for your attention on our project! We'll just migrate after the new version is officially released, and looking forward to all the new updates from there :)