docs/REPRODUCIBLE_PIPELINE.md

# Reproducible AccessPath pipeline

`python accesspath.py pipeline` is the complete single-image execution path.
It is a finite Slurm GPU job: it submits one image, writes persistent outputs,
and releases the GPU allocation at completion or failure.

## Execution graph

```text
RGB image
  -> SAM 3 target/obstacle proposals (or validated reviewed visible mask)
  -> constrained hidden/amodal mask proposal
  -> mask and geometry preflight
  -> GPU 2D inpainting candidates and deterministic quality selection
  -> depth/point cloud/category-geometry diagnostics
  -> visual 3D completion through the upstream Amodal3R backend
  -> verification, turntable, and compact review bundle
```

Automatic masks and generated completions are review candidates, not ground
truth, metric geometry, or navigation-safety labels.

## Required runtime assets

Set paths through environment variables rather than editing repository files:

```bash
export SAM3_PYTHON=/path/to/sam3/python
export SAM3_REPO=/path/to/sam3/source
export SAM3_CHECKPOINT=/path/to/sam3/checkpoint.pt
export AMODAL3D_PYTHON=/path/to/amodal3r/python
export AMODAL_CHECKPOINT=/path/to/accesspath-amodal-mask-adapter.pt
export DEPTH_REPO=/path/to/Depth-Anything-V2
export DEPTH_CHECKPOINT=/path/to/depth-checkpoint.pth
export SD_MODEL=/path/to/stable-diffusion-inpainting
export AMODAL3D_MODEL=Sm0kyWu/Amodal3R
```

The optional `REVIEWED_VISIBLE_WORKSPACE` route bypasses automatic mask
proposal only when a validated reviewed mask workspace is supplied. All
checkpoint paths above are local user assets and are intentionally absent from
the repository.

## Submit one image

```bash
python accesspath.py pipeline -- \
  --image path/to/image.jpg \
  --category stairs \
  --output-dir output/stairs_demo
```

Add `--no-wait` to return after Slurm submission, `--no-2d` to skip inpainting,
or `--no-generative-3d` to skip the upstream visual-3D stage. The command
prints the job identifier and paths to persisted review artifacts.

## Output review order

1. `00_quick_review/overview.jpg` — compact original/2D/3D comparison.
2. `01_sam3/` or `01_reviewed_visible/` — target and obstacle mask evidence.
3. `02_masks/` — visible, hidden, amodal, and obstacle masks.
4. `03_2d_completion/` — candidates, selection manifest, and selected RGB.
5. `04_3d_completion/` — depth and geometry diagnostics.
6. `accessibility3d/` — upstream Amodal3R visual-3D assets.
7. `05_quality_checks/` — preflight and final verification reports.

The job wrapper uses portable project-relative paths and sanitizes persisted
logs and text metadata. It never attempts to anonymize people or sensitive
content visible in the input image.