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

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:

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

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.