Add planner selection to atomic-action tutorials

[yuecideng]

Description

Add a shared motion-planner selector to the runnable atomic-action tutorials.
The new --planner option supports toppra, trapezoidal, and curobo, while
intentionally leaving NeuralPlanner out of the tutorial selector because it
requires model-specific ONNX configuration. trapezoidal is now the default
for ordinary atomic-action tutorials; the live collision-world recovery demo
retains its cuRobo-only default.

The change also makes planner-owned trapezoidal samples safe to consume in
composite atomic-action phases, adds CPU/Torch trajectory-resampling fallback
and focused coverage, and documents planner behavior, examples, and known
tutorial-specific constraints in the atomic-action and motion-generation
guides.

All atomic-action tutorials now use the same shared scene lighting: one global
downward sun light (main_light) for the simulation. Vectorized arenas no
longer create separate per-arena point lights, and the dual-arm examples no
longer need tutorial-specific light positions.

Issue reference: none provided.

Dependencies: no new dependencies. cuRobo remains optional and is only used
when selected (and requires its existing CUDA/runtime setup).

Type of change

• Bug fix (non-breaking change which fixes an issue)
• Enhancement (non-breaking change which improves an existing functionality)
• New feature (non-breaking change which adds functionality)
• Breaking change (existing functionality will not work without user modification)
• Documentation update

Screenshots

Not applicable; this changes tutorial CLI behavior, scene lighting, and planner documentation.

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation
• Public API changes are reflected in the API docs (python docs/scripts/check_api_docs.py), if applicable
• I have added tests that prove my fix is effective or that my feature works
• Dependencies have been updated, if applicable.

Validation

• /root/miniconda3/envs/py311/bin/python -m pytest -q tests/sim/motion tests/sim/atomic_actions tests/compute/test_trajectory.py
  (1363 passed, 31 skipped, 12 deselected)
• /root/miniconda3/envs/py311/bin/python -m pytest -q tests/test_agent_context_map.py tests/test_agent_context_tools.py
  (23 passed)
• /root/miniconda3/envs/py311/bin/python docs/scripts/check_api_docs.py
  (1925/1925 exports documented)
• /root/miniconda3/envs/py311/bin/python -m pytest -q tests/sim/atomic_actions/test_tutorial_utils.py
  (77 passed)
• black ., compileall, git diff --check, and context affected-topic checks
  passed.
• Sphinx dummy build completed successfully; the repository's existing
  deprecation and cross-reference warnings remain non-fatal.

Known limitations

• dynamic_obstacle_recovery.py remains cuRobo-only because it updates a live
  collision world.
• Dual-arm tutorials currently reject cuRobo; control_dt.py intentionally
  retains its IK interpolation experiment, and exact Cartesian-linear phases
  remain IK-grounded.

[greptile-apps]

Confidence Score: 4/5

The PR is not yet safe to merge because the previously reported composite-phase timing defect remains outstanding.

Findings

1.  Timing Guarantees Are Lost ▶

Fix with agent prompt

### Issue 1
embodichain/lab/sim/atomic_actions/primitives/_helpers.py:140-143
When `TrapezoidalPlanner` returns its native samples and timing, this helper resamples only the positions to the composite phase's requested count and discards the planner's `dt`. Callers such as `Press` then execute the resulting positions at a fixed simulation control interval. If the Cartesian path produced more samples than requested, compressing it into a shorter, uniformly timed motion can make the executed joint velocities and accelerations exceed the limits used by the planner.

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Summary

• Supports toppra, trapezoidal, and curobo tutorial selection while retaining tutorial-specific backend restrictions.
• Preserves native trapezoidal samples through motion generation and fits planner positions into fixed-length composite phases.
• Replaces per-arena tutorial point lights with one global directional sun.
• Adds focused motion-generator, trajectory-resampling, primitive-helper, and tutorial-factory coverage.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  CLI["Tutorial --planner"] --> Factory["Shared motion-generator factory"]
  Factory --> TOPPRA["TOPPRA"]
  Factory --> Trap["Trapezoidal planner"]
  Factory --> Curobo["cuRobo"]
  TOPPRA --> MG["MotionGenerator"]
  Trap --> MG
  Curobo --> MG
  MG --> Composite["Composite atomic-action phase"]
  Composite --> Resample["Fit position path to phase count"]
  Resample --> Timed["Assemble timed full-robot trajectory"]

Loading

_{Reviews (3) · Last reviewed commit: "feat(atomic-actions): use one global sun..."}

[greptile-apps]

Timing Guarantees Are Lost

When TrapezoidalPlanner returns its native samples and timing, this helper resamples only the positions to the composite phase's requested count and discards the planner's dt. Callers such as Press then execute the resulting positions at a fixed simulation control interval. If the Cartesian path produced more samples than requested, compressing it into a shorter, uniformly timed motion can make the executed joint velocities and accelerations exceed the limits used by the planner.

Knowledge Base Used:

• Simulation lab
• Motion planning and kinematics

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/lab/sim/atomic_actions/primitives/_helpers.py
Line: 140-143

Comment:
**Timing Guarantees Are Lost**

When `TrapezoidalPlanner` returns its native samples and timing, this helper resamples only the positions to the composite phase's requested count and discards the planner's `dt`. Callers such as `Press` then execute the resulting positions at a fixed simulation control interval. If the Cartesian path produced more samples than requested, compressing it into a shorter, uniformly timed motion can make the executed joint velocities and accelerations exceed the limits used by the planner.

**Knowledge Base Used:**
- [Simulation lab](https://app.greptile.com/dexforce/-/custom-context/knowledge-base/dexforce/embodichain/-/docs/simulation-lab.md)
- [Motion planning and kinematics](https://app.greptile.com/dexforce/-/custom-context/knowledge-base/dexforce/embodichain/-/docs/motion-planning-and-kinematics.md)

---

For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.