[yuecideng]

Description

cuRobo waypoint planning constrains endpoint poses but can still drift sideways or rotate during a grasp approach. Add opt-in CuroboPlanOptions.path_constraints with a CuroboLinearConstraintCfg for each selected full-pose Cartesian segment. Native line/orientation costs and feasibility checks guide the solve; bounded FK batches then validate the actual TCP, including tool offsets. Failed environments retain the normal start-hold result, and cached native criteria are restored after each constrained segment, including exceptions.

The defaults remain unchanged. Constrained requests preserve native samples and support target-TCP or planning-base directions. The implementation also covers CPU physics with CUDA planning. These are whole-segment, sampled constraints; monotonic progress, continuous validity between samples, and the V1 time-activated single-optimization approach remain outside this change.

Include a runnable 45 cm side-approach example with a physical alignment frame. Both variants use identical initial joints, target, collision world, sampling resets, and limits. The example independently scores TCP geometry, checks native sampled world collisions, and renders synchronized overview/overhead videos through EmbodiChain Hybrid. A separate benchmark records synchronized planning latency, memory accounting, and quality metrics. The guide explains the geometry, coordinate transforms, tolerance semantics, state lifecycle, and reproduction commands.

Dependencies: the existing optional cuRobo V2-Fast 0.9+ / CUDA runtime. FFmpeg is needed for example video export, and Matplotlib for benchmark plots. No dependency metadata changes.

Refs #571. This PR does not close the issue's remaining late-activated, blended-approach objective.

Type of change

• Enhancement (non-breaking improvement to the existing motion-planning backend)
• Documentation update

Example

The runnable example generates its images and recordings locally; no image or video files are included in this PR. Both paths pass native sampled world-collision validation; self-collision retains the existing backend limitation. This demonstrates planned approach geometry, not physical insertion success.

Fixed illustrative case	Unconstrained	Line-constrained
Maximum sampled perpendicular TCP error	71.50 mm	4.34 mm
Maximum sampled target-orientation error	9.32 degrees	2.64 degrees
Trajectory duration	0.618 s	0.658 s

Reproduce from the repository root in the CUDA/cuRobo environment:

python examples/sim/motion/planners/curobo_approach_showcase.py
python examples/sim/motion/planners/curobo_approach_showcase.py --plan-only
python -m scripts.benchmark.motion_generation.curobo_grasp_approach --warmup 2 --repeats 5

Validation

• Black 26.10.1: python -m black .; clean formatting and git diff --check.
• 283 focused CPU tests passed across the cuRobo adapter, query snapshots, and scalar/batched MotionGenerator contracts.
• 4 live CUDA integration cases passed: singleton/batched paths, goal/base directions, CUDA Graphs, CPU-physics/CUDA-planning interoperability, mixed failed-row holds, and subsequent unconstrained requests.
• 53 agent-context and API-documentation tooling tests passed; public API coverage is 4915/4915.
• Re-ran the full showcase in an isolated checkout: both native solves and collision checks passed, constrained sampled and interpolated-display TCP deviations remained below 5 mm, and the native recording decoded successfully.
• Strict scoped Sphinx HTML build passed for the changed guide, including math, Mermaid, and Python examples. The full Sphinx dummy build completed with 874 broader documentation warnings; none mention the new guide, configuration, or examples.

Coverage review: the focused additions cover undefined geometry, unsupported target semantics/resampling, rotated and translated TCP frames, intermediate position/rotation excursions including small-angle precision, native state restoration/cache updates, batched partial failure, and device conversion. Existing facade/query-snapshot coverage is reused. The example is validated through its CLI and real planning/rendering rather than tutorial-specific unit tests.

Context review: updated the motion-planning integration contract. Simulation-system guidance remains accurate because physics, rendering, and execution ownership are unchanged.

Checklist

• I have run the black . command to format the code base.
• I reviewed affected documentation and agent context, updated it where needed, or explained why no update was needed.
• Public API changes are reflected in the API docs (python docs/scripts/check_api_docs.py).
• I verified appropriate behavioral coverage and reviewed the necessity of added or extended tests.
• Dependencies have been reviewed; no dependency metadata changes are required.