# Task B EE-Camera Target Lock Pipeline

## Goal

Reduce the unstable blind-forward part of the current Task B reach policy.
The intended flow is:

1. Use the existing head-camera search/map policy to find a target and move near it.
2. When the head camera has centered the target and estimated it is within the EE-lock entry distance, switch to EE-camera lock.
3. Use only official online inputs:
   - `obs["image"]["ee_rgb"]`
   - `obs["image"]["ee_depth"]`
   - `obs["proprio"]`
4. Move the Piper arm to keep the target centered in the EE camera.
5. Rotate/walk the robot with a fast closed loop while the arm keeps lock.
6. At roughly `0.45-0.50 m` EE-camera depth, start the existing safe crouch and arm sweep.

## Non-Cheating Boundary

The online solution must not read simulator object poses, robot ground truth, or the seed.
The new EE path in `demo/solution_task_b_nav_only.py` is opt-in with:

```bash
ATEC_TASK_B_EE_LOCK_ENABLED=1
```

The default policy remains the previous head-camera path.

Offline dataset generation may reposition simulator objects and use generated labels because it is training/debug tooling, not submitted runtime logic.

## Added Files

- `scripts/generate_task_b_ee_lock_dataset.py`
  - Generates isolated EE-camera RGB examples.
  - Labels visibility, center error, depth, and conservative teacher servo commands.

- `scripts/train_task_b_ee_lock_model.py`
  - Trains a lightweight CNN.
  - Exports `model_ts.pt`, `checkpoint.pt`, `metrics.json`, and `prediction_contact_sheet.png`.

## Runtime Controller

The first implementation is deliberately conservative:

- Head camera still handles waypoint scan, object memory, and initial approach.
- EE lock starts only after a centered head-camera handoff inside `ATEC_TASK_B_EE_LOCK_ENTRY_DISTANCE`.
- EE camera detection uses legal `ee_rgb` and `ee_depth`.
- If `ATEC_TASK_B_EE_LOCK_MODEL=1` and `ATEC_TASK_B_EE_LOCK_MODEL_PATH` points to a TorchScript model,
  the EE detector first uses the trained full-frame lock model for visibility, center offset, depth, and class.
  If the model is missing or not confident, it falls back to the RGB-D mask detector.
- The arm updates joint-action targets to center the image target.
- The base rotates to unwind arm yaw and walks forward only when the target is centered.
- If EE lock reaches `ATEC_TASK_B_EE_LOCK_TARGET_DISTANCE`, the policy starts the existing safe crouch/sweep reach attempt.

## Why A Dataset Exists

The fast B2-Piper locomotion model is trained with RSL-RL.
The EE target-lock model starts with supervised visual-servo pretraining because pure pixel RL is slow and unstable:

- Offline simulator placement creates varied target views.
- Online-style EE RGB-D detection labels target visibility, center error, depth, and class.
- A simple teacher produces arm/base correction targets.
- Runtime still uses only official observations; no object ground truth, seed, or simulator pose is read.

After the supervised model can reliably keep the object centered, the next stage is single-target closed-loop validation
and optional RL/control fine-tuning around the real reach objective.

## Example Commands

Small smoke dataset:

```bash
micromamba run -n atec2026 python scripts/generate_task_b_ee_lock_dataset.py \
  --headless \
  --samples_per_class 20 \
  --background_samples 20 \
  --output outputs/datasets/task_b_ee_lock/smoke
```

Train:

```bash
micromamba run -n atec2026 python scripts/train_task_b_ee_lock_model.py \
  --data outputs/datasets/task_b_ee_lock/smoke \
  --output outputs/models/task_b_ee_lock/smoke \
  --epochs 5
```

Opt-in policy test:

```bash
ATEC_TASK_B_EE_LOCK_ENABLED=1 \
ATEC_TASK_B_EE_LOCK_MODEL=1 \
ATEC_TASK_B_EE_LOCK_MODEL_PATH=outputs/models/task_b_ee_lock/ee_lock_balanced_3000x3_20260629/model_ts.pt \
ATEC_TASK_B_STOP_ON_SERVICE=0 \
ATEC_SOLUTION_MODULE=demo.solution_task_b_nav_only \
micromamba run -n atec2026 python scripts/debug_task_b_seeded_play.py \
  --headless \
  --task ATEC-TaskB-B2Piper \
  --max_steps 6000 \
  --stop_on_reach_count 1 \
  --task_b_single_reach_scene \
  --task_b_single_reach_index 2 \
  --task_b_single_reach_body_x 1.0 \
  --task_b_single_reach_body_y 0.0
```

## Next Validation Gates

1. Compile/smoke test the new files.
2. Generate a small EE-lock dataset and inspect random images.
3. Train a first model and check validation center/depth errors.
4. Run single-target EE-lock trials before any full Task B run.
5. Only after single-target success is stable, integrate the trained model into the EE detector path.