feat(atomic-actions): improve upright grasp selection

[skywhite1024]

Replacement

Supersedes #540. The code is unchanged; this PR moves the head branch from the temporary codex/ namespace to ljd/gen-sim-atomic-prerequisite.

Stack

• Stack: #543
• Layer: 1/8
• Base: feat/cube-physical-recovery-gates
• Depends on: none
• Followed by: feat(scene-engine): add generated-scene authoring and editing #532

Description

This PR extracts the reusable Atomic Action prerequisite from GenSim PR #538. It adds object-aware upright grasp ranking before GraspKit top-k truncation, rejects top/bottom clamp poses for upright transport, and checks yaw-equivalent downstream targets without persisting grounded poses in task artifacts.

Dependencies: none. This should land before the rewritten GenSim semantic task-planning stack (#533-#538).

Refs #538

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

Validation

• black ./
• python docs/scripts/check_api_docs.py
• pytest tests/docs/test_check_api_docs.py -q --confcutdir=tests/docs
• pytest tests/sim/atomic_actions/test_affordance.py tests/sim/atomic_actions/test_primitives_helpers.py tests/sim/atomic_actions/test_actions.py tests/toolkits/test_grasp_pose_generator.py -q --disable-warnings --maxfail=1 (120 passed, 1 deselected)

Checklist

• I have run Black.
• Public API documentation coverage is aligned.
• I have added focused regression tests.
• No task-engine, controller, simulator-step, or duplicate runtime code is included.

[greptile-apps]

Greptile Summary

The PR adds object-aware upright grasp reranking, rejects top/bottom clamp poses, and samples yaw-equivalent downstream targets during feasibility checks.

• Adds a pre-truncation pose-cost callback to the grasp-generator API and antipodal backend.
• Ranks upright side grasps using closing-axis alignment and normalized grasp height.
• Extends downstream IK checks with configurable world-Z yaw variants.
• Adds focused callback, validation, and pose-variant tests.

Confidence Score: 4/5

The PR appears safe to merge, with a non-blocking need to document the newly exposed action option and grasp-generator callback.

The changed grasp-ranking and downstream feasibility paths are internally consistent, while the remaining accepted concern is limited to missing user-facing documentation for public API additions.

Files Needing Attention: embodichain/toolkits/graspkit/pose_generator.py; embodichain/lab/sim/atomic_actions/primitives/pick_up.py

Important Files Changed

Filename	Overview
embodichain/lab/sim/atomic_actions/primitives/pick_up.py	Adds upright side-grasp ranking, compatibility filtering, normalized upright directions, and yaw-equivalent downstream feasibility checks.
embodichain/toolkits/graspkit/pg_grasp/_antipodal_backend.py	Applies an optional validated cost callback before limiting collision-free grasps to the top candidates.
embodichain/toolkits/graspkit/pg_grasp/pose_generator.py	Forwards object-aware pose-cost callbacks from the batched generator to each backend invocation.
embodichain/toolkits/graspkit/pose_generator.py	Expands the public abstract grasp-generator interface, but the public documentation was not updated for implementors.
tests/sim/atomic_actions/test_actions.py	Updates the test generator stub to support object-aware pose-cost callbacks.
tests/sim/atomic_actions/test_primitives_helpers.py	Tests yaw-variant translation preservation and positive sample-count validation.
tests/toolkits/test_parallel_jaw_grasp_pose_generator.py	Verifies that object-aware costs are applied and returned by the antipodal generator.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart LR
A[Antipodal grasp candidates] --> B[Collision filtering and base costs]
B --> C[Object-aware upright cost callback]
C --> D[Top-k candidate truncation]
D --> E[Pickup path IK checks]
E --> F[Yaw-variant downstream IK checks]
F --> G[Selected feasible grasp]

Loading

Prompt To Fix All With AI

### Issue 1
embodichain/toolkits/graspkit/pose_generator.py:128-130
**Document the expanded public APIs**
The public `GraspPoseGenerator` interface now accepts `pose_cost_fn`, and `PickUpOptions` also exposes `upright_yaw_samples`, but the user-facing documentation does not describe either addition. This leaves callers unable to discover the new configuration and gives custom generator implementors no migration guidance for the expanded interface.
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

_{Reviews (1): Last reviewed commit: "Merge branch 'feat/cube-physical-recover..." | Re-trigger Greptile}

[greptile-apps]

Document the expanded public APIs

The public GraspPoseGenerator interface now accepts pose_cost_fn, and PickUpOptions also exposes upright_yaw_samples, but the user-facing documentation does not describe either addition. This leaves callers unable to discover the new configuration and gives custom generator implementors no migration guidance for the expanded interface.

Context Used: AGENTS.md (source)

Prompt To Fix With AI

This is a comment left during a code review.
Path: embodichain/toolkits/graspkit/pose_generator.py
Line: 128-130
Comment:
**Document the expanded public APIs**
The public `GraspPoseGenerator` interface now accepts `pose_cost_fn`, and `PickUpOptions` also exposes `upright_yaw_samples`, but the user-facing documentation does not describe either addition. This leaves callers unable to discover the new configuration and gives custom generator implementors no migration guidance for the expanded interface.
**Context Used:** AGENTS.md ([source](https://github.com/dexforce/embodichain/blob/main/AGENTS.md))
---
For each issue above, determine whether it is valid and should be fixed. If so, fix it directly.

Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!