# Sample Export + Visual Tuning

These tools run occluder export headlessly and optimize with both GT metrics and a visual-quality heuristic.

## Ground Truth Masks

- Location: `screenshots/sample_masks`
- Match rule: sample basename -> `.png` (or `.mask.png`)
- Format: grayscale, `255 = occluder`, `0 = background`

## `run_sample_export`

Runs one sample and writes a full visual review package.

```bash
node tools/run_sample_export.js \
  --sample 7xm.xyz332401_1024.jpg \
  --sample-dir screenshots/sample_images \
  --gt-dir screenshots/sample_masks \
  --out runs/sample_export/latest \
  --debug 1
```

### Key outputs per run

- `final_output.png`
- `predMask.png`, `occluderMask.png`, `gtMask.png`, `diff.png`
- `fn_overlay.png`, `fp_overlay.png`, plus `error_crops/*`
- `review.png` (one-page montage)
- `review.md` (top issues with crop thumbnails)
- `review.json` (machine-readable issue list)
- `metrics.json` (includes visual fields)

Note on reproducibility:
- `analyze_response.json` is saved as a raw snapshot now (before render-time transforms), so re-renders from this file are stable.

Note on SAM patch runner:
- `run_sample_export` now auto-prefers `./.venv_sam_patch/bin/python` (then `./.venv/bin/python`) when available.
- You can still override with `OCCLUDER_SAM_PATCH_PY=/path/to/python`.

### Visual fields in `metrics.json`

- `visual_score` / `visualScore`
- `visualThreshold`
- `visualPass`
- `visualIssueCount`
- `fnBoundaryMissRate`
- `fpOutsideTileCoverage`
- `samPatchApplied`, `samPatchFailed`, `samPatchTrimIterations`, `samPatchMaxAddedPixels`
- `samPatchToolFailed` (local SAM patch runner failed and fallback path was used)

### Experimental Alternative Strategies

You can toggle additional headless-only refinement paths through `--occluder-env`:

- Option B candidate union:
  - `OCCLUDER_ALT_UNION_ENABLED=1`
  - unions `mask_versions.normalized` with prompted SAM candidate (when available), then prunes additions with edge + adjacency constraints.
- Option A edge-guided thin-detail recovery:
  - `OCCLUDER_ALT_EDGE_RECOVERY_ENABLED=1`
  - recovers from `mask_versions.raw` deltas using RGB-edge support and component budgets.
- Option C higher analysis resolution:
  - `OCCLUDER_ANALYZE_UPSCALE=1.25` (or `1.5`, etc.)
  - upscales image before API analyze call, then resizes outputs back to sample resolution.
- Option E spill-prune (FP-focused on shelves/counter-like regions):
  - `OCCLUDER_ALT_SPILL_PRUNE_ENABLED=1`
  - removes occluder components that are weakly anchored to tile region + tile band.
  - prune acceptance now includes optional recall guard (when GT exists in sample export):
    - `OCCLUDER_ALT_SPILL_PRUNE_RECALL_GUARD_ENABLED` (default `1` for GT eval)
    - `OCCLUDER_ALT_SPILL_PRUNE_MAX_FN_INCREASE_PIXELS` (default `2000`)
    - `OCCLUDER_ALT_SPILL_PRUNE_MAX_FN_INCREASE_FRAC` (default `0.025`)
  - if guard fails, prune is rolled back with:
    - `occluder_meta.altSpillPrune.reason = rollback_recall_guard`
  - key knobs:
    - `OCCLUDER_ALT_SPILL_PRUNE_ANCHOR_DILATE`
    - `OCCLUDER_ALT_SPILL_PRUNE_BAND_TOP_PAD`
    - `OCCLUDER_ALT_SPILL_PRUNE_BAND_BOTTOM_PAD`
    - `OCCLUDER_ALT_SPILL_PRUNE_MIN_TILE_FRAC`
    - `OCCLUDER_ALT_SPILL_PRUNE_MIN_ANCHOR_FRAC`
    - `OCCLUDER_ALT_SPILL_PRUNE_MIN_BAND_FRAC`
    - `OCCLUDER_ALT_SPILL_PRUNE_MIN_REMOVE_COMP_AREA`

Recommended GT-tuning profile (strict recall guard):
- `OCCLUDER_ALT_SPILL_PRUNE_ENABLED=1`
- `OCCLUDER_ALT_SPILL_PRUNE_RECALL_GUARD_ENABLED=1`
- `OCCLUDER_ALT_SPILL_PRUNE_MAX_FN_INCREASE_PIXELS=2000`
- `OCCLUDER_ALT_SPILL_PRUNE_MAX_FN_INCREASE_FRAC=0.025`

Example:

```bash
node tools/run_sample_export.js \
  --sample ComfyUI_01234_.png \
  --sample-dir screenshots/sample_images \
  --gt-dir screenshots/sample_masks \
  --out runs/sample_export/alt_probe \
  --debug 1 \
  --occluder-env '{"OCCLUDER_ALT_EDGE_RECOVERY_ENABLED":1,"OCCLUDER_ALT_EDGE_RECOVERY_EDGE_Q":0.76}'
```

