Add Franka drawer manipulation tutorial

[yuecideng]

Description

This PR adds a contact-rich manipulation tutorial in which a Franka Panda uses MotionGenerator trajectories to grasp a passive drawer, pull it open, and push it halfway closed.

It includes:

• a batched executable tutorial with seeded IK and TOPPRA trajectory generation;
• a 90-degree local-TCP grasp rotation and an Enter-to-execute safety gate;
• phase-level feedback based on measured drawer state;
• optional fixed-camera headless MP4 recording;
• a teaching-focused Sphinx page with an embedded recording, poster, and reproduction commands.

Dependencies: None.

No linked issue.

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

Watch or download the recorded MP4

Validation

• black . — 657 files unchanged
• python -m py_compile scripts/tutorials/sim/open_drawer.py
• CPU headless end-to-end simulation — 16.06 cm pull, 8.11 cm final opening
• CUDA headless recording — 16.64 cm pull, 8.63 cm final opening
• H.264 MP4 full-stream decode validation
• python -m sphinx -b html docs/source docs/build/html -q — passed with pre-existing repository warnings
• Built HTML video, poster, and download targets verified

Checklist

• I have run the black . command to format the code base.
• I have made corresponding changes to the documentation.
• I have added tests that prove my fix is effective or that my feature works. No pytest test was added; the executable tutorial was validated end to end on CPU and CUDA.
• Dependencies have been updated, if applicable. No dependency changes are required.

[greptile-apps]

Greptile Summary

The PR adds an executable Franka tutorial that plans batched approach, pull, and push trajectories against a passive drawer, validates success from measured drawer state, and optionally records headless execution. It also adds a teaching-focused Sphinx page, tutorial navigation, and associated video and poster assets.

• Adds seeded IK and TOPPRA trajectory generation for contact-rich drawer manipulation.
• Adds phase-level feedback and per-environment object-state validation.
• Adds optional fixed-camera MP4 recording with command-line validation.
• Documents the control flow, frame conventions, execution steps, and troubleshooting guidance.

Confidence Score: 5/5

The PR appears safe to merge; no concrete blocking or independently actionable non-blocking issue was identified.

The planner sampling and playback shapes match repository contracts, articulation creation follows its non-optional API, and the optional recording path safely handles directory creation and partial lifecycle cleanup.

Important Files Changed

Filename	Overview
scripts/tutorials/sim/open_drawer.py	Adds a complete batched simulation tutorial with scene setup, seeded IK, TOPPRA planning, contact-phase execution, measured-state validation, argument checks, and safe recorder cleanup; no actionable defect was identified.
docs/source/tutorial/robot_articulation.rst	Adds comprehensive tutorial documentation aligned with the executable example, including frame conventions, control boundaries, reproduction commands, and troubleshooting.
docs/source/tutorial/index.rst	Inserts the new tutorial into the learning sequence and Sphinx toctree while consistently renumbering subsequent entries.
docs/source/_static/tutorials/open_drawer.mp4	Adds the tutorial recording referenced by the new Sphinx page.
docs/source/_static/tutorials/open_drawer_poster.jpg	Adds the poster image used by the embedded tutorial video.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Create Franka and passive drawer] --> B[Read live handle pose]
    B --> C[Build pre-grasp and grasp poses]
    C --> D[Seeded inverse kinematics]
    D --> E[TOPPRA arm trajectory]
    E --> F[Execute approach]
    F --> G[Close gripper and settle contact]
    G --> H[Re-read handle pose]
    H --> I[Plan and execute pull]
    I --> J[Measure achieved drawer opening]
    J --> K{Opening meets threshold?}
    K -- No --> L[Raise task failure]
    K -- Yes --> M[Plan push from measured opening]
    M --> N[Execute half-close push]
    N --> O{Final opening within tolerance?}
    O -- No --> L
    O -- Yes --> P[Hold final pose and save recording]

Loading

_{Reviews (1): Last reviewed commit: "feat(tutorial): add Franka drawer manipu..." | Re-trigger Greptile}