feat(manipulation): add trajectory parametrization

[TomCC7]

Closes DIM-1093

Contribution path

• Linked issue or discussion: DIM-1093

Problem

Manipulation planners return either an untimed geometric path or a planner-native timed trajectory. ManipulationModule previously owned a simple per-robot trapezoid generator and mixed path conversion, validation, plan storage, and execution concerns. The stack had no startup-selectable trajectory-parametrization boundary, no RoboPlan TOPP-RA integration, and no GUI control for reducing the speed of future plans.

Solution

• Add TrajectoryParametrizerSpec beside PlannerSpec and WorldSpec. Its implementations convert paths, validate canonical trajectory structure, and construct GeneratedPlan.
• Select exactly one parametrization backend at startup. When configuration is omitted, RoboPlanWorld selects roboplan_toppra and DrakeWorld selects simple_trapezoid; explicit configuration overrides the world default. A backend failure rejects the plan—there is no fallback.
• Preserve planner-native timestamps and velocities. Timed planner results skip path parametrization but pass through the same structural validation before becoming a GeneratedPlan.
• Remove the module-local trajectory generator and naive materialization logic. Preview and execution consume the accepted stored trajectory without regenerating or retiming it.
• Pin roboplan==0.5.1. RoboPlan model composition preserves authored acceleration limits and temporarily supplies a global 2.0 rad/s² limit where acceleration is absent. A TODO tracks removing this fallback when formal per-joint DimOS limit overrides are available.
• Add Viser's Next plan speed slider. It changes subsequent plans while leaving an accepted plan and active execution unchanged.
• Document backend selection, timed-result bypass, limit handling, and custom-arm configuration.

How to Test

Test the RoboPlan world and its default TOPP-RA backend on the stock xArm model:

dimos run xarm7-planner-coordinator \
  -o manipulationmodule.world_backend=roboplan \
  -o manipulationmodule.visualization.backend=viser

Test compatibility timing by selecting the simple backend explicitly:

dimos run xarm7-planner-coordinator \
  -o manipulationmodule.trajectory_parametrization.backend=simple_trapezoid \
  -o manipulationmodule.visualization.backend=viser

Selecting roboplan_toppra explicitly is equivalent to omitting trajectory-parametrization configuration with world_backend=roboplan.

In Viser, plan and preview a multi-waypoint motion, change Next plan speed, then plan again. The new plan should slow down; the previously accepted plan should remain unchanged.

Automated validation completed:

• uv run pytest dimos/manipulation -m 'not (self_hosted or mujoco or self_hosted_large)' — 408 passed, 19 deselected
• RoboPlan 0.5.1 contract and adapter tests — 5 passed
• Stock xArm7 RoboPlan scene verification — finite ±2.0 rad/s² acceleration bounds
• Ruff check and format
• Strict mypy for dimos/manipulation
• Pre-commit checks for changed files
• uv lock --check
• git diff --check

Hardware/manual QA completed:

• Plan, preview, and execute a multi-waypoint path with simple_trapezoid.
• Repeat with RoboPlanWorld and roboplan_toppra.
• Verify startup or pre-motion failures for an incompatible world and TOPP-RA generation failure.

AI assistance

OpenAI Codex with GPT-5 was used extensively for design exploration, implementation, tests, documentation, conflict resolution, and review.

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 30, 2026, 6:11 AM

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

[codecov]

Codecov Report

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

Files with missing lines	Patch %	Lines
...tion/planning/trajectory_generator/parametrizer.py	78.57%	9 Missing and 9 partials ⚠️
dimos/manipulation/visualization/viser/gui.py	53.57%	9 Missing and 4 partials ⚠️
dimos/manipulation/manipulation_module.py	80.00%	8 Missing and 1 partial ⚠️
dimos/manipulation/planning/factory.py	57.14%	6 Missing and 3 partials ⚠️
...anning/trajectory_generator/simple_parametrizer.py	82.97%	4 Missing and 4 partials ⚠️
dimos/manipulation/pick_and_place_module.py	0.00%	2 Missing ⚠️
...imos/manipulation/planning/world/roboplan_world.py	50.00%	2 Missing ⚠️
dimos/manipulation/visualization/operator.py	50.00%	2 Missing ⚠️

@@            Coverage Diff             @@
##             main    #3287      +/-   ##
==========================================
+ Coverage   74.86%   74.95%   +0.08%     
==========================================
  Files        1137     1144       +7     
  Lines      109071   109571     +500     
  Branches     9838     9868      +30     
==========================================
+ Hits        81661    82131     +470     
- Misses      24618    24639      +21     
- Partials     2792     2801       +9     

Flag	Coverage Δ
OS-ubuntu-24.04-arm	68.64% <66.61%> (-0.05%)	⬇️
OS-ubuntu-latest	70.77% <71.58%> (-0.03%)	⬇️
Py-3.10	70.77% <71.58%> (-0.03%)	⬇️
Py-3.11	70.76% <71.58%> (-0.03%)	⬇️
Py-3.12	70.77% <71.58%> (-0.03%)	⬇️
Py-3.13	70.76% <71.58%> (-0.03%)	⬇️
Py-3.14	70.77% <71.58%> (-0.03%)	⬇️
Py-3.14t	70.77% <71.58%> (-0.03%)	⬇️
SelfHosted-Large	29.08% <30.54%> (+0.04%)	⬆️
SelfHosted-Linux	36.05% <58.99%> (+0.15%)	⬆️

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

Files with missing lines	Coverage Δ
dimos/control/test_control.py	95.90% <100.00%> (+<0.01%)	⬆️
...anipulation/planning/monitor/test_world_monitor.py	93.95% <100.00%> (+0.03%)	⬆️
dimos/manipulation/planning/spec/protocols.py	100.00% <100.00%> (ø)
...nipulation/planning/trajectory_generator/config.py	100.00% <100.00%> (ø)
...ajectory_generator/roboplan_toppra_parametrizer.py	100.00% <100.00%> (ø)
...planning/trajectory_generator/test_parametrizer.py	100.00% <100.00%> (ø)
...ory_generator/test_roboplan_toppra_parametrizer.py	100.00% <100.00%> (ø)
...g/trajectory_generator/test_simple_parametrizer.py	100.00% <100.00%> (ø)
...imos/manipulation/planning/world/roboplan_model.py	87.30% <100.00%> (+0.45%)	⬆️
...anipulation/test_generated_plan_materialization.py	100.00% <100.00%> (ø)
... and 14 more

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