## `auto_tune_occluder`

Tunes against both metric score and visual score, supports multi-sample runs, and re-runs the best candidate into per-sample best folders.

```bash
node tools/auto_tune_occluder.js \
  --samples 7xm.xyz332401_1024.jpg,ComfyUI_01234_.png \
  --sample-dir screenshots/sample_images \
  --gt-dir screenshots/sample_masks \
  --out runs/sample_export/live_visual_tune \
  --max-iter 20 \
  --no-improve-limit 6 \
  --visual-threshold 72 \
  --rerun-analysis 1
```

### Stop behavior

The loop stops when either:

1. Visual threshold is reached for all samples, or
2. No aggregate improvement for `--no-improve-limit` rounds and visual issues remain, or
3. `--max-iter` is reached.

If visual threshold is not reached, the tuner writes `iters/NO_IMPROVEMENT.md` with evidence per sample.

Recall-guarded candidate acceptance:
- Tuner now enforces spill-prune recall guard during candidate selection.
- If an applied spill-prune candidate exceeds FN guard thresholds, it is hard-rejected from best-candidate promotion.
- Control with `OCCLUDER_TUNER_ENFORCE_SPILL_RECALL_GUARD=1` (default on).
- Telemetry fields:
  - `spillRecallGuardPass` (candidate-level)
  - `spillRecallGuardFailures` (sample-level FN increase vs threshold evidence)

### Tuner outputs

- `iters/iters.csv`, `iters/iters.md`, optional `iters/NO_IMPROVEMENT.md`
- `latest/<sampleKey>/...` for current baseline eval
- `iter_<n>_<key>_<dir>/<sampleKey>/...` for each candidate
- `best/<sampleKey>/...` with final artifacts (including `review.png` + `review.md`)
- `best/best_params.json`
- `summary.md`, `summary.json`

## Interpreting visual review

- Goal: foreground objects on backsplash are white in occluder mask; backsplash background stays black.
- `review.png`: quick visual montage (final output, masks, FN/FP overlays, issue panels).
- `review.md`: top 5 visual failures with thumbnails.
- Tune for lower FN object misses first, then suppress FP spill and edge artifacts.

## TileMask v3 (backsplash ROI hard samples)

TileMask v3 is a grid + seam + occluder region constructor for backsplash ROI on low-contrast white-on-white scenes.

### Batch export (samples A-E)

```bash
TS_NODE_TRANSPILE_ONLY=1 npx ts-node -r tsconfig-paths/register -P tsconfig.scripts.json tools/run_tilemask_v3_batch.ts
```

Outputs:
- `runs/sample_export/tilemask_v3_batch_<timestamp>/<sample>/...`
- `out/tilemask_v3_delta.md`
- `out/README_tileMask_v3.md`

Per-sample files include:
- `final_output.png`
- `tile_mask_raw.png`
- `tile_mask_grid.png`
- `tile_mask_final.png`
- `tile_bounds_overlay.png`
- `debug_montage.png`
- `metrics.json`, `summary.md`

### Regression / holdout gate (A-E)

```bash
TS_NODE_TRANSPILE_ONLY=1 npx ts-node -r tsconfig-paths/register -P tsconfig.scripts.json tools/regress_tilemask_v3.ts
```

This runs the v3 batch and fails on heuristic regressions (coverage explosions/collapses, seam missing, spill proxy too high, fragmentation too high).

### Holdout expansion runner (TileMask v3)

```bash
TS_NODE_TRANSPILE_ONLY=1 npx ts-node -r tsconfig-paths/register -P tsconfig.scripts.json tools/run_tilemask_v3_holdout.ts
```

Outputs:
- `runs/sample_export/tilemask_v3_holdout_<timestamp>/HOLDOUT_REPORT.md`
- `runs/sample_export/tilemask_v3_holdout_<timestamp>/HOLDOUT_REPORT.json`
- `runs/tilemask_v3/LATEST.md` (compact latest summary)

Useful flags:
- `--list <path>`: use a custom holdout image list JSON (array of sample-relative paths)
- `--timeout-ms <ms>`: per-sample exporter timeout (default `180000`)
- `--continue-on-error 0|1`: continue and write `export_error` rows instead of aborting the whole run (default `1`)

Examples:

```bash
# Custom list + longer timeout
TS_NODE_TRANSPILE_ONLY=1 npx ts-node -r tsconfig-paths/register -P tsconfig.scripts.json \
  tools/run_tilemask_v3_holdout.ts \
  --list tools/tilemask_v3_holdout_list.json \
  --timeout-ms 300000
```

```bash
# Fail fast on first exporter error
TS_NODE_TRANSPILE_ONLY=1 npx ts-node -r tsconfig-paths/register -P tsconfig.scripts.json \
  tools/run_tilemask_v3_holdout.ts \
  --continue-on-error 0
```