RoboPlan upstream integration: example_ssik_to_plan.py (followup to #310/#316/#317)

[siddhss5]

Context

The interactive demo shipped via #316/#317 was originally conceived (#310) as the ssik half of a joint integration with open-planning/roboplan — Sebastian Castro's motion planning library. ssik provides analytical IK; RoboPlan provides motion planning + trajectory animation. The upstream half is still owed.

This issue captures the design + environment work needed to ship the RoboPlan-side PR, deferred so we can prioritize coverage gaps / outreach first.

What to ship upstream

A new file roboplan_examples/python/example_ssik_to_plan.py in open-planning/roboplan, modeled on their existing example_ik.py (interactive marker scaffold) and example_rrt.py (RRT planning + animation).

Architecture

1. Same Pinocchio + ViserVisualizer + xacro/URDF stack as their other examples — load UR5 via common.get_model_data("ur5").
2. Replace SimpleIk with a thin wrapper around ssik.prebuilt.ur5_ik.solve(T, max_solutions=8, q_seed=q_current) — returns all 8 analytical branches at machine precision.
3. Render every branch (active + 7 ghosts) on the marker the same way ssik's own demo does (examples/05_viser_interactive_ik.py) — gives RoboPlan users a free visual upgrade.
4. The differentiator: pick the closest-to-current branch as the goal, run RRT to plan a collision-free path from q_current to it, then animate the trajectory using their existing TOPP-RA + visualizeJointTrajectory utilities. "ssik to plan", not just "ssik IK".
5. cycle button: switch goal branch → re-plan → re-animate. Surfaces the "different branches give different motion plans" story that's invisible with numerical IK.

Concrete API skeleton

import numpy as np
import pinocchio as pin
from common import get_model_data
from roboplan.core import Scene, JointConfiguration
from roboplan.rrt import RRT, RRTOptions
from ssik.prebuilt import ur5_ik

def solve_ssik(T_world_target, q_seed, q_indices):
    \"\"\"Wrap ssik.prebuilt.ur5_ik to RoboPlan's q_indices convention.\"\"\"
    sols = ur5_ik.solve(T_world_target, max_solutions=8, q_seed=q_seed)
    return [s.q for s in sols]

# (full marker-driven scaffold from example_ik.py, but solveIk() routes
# through solve_ssik() and falls through to RRT planning before display)

Environment requirements

This is what blocked the first attempt and needs to be sorted before the PR:

• RoboPlan's pixi.toml only declares platforms = [\"linux-64\", \"linux-aarch64\"]. macOS is unsupported, so testing on a Mac dev box requires either:
  • Docker Desktop + their docker-compose.yaml (uses NVIDIA + X11 forwarding — painful to set up cleanly on Mac).
  • A GitHub Codespace on the repo (browser-based Linux, runs out of the box).
  • A real Linux box (lab machine / EC2).
• ssik is pure Python at the [demo] extra surface so importing it into their pixi env should be pip install ssik (or pip install ssik[demo] if we want viser-side ghost rendering). Worth confirming their pixi env tolerates pip install of pure-Python wheels.

Joint-index mapping (verify before coding)

ssik's UR5 prebuilt (#313 manifest, built from robot_descriptions / ur5_description) and RoboPlan's UR5 (loaded via common.get_model_data(\"ur5\")) should match at the URDF level, but the q_indices mapping into Pinocchio's full joint vector is what solveIk has to round-trip through. Cheap pre-check: load both, compare actuated_joint_names, expect identity.

ssik-side API gaps this might surface

• The wrapper needs to translate from RoboPlan's q_seed (RoboPlan's joint-group convention) to ssik's q (URDF actuated order). Probably a 1:1 identity but worth confirming.
• ssik's solve returns Solution objects with q, fk_residual, etc.; RoboPlan likely expects raw np.ndarray. Trivial shim, but flagging.
• If RoboPlan wants ssik to be a hard dep of the example, it needs to land in their pixi.toml or be pip installed at example-runtime.

Why it matters

• Concrete cross-library integration validates ssik as the IK layer in a real motion-planning stack.
• Followup beat for the v1.3 / demo outreach arc — the LinkedIn post can chain into "now imagine planning on top."
• Sebastian Castro expressed interest in this pattern after the v1.2.4 outreach; opening as a Draft PR is the polite next step rather than a cold submission.

Effort estimate

• Env setup (Linux box / Codespaces / Docker): 30 min – 2 hours depending on path.
• Code: 2-3 hours of careful translation from their existing patterns + ssik wrapper.
• Local end-to-end test: 1 hour.
• Draft PR + Sebastian coordination: open-ended.

Total: ~half-day to a day of focused work.

When to pick this up

After the higher-priority piles (coverage gaps, #314 vendored-mesh package, speed work) have been triaged or when the outreach calendar specifically needs a "composability" beat.