# Bin-picking expert and simulator contract

This task uses the canonical MJLab UR5 CB3 and legacy OnRobot RG2 with the
approved D415/mount-v4 assembly. Bottle and tube-sort assets/contracts are not
changed. Run commands from the workspace root after `source env.sh`.

## Assembly and control

The D415 mesh, mount, factory calibration and reference assembly are copied to
`assets/d415`. The RGB centre in the RG2 frame is
`[-0.0024707697691, -0.0524847399704, 0.0304948260870]` metres. The original
1280×720 intrinsics scale to a 320×180 policy image. This intentionally differs
from the old D455 320×200 image; old visual checkpoints cannot be treated as
compatible. Factory intrinsics do not establish measured hand-eye calibration.

The camera has the source box collision proxy. Mount v4 additionally has a
conservative convex-hull collision proxy, including its empty openings. The
visible mount retains its original mass; the collision proxy adds no mass.
Camera visual geometry stays in the sensor-excluded group, as in its source.

The arm uses the existing bounded position-target IK controller at 1 kHz and
20 Hz Cartesian policy actions: translation scale 5 mm, rotation scale 1 degree,
`max_dq=0.025`, direction-preserving limits and bias compensation. Gripper action
is normalized position (-1 closed, +1 open), with unchanged kp=12, kv=0.4 and
actuator effort range [-3,3]. That actuator effort is not calibrated pad force
in newtons. No controller gains or object friction were increased for the expert.

## Expert

The expert searches grasp heights, 12 horizontal closing directions and five
tilts about the closing axis. Candidate widths and centres come from collision
mesh cross-sections, including triangle-edge intersections. A CPU kinematic
replica checks IK and robot/scene collision at the open grasp and sampled
vertical approach. Both pad meshes must intersect the target at predicted
closure. Width is measured within three candidate pad contact strips along each
cross-section. Wall clearance uses the posed collision geometry, not an untilted
finger rectangle. The replica does not move the live robot or objects. This
is a sampled feasibility check, not a continuous collision-free motion proof.

The live robot executes Cartesian actions, closes against the original effort
bound, lifts, monitors object-relative motion, carries above the rim, lowers
near the table, releases and verifies the placement. Motion timeouts and slips
trigger opening and vertical recovery. Successful placement is followed by
vertical retreat before selecting another object. There is no prescribed pick
order. A slipped object resting on the reachable tabletop remains eligible for
regrasp and verified delivery. Objects are placed by the pourer only during initialization.

Success requires the released object's geometry to be outside the bin, near the
drop destination, supported near the tabletop, and moving slowly. Reaching the
drop point alone is not a success. `finished` includes exhausted grasp candidates;
only `bin_cleared` means every poured object was successfully deposited.

## Physics-only evaluation

```
python scripts/evaluate_binpick.py --num-envs 4 --objects 12 --max-steps 3600 \
  --bin-width .14 --bin-height .06 \
  --device cuda:1 --output reports/binpick_expert/new_run
python -m pytest tests/test_binpick.py tests/test_tubesort_expert.py -q
```

The command tests a 400×140×60 mm internal bin. Geometry changes are authorized;
this is a development candidate, not a validated hardware recommendation.
Without overrides the historical 400×128×150 mm bin remains the default.
Shallower walls change the pourer's stopping height and thus object count;
compare actual poured counts rather than requested capacity.

The default `--videos 0` removes camera sensors and camera observations and
disables rendering. Reports include source snapshots, transitions, planning
rejections, failure reasons, physics metrics and final states. Use fresh output
directories. GPU pile dynamics are not bitwise deterministic: counts and object
poses can differ between runs even with the same seed.

With videos enabled, both cameras use Gaussian room backgrounds. External
foreground comes from a read-only MuJoCo pose replica, with opaque bin walls
and the D415 housing visible. `video_poses.npz` saves each recorded frame's qpos
at 4 fps for later re-rendering. The rendering path never steps live physics.

Current limits include wall-blocked objects, failed force closures on irregular
meshes, approximate physical parameters and conservative mount geometry. A
privileged planner cannot guarantee that every object has an accessible grasp.
The expert currently does not deliberately rearrange the pile. RL task design,
demonstration collection, rendering and website publication are separate steps.
